Mindmap MCP Server

🧠 Mind Map — MCP memory & context-handoff server

Ever lose the thread of a discussion across Claude Code, Claude Desktop, and your other AI tools? Mind Map is a small, local-first MCP server that acts as a shared memory layer across all your local MCP clients.

You capture context at the end of a session, and resume it in any other tool — no more re-explaining your project from scratch. Memory you stop using cools and decays gracefully into one-line traces (it's never silently deleted), so your shelf stays small and trustworthy instead of becoming another haystack.

Local-first by design. It runs on your machine; your memories are plain

files in ~/.mindmap that never leave your control. No account, no cloud, no

server to trust. Install once with npx @ravi-labs/mindmap-mcp-server install.

_ChatGPT and other cloud/web clients are out of scope for now — they can't

reach a local server without a public endpoint, which conflicts with

local-first. See Future._

The idea in one loop

1. Capture (effortless) — at the end of a discussion, save a portable summary.
2. Resume (promote-on-reuse) — pull it forward in a new session. The act of reusing it is what promotes it to *trusted* memory. Throwaway sessions never get promoted, so they never clutter your shelf.
3. Consolidate (automatic) — a background pass cools unused memory through tiers (🔥 hot → 🌤️ warm → ❄️ cold) and collapses cold items to a searchable one-line trace. The moat isn't storing things — it's forgetting well.
4. Tidy (opt-in, gamified) — a *cleanliness score* rewards pruning, not hoarding.

Install (one command)

Once published to npm, the whole install is:

npx @ravi-labs/mindmap-mcp-server install

This auto-detects your local MCP clients (Claude Desktop, Cursor, Windsurf) and writes the config for you, and configures Claude Code via its CLI if present. Restart your client and Mind Map's tools are there. Preview first with npx @ravi-labs/mindmap-mcp-server install --dry-run; undo with npx @ravi-labs/mindmap-mcp-server uninstall.

Data lives in ~/.mindmap/ by default — override with the MINDMAP_DIR env var.

Manual setup (if you prefer)

Every client uses the same command — npx -y @ravi-labs/mindmap-mcp-server over stdio.

Claude Code:

claude mcp add mindmap -- npx -y @ravi-labs/mindmap-mcp-server

Claude Desktop — edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{

"mcpServers": { "mindmap": { "command": "npx", "args": ["-y", "@ravi-labs/mindmap-mcp-server"] } } }

Cursor / Windsurf / other clients — same command + args shape in that client's MCP config. Add an env block to relocate data:

{ "command": "npx", "args": ["-y", "@ravi-labs/mindmap-mcp-server"],

"env": { "MINDMAP_DIR": "/path/to/my/memory" } }

From source (development)

git clone https://github.com/ravi-labs/mindmap-mcp-server.git && cd mindmap-mcp-server

npm install && npm run build node dist/index.js install --local # points clients at this checkout

Using it day to day

Just talk naturally inside your AI tool — the model calls the right tool:

• "Save this to mind map" → captures the current context
• "Resume my work on \ " → pulls it back into a fresh session
• "What's in my mind map?" / "Show my mind map health" → browse / score
• "What do you know about how I work?" → reads your persona (see below)
• "Brainstorm \ with me" → loads your prior thinking so ideas continue across tools
• "Add this to my Goals" / "park this for later" → files it into a collection
• "What apps did I start and never finish?" → auto-organizes your memory into collections
• "Continue one of my unfinished projects" → pick one, and you're back in the right folder at the exact next step

Run npx @ravi-labs/mindmap-mcp-server quickstart for the full getting-started guide.

Brainstorm across tools

Start an idea in Claude, keep going in Cursor — without re-explaining it. Mind Map is the shared memory; each tool brings its own brainstorming muscle. mindmap_brainstorm loads your persona and prior idea-threads on the topic, you brainstorm, and saving with kind: "brainstorm" lets it resume anywhere. A bundled brainstorm Skill (installed into ~/.claude/skills by install) wires the load → brainstorm → save flow for Claude.

Organize it your way — Collections

Mind Map always organizes automatically (recency tiers, source, topic, workspace). Collections are your own layer on top: named groups like 🎯 Goals, 🅿️ Parking Lot, ✅ Decisions — or anything you invent. Say *"add this to my Goals"* or *"park this"* in any tool, or use the dashboard's Organize tab.

Two things make collections more than folders:

• Filing protects from decay. A memory in a pinned collection won't be forgotten while it's filed — parking something is a signal it matters. (An explicit "forget this" still wins.)
• Every collection is a launcher. *"Continue one of my unfinished projects"* lists them — each with its 📂 workspace and *↳ where you left off* — pick one and mindmap_resume drops you back in: full topic context, right folder, exact next step.

Don't want to file things by hand? Auto-organize reads across *all* your sessions and proposes collections — it always looks for unfinished projects (started building, went cold, never shipped), Goals, Decisions, and parked ideas, plus anything you ask for (*"everything about billing"*). It only suggests; nothing is filed until you accept. Uses your own LLM if configured, otherwise a no-key heuristic.

Make capture automatic

For Claude Code, install adds a `SessionEnd` auto-capture hook — every substantive session is distilled into a memory automatically, so you never have to remember to save. It's deduped (resuming + re-ending updates in place) and skips trivial/automated sessions. Opt out with install --no-hook; it's removed cleanly by uninstall.

For other clients (or as a belt-and-braces nudge), add one line to your client's instructions (e.g. Claude Code's CLAUDE.md):

