# Mindmap Mcp Server

> Local-first MCP memory & context-handoff server — capture context in one AI tool, resume it in another. Graceful decay, no cloud.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ravi-labs-mindmap-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ravi-labs](https://agentstack.voostack.com/s/ravi-labs)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ravi-labs](https://github.com/ravi-labs)
- **Source:** https://github.com/ravi-labs/mindmap-mcp-server

## Install

```sh
agentstack add mcp-ravi-labs-mindmap-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

[](https://www.npmjs.com/package/@ravi-labs/mindmap-mcp-server)
[](https://github.com/ravi-labs/mindmap-mcp-server/actions/workflows/ci.yml)
[](LICENSE)
[](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 \"** → 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:

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

```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 (``…`: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):

```bash
npx @ravi-labs/mindmap-mcp-server embed   # build/refresh the local embedding cache
```

It re-embeds only new/changed memories, caches vectors in `~/.mindmap/embeddings.json`,
and `resume` / `search` / `brainstorm` use it automatically. Without it (or on
Anthropic), search stays on BM25 — never worse.

### Step 1 — choose a provider

From the dashboard's **Persona** tab (LLM section), or via the `mindmap_llm` tool
(e.g. "set my mindmap llm provider to anthropic"). This writes `{provider, model}`
to `~/.mindmap/llm.json`. Per provider, Mind Map looks for one env var:

| Provider | Env var it reads | Default model |
| --- | --- | --- |
| `anthropic` | `ANTHROPIC_API_KEY` | claude-sonnet-4-6 |
| `openai` | `OPENAI_API_KEY` | gpt-4o |
| `google` | `GOOGLE_API_KEY` | gemini-1.5-pro |
| `ollama` | *(none — local)* | llama3.1 |

### Step 2 — give it the key

The key must be visible **to the process that needs it**. There are two ways, and
which one you need depends on the surface:

**A. Shell profile** — for the **dashboard / CLI**, and for **Claude Code** (its
MCP servers inherit your shell environment):

```bash
# ~/.zshrc (or ~/.bashrc)
export ANTHROPIC_API_KEY="sk-ant-…"
```

Then `source ~/.zshrc` and restart. Run the dashboard from that same shell and
it'll pick the key up.

**B. The client's MCP config `env` block** — for **GUI clients** (Claude Desktop,
Cursor, Windsurf), which launch MCP servers *without* your shell environment, so
the `export` above won't reach them. Add an `env` map to Mind Map's entry:

```json
{
  "mcpServers": {
    "mindmap": {
      "command": "npx",
      "args": ["-y", "@ravi-labs/mindmap-mcp-server"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-…" }
    }
  }
}
```

> Trade-off: method **B** writes the key into that client's config file in plain
> text. That's the only way some GUI clients can pass it through — but if you'd
> rather not have a key on disk, prefer method **A** (or launch the GUI app from a
> terminal that already has the variable exported, so it inherits it).

There is **no key field in the dashboard or tools by design** — a key typed into a
web form would have to be transmitted and stored to be useful, which is exactly the
credential-on-disk pattern Mind Map avoids. You set the env var yourself.

For **ollama** there's no key at all — just run `ollama serve` locally and pick the
`ollama` provider.

### Step 3 — verify

Call `mindmap_llm` with no arguments (or open the dashboard Persona tab). When the
key is visible it reports **ready** — e.g. *"✓ `ANTHROPIC_API_KEY` detected."*
After setting the env var, **restart** the server/client so it's picked up.

## See your memory — the dashboard

```bash
npx @ravi-labs/mindmap-mcp-server dashboard   # http://127.0.0.1:7777
```

A local web UI (loopback-only) with six views:

- **List** — memories grouped by 🔥/🌤️/❄️ tier, searchable; click one to read its
  summary, key points, and **full discussion** (the complete conversation,
  reconstructed on demand and rendered as Markdown). A 📜 badge + filter mark
  memories that have a full transcript; a **File into…** control files it into a
  collection.
- **Tree** — 🧠 → source → project → discussion, with linked threads joined.
- **Graph** — an auto-derived **topic map**: categories as hubs, sessions
  connected by relatedness, with category filter chips and live search. An opt-in
  **✨ LLM labels** button relabels the topic clusters using your own LLM.
- **Organize** — your **collections** (each item with *↳ where you left off*),
  the **✨ Auto-organize** proposer, and a live breakdown of how memory is
  organized automatically (by tier, source, workspace, topic).
- **Persona** — view and edit your profile (see above), add preferences, run
  inference, and configure the optional LLM — all from the browser.
- **Activity** — a live console of every MCP call across your tools (redacted,
  from `~/.mindmap/calls.jsonl`).

A **⟳ Sync** button imports new sessions on demand, and a **cleanliness score**
rewards a tidy, trusted memory — not a big one.

## 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**. Also a launcher: pass `collection` to resume out of e.g. "Unfinished projects". |
| `mindmap_resume_options` |

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ravi-labs](https://github.com/ravi-labs)
- **Source:** [ravi-labs/mindmap-mcp-server](https://github.com/ravi-labs/mindmap-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ravi-labs-mindmap-mcp-server
- Seller: https://agentstack.voostack.com/s/ravi-labs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.