{
  "markdown": "# 🧠 Mind Map — MCP memory & context-handoff server\n\n[![npm](https://img.shields.io/npm/v/@ravi-labs/mindmap-mcp-server?logo=npm)](https://www.npmjs.com/package/@ravi-labs/mindmap-mcp-server)\n[![CI](https://github.com/ravi-labs/mindmap-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ravi-labs/mindmap-mcp-server/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/node/v/@ravi-labs/mindmap-mcp-server)](https://nodejs.org)\n\nEver lose the thread of a discussion across Claude Code, Claude Desktop, and your\nother AI tools? Mind Map is a small, **local-first** [MCP](https://modelcontextprotocol.io)\nserver that acts as a **shared memory layer** across all your local MCP clients.\n\nYou **capture** context at the end of a session, and **resume** it in any other\ntool — no more re-explaining your project from scratch. Memory you stop using\n**cools and decays gracefully** into one-line traces (it's never silently\ndeleted), so your shelf stays small and trustworthy instead of becoming another\nhaystack.\n\n> **Local-first by design.** It runs on your machine; your memories are plain\n> files in `~/.mindmap` that never leave your control. No account, no cloud, no\n> server to trust. Install once with `npx @ravi-labs/mindmap-mcp-server install`.\n\n> _ChatGPT and other cloud/web clients are out of scope for now — they can't\n> reach a local server without a public endpoint, which conflicts with\n> local-first. See [Future](#future)._\n\n## The idea in one loop\n\n1. **Capture** (effortless) — at the end of a discussion, save a portable summary.\n2. **Resume** (promote-on-reuse) — pull it forward in a new session. The act of\n   reusing it is what promotes it to *trusted* memory. Throwaway sessions never\n   get promoted, so they never clutter your shelf.\n3. **Consolidate** (automatic) — a background pass cools unused memory through\n   tiers (🔥 hot → 🌤️ warm → ❄️ cold) and collapses cold items to a searchable\n   one-line trace. The moat isn't storing things — it's **forgetting well**.\n4. **Tidy** (opt-in, gamified) — a *cleanliness score* rewards pruning, not\n   hoarding.\n\n## Install (one command)\n\nOnce published to npm, the whole install is:\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server install\n```\n\nThis **auto-detects** your local MCP clients (Claude Desktop, Cursor, Windsurf)\nand writes the config for you, and configures **Claude Code** via its CLI if\npresent. Restart your client and Mind Map's tools are there. Preview first with\n`npx @ravi-labs/mindmap-mcp-server install --dry-run`; undo with\n`npx @ravi-labs/mindmap-mcp-server uninstall`.\n\nData lives in `~/.mindmap/` by default — override with the `MINDMAP_DIR` env var.\n\n### Manual setup (if you prefer)\n\nEvery client uses the same command — `npx -y @ravi-labs/mindmap-mcp-server` over stdio.\n\n**Claude Code:**\n\n```bash\nclaude mcp add mindmap -- npx -y @ravi-labs/mindmap-mcp-server\n```\n\n**Claude Desktop** — edit `claude_desktop_config.json`\n(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mindmap\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ravi-labs/mindmap-mcp-server\"]\n    }\n  }\n}\n```\n\n**Cursor / Windsurf / other clients** — same `command` + `args` shape in that\nclient's MCP config. Add an `env` block to relocate data:\n\n```json\n{ \"command\": \"npx\", \"args\": [\"-y\", \"@ravi-labs/mindmap-mcp-server\"],\n  \"env\": { \"MINDMAP_DIR\": \"/path/to/my/memory\" } }\n```\n\n### From source (development)\n\n```bash\ngit clone https://github.com/ravi-labs/mindmap-mcp-server.git && cd mindmap-mcp-server\nnpm install && npm run build\nnode dist/index.js install --local   # points clients at this checkout\n```\n\n## Using it day to day\n\nJust talk naturally inside your AI tool — the model calls the right tool:\n\n- **\"Save this to mind map\"** → captures the current context\n- **\"Resume my work on \\<topic\\>\"** → pulls it back into a fresh session\n- **\"What's in my mind map?\"** / **\"Show my mind map health\"** → browse / score\n- **\"What do you know about how I work?\"** → reads your **persona** (see below)\n- **\"Brainstorm \\<topic\\> with me\"** → loads your prior thinking so ideas continue across tools\n- **\"Add this to my Goals\"** / **\"park this for later\"** → files it into a **collection**\n- **\"What apps did I start and never finish?\"** → auto-organizes your memory into collections\n- **\"Continue one of my unfinished projects\"** → pick one, and you're back in the right folder at the exact next step\n\nRun `npx @ravi-labs/mindmap-mcp-server quickstart` for the full getting-started guide.\n\n### Brainstorm across tools\n\nStart an idea in Claude, keep going in Cursor — without re-explaining it. Mind Map is\nthe **shared memory**; each tool brings its own brainstorming muscle. `mindmap_brainstorm`\nloads your persona and prior idea-threads on the topic, you brainstorm, and saving with\n`kind: \"brainstorm\"` lets it resume anywhere. A bundled **brainstorm Skill** (installed\ninto `~/.claude/skills` by `install`) wires the load → brainstorm → save flow for Claude.\n\n### Organize it your way — Collections\n\nMind Map always organizes automatically (recency tiers, source, topic, workspace).\n**Collections** are your own layer on top: named groups like 🎯 Goals, 🅿️ Parking\nLot, ✅ Decisions — or anything you invent. Say *\"add this to my Goals\"* or *\"park\nthis\"* in any tool, or use the dashboard's **Organize** tab.\n\nTwo things make collections more than folders:\n\n- **Filing protects from decay.** A memory in a pinned collection won't be\n  forgotten while it's filed — parking something is a signal it matters. (An\n  explicit \"forget this\" still wins.)\n- **Every collection is a launcher.** *\"Continue one of my unfinished projects\"*\n  lists them — each with its 📂 workspace and *↳ where you left off* — pick one\n  and `mindmap_resume` drops you back in: full topic context, right folder,\n  exact next step.\n\nDon't want to file things by hand? **Auto-organize** reads across *all* your\nsessions and proposes collections — it always looks for **unfinished projects**\n(started building, went cold, never shipped), Goals, Decisions, and parked\nideas, plus anything you ask for (*\"everything about billing\"*). It only\nsuggests; nothing is filed until you accept. Uses your own LLM if configured,\notherwise a no-key heuristic.\n\n### Make capture automatic\n\nFor **Claude Code**, `install` adds a **`SessionEnd` auto-capture hook** — every\nsubstantive session is distilled into a memory automatically, so you never have\nto remember to save. It's deduped (resuming + re-ending updates in place) and\nskips trivial/automated sessions. Opt out with `install --no-hook`; it's removed\ncleanly by `uninstall`.\n\nFor other clients (or as a belt-and-braces nudge), add one line to your client's\ninstructions (e.g. Claude Code's `CLAUDE.md`):\n\n> At the end of a substantive session, call `mindmap_capture` to save the context.\n> When I reference past work, call `mindmap_resume` first.\n\nThe tools are also described to encourage the model to do this proactively.\n\n## Bring in your past sessions\n\nImport your existing Claude history into Mind Map — distilled, not raw dumps:\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server import --dry-run   # preview\nnpx @ravi-labs/mindmap-mcp-server import             # apply\n```\n\nCovers **Claude Code** (CLI — full prompts), **Cowork** (title + opening\nmessage), **VS Code Copilot** (full prompts), and **Cursor** (chat titles +\nprompts); each memory is tagged by source. Filters: `--source code|cowork|copilot|cursor`,\n`--project <name>`, `--limit N`. Imported memories keep their original dates, so\nold ones settle into cold traces automatically.\n\nImported memories capture the **discussion** (your prompts + the assistant's\nsubstantive answers), not just titles — for the transcript-backed sources\n(Claude Code, Cursor, Copilot). Re-run with `--reimport` to refresh existing\nmemories in place after an upgrade.\n\nNotes:\n- **Cursor** stores chats in a (often multi-GB) SQLite DB, read via Node's\n  built-in SQLite — so Cursor import needs **Node 22.5+** (other sources don't).\n- **ChatGPT** and **Claude.ai web chats** can't be imported — they live in the\n  cloud, not local files. (A future \"import from data-export file\" is planned.)\n\n### Tidy up\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server cleanup --dry-run   # preview\nnpx @ravi-labs/mindmap-mcp-server cleanup             # apply\n```\n\nRemoves automated/scheduled-task memories and collapses duplicate sessions.\nAnything you've **promoted** is always kept.\n\n## Persona — a profile every tool can read\n\nBeyond individual discussions, Mind Map keeps a **persona**: a distilled,\nevolving profile of *how you work* — your stack, style, communication\npreferences, and constraints — so any tool can apply it and **stop re-asking the\nsame setup questions.** It's separate from your discussion memories.\n\n- **Declared** facts: tell a tool *\"I prefer concise, code-first answers\"* and it\n  calls `mindmap_persona_set`. High confidence, yours, editable.\n- **Inferred** facts: `mindmap_persona_learn` derives recurring signals from your\n  existing memories. No LLM needed (keyword heuristic); richer if you enable one.\n- Tools call `mindmap_persona` at the start of a session and apply what's there.\n\nAdd this to your client's instructions so it happens automatically:\n\n> At the start of a session call `mindmap_persona` and apply it. When I state a\n> durable preference, call `mindmap_persona_set`.\n\n## Own your context\n\nA memory you can't extract, inspect, or carry isn't a memory you own. Three\nfeatures make Mind Map's memory genuinely yours:\n\n**Memory Passport** — export everything to one portable, open file, and pull your\ncontext *out of the walled gardens*:\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server passport export                 # → ~/mindmap-passport-<date>.json\nnpx @ravi-labs/mindmap-mcp-server passport import <file>          # from another machine\nnpx @ravi-labs/mindmap-mcp-server passport import-chatgpt conversations.json   # your ChatGPT export\nnpx @ravi-labs/mindmap-mcp-server passport import-claude  conversations.json   # your Claude.ai export\n```\n\nThe cloud chats can't be reached live from a local server — but their **data\nexport files are yours**, and this imports them as distilled memories.\n\n**Glass-box memory** — see exactly what's stored and why:\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server audit\n```\n\nEvery memory shows its **provenance** (where it came from), **trust** (how many\ntimes you reused it), and **decay forecast** (when it fades to a one-line trace).\nIn the dashboard, each memory has a one-click **Forget**. Unlike opaque vector\nstores, nothing about your memory is hidden from you.\n\n**Persona projection** — write your persona into each tool's own config, so even\nnon-MCP tools know how you work:\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server persona-sync          # Claude, Cursor, Copilot, Windsurf\n```\n\nIt edits only a managed block (`<!-- mindmap:persona:start -->`…`:end`), so your\nown content is never touched.\n\n## Optional: bring your own LLM key\n\nMind Map runs **fully without any LLM** — every feature has a no-LLM path. If you\n*want* smarter persona inference and topic-graph labels, plug in your **own**\nprovider (`anthropic`, `openai`, `google`, or local `ollama`). It's opt-in and\ngraceful: no key, or a failed call, simply falls back to the no-LLM path, and any\ncost notes are rough estimates — never a bill.\n\n**Mind Map never stores your API key.** It saves only the provider + model name\nin `~/.mindmap/llm.json`; the key is read from an **environment variable** at\ncall time. You set the key; Mind Map just reads it.\n\n**Smarter search (optional).** Search is **BM25** out of the box — no LLM needed.\nWith an **embeddings-capable** provider (OpenAI, Google, or Ollama — Anthropic has\nno embeddings API), build a local embedding cache for **hybrid search** (BM25 fused\nwith semantic similarity via reciprocal rank fusion):\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server embed   # build/refresh the local embedding cache\n```\n\nIt re-embeds only new/changed memories, caches vectors in `~/.mindmap/embeddings.json`,\nand `resume` / `search` / `brainstorm` use it automatically. Without it (or on\nAnthropic), search stays on BM25 — never worse.\n\n### Step 1 — choose a provider\n\nFrom the dashboard's **Persona** tab (LLM section), or via the `mindmap_llm` tool\n(e.g. \"set my mindmap llm provider to anthropic\"). This writes `{provider, model}`\nto `~/.mindmap/llm.json`. Per provider, Mind Map looks for one env var:\n\n| Provider | Env var it reads | Default model |\n| --- | --- | --- |\n| `anthropic` | `ANTHROPIC_API_KEY` | claude-sonnet-4-6 |\n| `openai` | `OPENAI_API_KEY` | gpt-4o |\n| `google` | `GOOGLE_API_KEY` | gemini-1.5-pro |\n| `ollama` | *(none — local)* | llama3.1 |\n\n### Step 2 — give it the key\n\nThe key must be visible **to the process that needs it**. There are two ways, and\nwhich one you need depends on the surface:\n\n**A. Shell profile** — for the **dashboard / CLI**, and for **Claude Code** (its\nMCP servers inherit your shell environment):\n\n```bash\n# ~/.zshrc (or ~/.bashrc)\nexport ANTHROPIC_API_KEY=\"sk-ant-…\"\n```\n\nThen `source ~/.zshrc` and restart. Run the dashboard from that same shell and\nit'll pick the key up.\n\n**B. The client's MCP config `env` block** — for **GUI clients** (Claude Desktop,\nCursor, Windsurf), which launch MCP servers *without* your shell environment, so\nthe `export` above won't reach them. Add an `env` map to Mind Map's entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"mindmap\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ravi-labs/mindmap-mcp-server\"],\n      \"env\": { \"ANTHROPIC_API_KEY\": \"sk-ant-…\" }\n    }\n  }\n}\n```\n\n> Trade-off: method **B** writes the key into that client's config file in plain\n> text. That's the only way some GUI clients can pass it through — but if you'd\n> rather not have a key on disk, prefer method **A** (or launch the GUI app from a\n> terminal that already has the variable exported, so it inherits it).\n\nThere is **no key field in the dashboard or tools by design** — a key typed into a\nweb form would have to be transmitted and stored to be useful, which is exactly the\ncredential-on-disk pattern Mind Map avoids. You set the env var yourself.\n\nFor **ollama** there's no key at all — just run `ollama serve` locally and pick the\n`ollama` provider.\n\n### Step 3 — verify\n\nCall `mindmap_llm` with no arguments (or open the dashboard Persona tab). When the\nkey is visible it reports **ready** — e.g. *\"✓ `ANTHROPIC_API_KEY` detected.\"*\nAfter setting the env var, **restart** the server/client so it's picked up.\n\n## See your memory — the dashboard\n\n```bash\nnpx @ravi-labs/mindmap-mcp-server dashboard   # http://127.0.0.1:7777\n```\n\nA local web UI (loopback-only) with six views:\n\n- **List** — memories grouped by 🔥/🌤️/❄️ tier, searchable; click one to read its\n  summary, key points, and **full discussion** (the complete conversation,\n  reconstructed on demand and rendered as Markdown). A 📜 badge + filter mark\n  memories that have a full transcript; a **File into…** control files it into a\n  collection.\n- **Tree** — 🧠 → source → project → discussion, with linked threads joined.\n- **Graph** — an auto-derived **topic map**: categories as hubs, sessions\n  connected by relatedness, with category filter chips and live search. An opt-in\n  **✨ LLM labels** button relabels the topic clusters using your own LLM.\n- **Organize** — your **collections** (each item with *↳ where you left off*),\n  the **✨ Auto-organize** proposer, and a live breakdown of how memory is\n  organized automatically (by tier, source, workspace, topic).\n- **Persona** — view and edit your profile (see above), add preferences, run\n  inference, and configure the optional LLM — all from the browser.\n- **Activity** — a live console of every MCP call across your tools (redacted,\n  from `~/.mindmap/calls.jsonl`).\n\nA **⟳ Sync** button imports new sessions on demand, and a **cleanliness score**\nrewards a tidy, trusted memory — not a big one.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `mindmap_capture` | Silently save a context summary (the effortless half of the loop). |\n| `mindmap_resume` | Find + return the best context for a topic; **promotes on reuse**. Also a launcher: pass `collection` to resume out of e.g. \"Unfinished projects\". |\n| `mindmap_resume_options` | List distinct candidate topics (with workspace) so the user can pick which to resume. |\n| `mindmap_import` | On-demand session sync — \"update mind map with my recent work\". |\n| `mindmap_organize` | File memories into collections — \"add this to my Goals\", \"park this\". |\n| `mindmap_collections` | View collections; opening one shows workspace + where-you-left-off per item. |\n| `mindmap_curate` | Auto-organize: scan everything, propose collections (unfinished projects, goals, decisions, parked). Preview-first. |\n| `mindmap_brainstorm` | Brainstorm a topic *with* your memory — loads prior idea-threads so ideas continue across tools. |\n| `mindmap_search` | Read-only search across every tier and tool. |\n| `mindmap_list` | Browse memories with filters. |\n| `mindmap_get` | Fetch one memory's full content. |\n| `mindmap_transcript` | Reconstruct the **full original conversation** for a memory (Claude Code / Cursor / Copilot). |\n| `mindmap_promote` | Explicitly bless a memory as trusted (→ hot). |\n| `mindmap_update` | Trim / edit / retag — the human curation moment. |\n| `mindmap_link` | Connect related threads (the lightweight \"map\"). |\n| `mindmap_prune` | Run the consolidation pass on demand (`dry_run` to preview). |\n| `mindmap_forget` | Soft-archive to a trace, or `hard` delete. |\n| `mindmap_health` | Gamified cleanliness score (opt-in). |\n| `mindmap_tidy` | Batch of stalest memories to keep / trim / forget. |\n| `mindmap_config` | View / change decay windows and toggles. |\n| `mindmap_persona` | Read your persona — apply it at session start to stop re-asking. |\n| `mindmap_persona_set` | Record a durable preference (stack/style/constraints…). |\n| `mindmap_persona_forget` | Mute or delete a persona fact. |\n| `mindmap_persona_learn` | Infer persona facts from your memories (LLM-assisted if configured). |\n| `mindmap_persona_sync` | Write your persona into your tools' native config files. |\n| `mindmap_llm` | Configure the optional BYO-key LLM (provider/model; key stays in your env). |\n| `mindmap_audit` | Glass-box ledger: provenance, trust, and decay forecast for every memory. |\n| `mindmap_passport_export` | Export all memories + persona to one portable file. |\n| `mindmap_passport_import` | Import a passport, or a ChatGPT / Claude.ai data export. |\n\n## How it stores things\n\n```\n~/.mindmap/\n├── threads/<id>.json   # one file per memory (human-readable JSON)\n├── index.json          # fast list/search index\n├── config.json         # tunable thresholds + gamification toggle\n├── persona.json        # your evolving profile (declared + inferred facts)\n├── collections.json    # your collections (Goals, Parking Lot, …) — ids only\n├── llm.json            # optional LLM provider + model (never your API key)\n├── calls.jsonl         # redacted log of every MCP call (the Activity view)\n└── embeddings.json     # optional local embedding cache for semantic search\n```\n\nPlain files you own and can inspect, grep, back up, or sync yourself. Tiers map\nto the mental model: **hot = mem**, **warm = files**, **cold = drive (trace)**.\n\n**Secrets are masked before saving.** Because memories are plain files — and\nimports can pull in keys pasted into past sessions — every memory is scanned for\ncommon credential shapes (API keys, tokens, private keys) and they're replaced\nwith `[REDACTED:…]` before anything is written. Masked memories are flagged (🔒).\nBest-effort, local, no LLM; toggle with the `redactSecrets` config.\n\n## Tuning decay\n\n```jsonc\n// defaults (mindmap_config to change at runtime)\n{\n  \"hotWindowMs\":  7 days,    // active memory stays hot this long\n  \"warmWindowMs\": 30 days,   // then warm; past it → cold trace\n  \"promotedLongevityFactor\": 2,  // blessed memories decay 2× slower\n  \"gamification\": true\n}\n```\n\n## Develop\n\n```bash\nnpm run dev      # watch mode (tsx)\nnpm run build    # type-check + emit dist/\nnpm test         # end-to-end smoke tests (stdio + http) in throwaway data dirs\n```\n\n## Future\n\n**ChatGPT / cloud clients (parked).** A cloud client can't reach a local server\nwithout exposing it publicly (a tunnel or a host), which breaks the local-first\npromise. An HTTP transport already ships in the codebase\n(`TRANSPORT=http`, with bearer-token auth + origin allow-listing) for anyone who\n*chooses* to self-host — but it's intentionally not the default path. Revisiting\nChatGPT later likely means an opt-in hosted tier with per-user encryption, a\ndeliberate trust decision rather than a default.\n\nOther directions:\n\n- Auto-capture hooks per client so the \"capture\" step is invisible.\n- Embedding-based semantic recall (current search is token-overlap).\n- LLM-assisted relatedness edges in the graph (labels already opt-in).\n- OAuth + per-user data isolation (only needed if a hosted tier ever happens).\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).\n",
  "bytes": 21200,
  "sha": "c623862db89edb3736d043117202bd62f12d8d184d30b894ab01afd560c27667",
  "repo_slug": "ravi-labs/mindmap-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ravi_labs_mindmap_mcp_server_a9aca75b/readme"
}