At the end of a substantive session, call mindmap_capture to save the context.

When I reference past work, call mindmap_resume first.

The tools are also described to encourage the model to do this proactively.

Bring in your past sessions

Import your existing Claude history into Mind Map — distilled, not raw dumps:

npx @ravi-labs/mindmap-mcp-server import --dry-run   # preview

npx @ravi-labs/mindmap-mcp-server import # apply

Covers Claude Code (CLI — full prompts), Cowork (title + opening message), VS Code Copilot (full prompts), and Cursor (chat titles + prompts); each memory is tagged by source. Filters: --source code|cowork|copilot|cursor, --project , --limit N. Imported memories keep their original dates, so old ones settle into cold traces automatically.

Imported memories capture the discussion (your prompts + the assistant's substantive answers), not just titles — for the transcript-backed sources (Claude Code, Cursor, Copilot). Re-run with --reimport to refresh existing memories in place after an upgrade.

Notes:

• Cursor stores chats in a (often multi-GB) SQLite DB, read via Node's built-in SQLite — so Cursor import needs Node 22.5+ (other sources don't).
• ChatGPT and Claude.ai web chats can't be imported — they live in the cloud, not local files. (A future "import from data-export file" is planned.)

Tidy up

npx @ravi-labs/mindmap-mcp-server cleanup --dry-run   # preview

npx @ravi-labs/mindmap-mcp-server cleanup # apply

Removes automated/scheduled-task memories and collapses duplicate sessions. Anything you've promoted is always kept.

Persona — a profile every tool can read

Beyond individual discussions, Mind Map keeps a persona: a distilled, evolving profile of *how you work* — your stack, style, communication preferences, and constraints — so any tool can apply it and stop re-asking the same setup questions. It's separate from your discussion memories.

• Declared facts: tell a tool *"I prefer concise, code-first answers"* and it calls mindmap_persona_set. High confidence, yours, editable.
• Inferred facts: mindmap_persona_learn derives recurring signals from your existing memories. No LLM needed (keyword heuristic); richer if you enable one.
• Tools call mindmap_persona at the start of a session and apply what's there.

Add this to your client's instructions so it happens automatically:

At the start of a session call mindmap_persona and apply it. When I state a

durable preference, call mindmap_persona_set.

Own your context

A memory you can't extract, inspect, or carry isn't a memory you own. Three features make Mind Map's memory genuinely yours:

Memory Passport — export everything to one portable, open file, and pull your context *out of the walled gardens*:

npx @ravi-labs/mindmap-mcp-server passport export                 # → ~/mindmap-passport-<date>.json

npx @ravi-labs/mindmap-mcp-server passport import # from another machine npx @ravi-labs/mindmap-mcp-server passport import-chatgpt conversations.json # your ChatGPT export npx @ravi-labs/mindmap-mcp-server passport import-claude conversations.json # your Claude.ai export

The cloud chats can't be reached live from a local server — but their data export files are yours, and this imports them as distilled memories.

Glass-box memory — see exactly what's stored and why:

npx @ravi-labs/mindmap-mcp-server audit

Every memory shows its provenance (where it came from), trust (how many times you reused it), and decay forecast (when it fades to a one-line trace). In the dashboard, each memory has a one-click Forget. Unlike opaque vector stores, nothing about your memory is hidden from you.

Persona projection — write your persona into each tool's own config, so even non-MCP tools know how you work:

npx @ravi-labs/mindmap-mcp-server persona-sync          # Claude, Cursor, Copilot, Windsurf

It edits only a managed block ( …:end), so your own content is never touched.

Optional: bring your own LLM key

Mind Map runs fully without any LLM — every feature has a no-LLM path. If you *want* smarter persona inference and topic-graph labels, plug in your own provider (anthropic, openai, google, or local ollama). It's opt-in and graceful: no key, or a failed call, simply falls back to the no-LLM path, and any cost notes are rough estimates — never a bill.

Mind Map never stores your API key. It saves only the provider + model name in ~/.mindmap/llm.json; the key is read from an environment variable at call time. You set the key; Mind Map just reads it.

Smarter search (optional). Search is BM25 out of the box — no LLM needed. With an embeddings-capable provider (OpenAI, Google, or Ollama — Anthropic has no embeddings API), build a local embedding cache for hybrid search (BM25 fused with semantic similarity via reciprocal rank fusion):

npx @ravi-labs/mi