🧠 Mind Map — MCP memory & context-handoff server

Ever lose the thread of a discussion across Claude Code, Claude Desktop, and yourother AI tools? Mind Map is a small, local-first MCPserver 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 othertool — no more re-explaining your project from scratch. Memory you stop usingcools and decays gracefully into one-line traces (it's never silentlydeleted), so your shelf stays small and trustworthy instead of becoming anotherhaystack.

Local-first by design. It runs on your machine; your memories are plainfiles in ~/.mindmap that never leave your control. No account, no cloud, noserver 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'treach a local server without a public endpoint, which conflicts withlocal-first. See Future.

The idea in one loop

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

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 ifpresent. Restart your client and Mind Map's tools are there. Preview first withnpx @ravi-labs/mindmap-mcp-server install --dry-run; undo withnpx @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 thatclient'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

Tools

Tool	What it does
`mindmap_capture`	Silently save a context summary (the effortless half of the loop).
`mindmap_resume`	Find + return the best context for a topic; promotes on reuse.
`mindmap_search`	Read-only search across every tier and tool.
`mindmap_list`	Browse memories with filters.
`mindmap_get`	Fetch one memory's full content.
`mindmap_promote`	Explicitly bless a memory as trusted (→ hot).
`mindmap_update`	Trim / edit / retag — the human curation moment.
`mindmap_link`	Connect related threads (the lightweight "map").
`mindmap_prune`	Run the consolidation pass on demand (`dry_run` to preview).
`mindmap_forget`	Soft-archive to a trace, or `hard` delete.
`mindmap_health`	Gamified cleanliness score (opt-in).
`mindmap_tidy`	Batch of stalest memories to keep / trim / forget.
`mindmap_config`	View / change decay windows and toggles.

How it stores things

~/.mindmap/
├── threads/<id>.json   # one file per memory (human-readable JSON)
├── index.json          # fast list/search index
└── config.json         # tunable thresholds + gamification toggle

Plain files you own and can inspect, grep, back up, or sync yourself. Tiers mapto the mental model: hot = mem, warm = files, cold = drive (trace).

Tuning decay

// defaults (mindmap_config to change at runtime)
{
  "hotWindowMs":  7 days,    // active memory stays hot this long
  "warmWindowMs": 30 days,   // then warm; past it → cold trace
  "promotedLongevityFactor": 2,  // blessed memories decay 2× slower
  "gamification": true
}

Develop

npm run dev      # watch mode (tsx)
npm run build    # type-check + emit dist/
npm test         # end-to-end smoke tests (stdio + http) in throwaway data dirs

Future

ChatGPT / cloud clients (parked). A cloud client can't reach a local serverwithout exposing it publicly (a tunnel or a host), which breaks the local-firstpromise. An HTTP transport already ships in the codebase(TRANSPORT=http, with bearer-token auth + origin allow-listing) for anyone whochooses to self-host — but it's intentionally not the default path. RevisitingChatGPT later likely means an opt-in hosted tier with per-user encryption, adeliberate trust decision rather than a default.

Other directions:

Auto-capture hooks per client so the "capture" step is invisible.
Embedding-based semantic recall (current search is token-overlap).
Richer graph view of linked threads.
OAuth + per-user data isolation (only needed if a hosted tier ever happens).

License

MIT

🧠 Mind Map — MCP memory & context-handoff server