mindmap-mcp-server

# 🧠 Mind Map — MCP memory & context-handoff server

[![npm](https://img.shields.io/npm/v/@ravi-labs/mindmap-mcp-server?logo=npm)](https://www.npmjs.com/package/@ravi-labs/mindmap-mcp-server)
[![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)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/node/v/@ravi-labs/mindmap-mcp-server)](https://nodejs.org)

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](https://modelcontextprotocol.io)
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](#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:

```bash
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:**

```bash
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`):

```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:

```json
{ "command": "npx", "args": ["-y", "@ravi-labs/mindmap-mcp-server"],
  "env": { "MINDMAP_DIR": "/path/to/my/memory" } }
```

### From source (development)

```bash
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 \<topic\>"** → 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 \<topic\> with me"** → loads your prior thinking so ideas continue across tools

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.

### 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:

```bash
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 <name>`, `--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

```bash
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*:

```bash
npx @ravi-labs/mindmap-mcp-server passport export                 # → ~/mindmap-passport-<date>.json
npx @ravi-labs/mindmap-mcp-server passport import <file>          # 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:

```bash
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:

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

It edits only a managed block (`<!-- mindmap:persona:start -->`…`: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.js