mindmap-mcp-server

🧠 思维导图 — MCP 记忆与上下文交接服务

你是否曾在 Claude Code、Claude Desktop 和其他 AI 工具之间切换时，丢失讨论的上下文？Mind Map 是一个小巧的、本地优先的 MCP 服务，可作为所有本地 MCP 客户端的共享记忆层。

你可以在会话结束时捕获上下文，并在其他任何工具中恢复它——无需再从头解释项目。停止使用的记忆会逐渐冷却并平滑衰减为一行追踪记录（绝不会在无提示的情况下被删除），因此你的记忆架不会变得臃肿，而是保持小巧且值得信赖。

设计上采用本地优先。 它运行在你的计算机上；记忆以普通文件的形式存放在 ~/.mindmap 中，始终由你掌控。无需账户、无需云服务，也无需信任任何服务端。只需运行 npx @ravi-labs/mindmap-mcp-server install 即可安装。

ChatGPT 和其他云端／网页客户端目前不在支持范围内——它们无法在没有公共端点的情况下访问本地服务，这与本地优先的设计相冲突。请参阅未来计划。

一个循环，理解核心理念

1. 捕获（轻松完成）——讨论结束时，保存一份可移植的摘要。
2. 恢复（再次使用时提升）——在新会话中调出记忆。再次使用记忆的行为会将其提升为可信记忆。一次性会话不会得到提升，因此不会让你的记忆架变得杂乱。
3. 整合（自动进行）——后台流程会让未使用的记忆逐级冷却（🔥 热 → 🌤️ 温 → ❄️ 冷），并将冷记忆压缩为可搜索的一行追踪记录。真正的优势不在于存储，而在于善于遗忘。
4. 整理（可选，游戏化）——通过整洁度评分奖励清理，而不是囤积。

安装（一个命令）

发布到 npm 后，完整的安装命令如下：

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

此命令会自动检测本地 MCP 客户端（Claude Desktop、Cursor、Windsurf）并为你写入配置；如果检测到 Claude Code，还会通过其 CLI 配置它。重启客户端后，即可使用 Mind Map 的工具。先用 npx @ravi-labs/mindmap-mcp-server install --dry-run 预览；用 npx @ravi-labs/mindmap-mcp-server uninstall 撤销安装。

默认情况下，数据存储在 ~/.mindmap/ 中——可通过 MINDMAP_DIR 环境变量更改位置。

手动设置（如有需要）

所有客户端都使用相同的命令——通过标准输入／输出运行 npx -y @ravi-labs/mindmap-mcp-server。

Claude Code：

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

Claude Desktop — 编辑 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 / 其他客户端 — 在该客户端的 MCP 配置中使用相同的 command + args 格式。添加 env 块以更改数据存储位置：

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

从源代码构建（开发）

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

日常使用

只需在 AI 工具中自然地交谈，模型就会调用合适的工具：

• “保存到思维导图” → 捕获当前上下文
• “继续我关于 <topic> 的工作” → 将其带回新的会话
• “我的思维导图里有什么？” / “查看我的思维导图健康状况” → 浏览 / 评分
• “你了解我是怎么工作的吗？” → 读取你的 persona（见下文）
• “和我一起对 <topic> 进行头脑风暴” → 加载你之前的思考，让想法在不同工具间延续
• “把这个添加到我的目标中” / “先把这个搁置起来” → 将其归入一个 集合
• “我启动过哪些应用却一直没完成？” → 自动将你的记忆整理到集合中
• “继续我的某个未完成项目” → 选一个项目，就能回到正确的文件夹，从确切的下一步继续

运行 npx @ravi-labs/mindmap-mcp-server quickstart，查看完整的入门指南。

跨工具进行头脑风暴

在 Claude 中开始一个想法，然后在 Cursor 中继续，无需重新解释。Mind Map 是共享记忆；每个工具都能发挥自己的头脑风暴优势。mindmap_brainstorm 会加载你的 persona 和该主题下之前的想法线索，你可以进行头脑风暴，然后用 kind: "brainstorm" 保存，即可在任何地方继续。随附的 brainstorm Skill（由 install 安装到 ~/.claude/skills）会为 Claude 串联起加载 → 头脑风暴 → 保存的流程。

按自己的方式整理 — 集合

Mind Map 始终会自动整理（按新近程度分层、来源、主题、工作区）。集合则是你自己的整理层：可以创建 🎯 目标、🅿️ 暂存区、✅ 决策等命名分组，也可以自定义。你可以在任何工具中说 “把这个添加到我的目标中” 或 “先把这个搁置起来”，也可以使用仪表板中的 整理选项卡。

集合不只是文件夹，体现在以下两点：

• 归档可防止记忆衰退。 记忆归入置顶集合后就不会被遗忘——将某项内容搁置起来，表明它很重要。（明确说“忘掉这个”仍然有效。）
• 每个集合都是启动入口。 “继续我的某个未完成项目” 会列出这些项目——每个项目都显示其 📂 工作区和 ↳ 上次停下的位置；选中一个后，mindmap_resume 就会带你回到其中：包含完整的主题上下文、正确的文件夹，以及确切的下一步。

不想手动归档？自动整理会读取你所有会话的内容，并提出集合建议——它总会查找未完成的项目（开始构建后停滞，始终未发布）、目标、决策和搁置的想法，也会查找你指定的内容（“所有关于计费的内容”）。它只会提供建议；只有你接受后，内容才会归档。如果已配置，会使用你自己的大模型；否则会使用无需密钥的启发式方法。

自动捕获

对于 Claude Code，install 会添加一个 SessionEnd 自动捕获钩子——每个有实质内容的会话都会自动提炼成一条记忆，因此你不必记得手动保存。它会去重（恢复会话后再次结束时会就地更新），并跳过琐碎或自动化的会话。使用 install --no-hook 可选择退出；运行 uninstall 会将其彻底移除。

对于其他客户端（或者想多一重提醒），可在客户端的说明中添加一行（例如 Claude Code 的 CLAUDE.md）：

在有实质内容的会话结束时，调用 mindmap_capture 保存上下文。 当我提及过去的工作时，先调用 mindmap_resume。

工具的说明中也包含了相关指引，鼓励模型主动执行这些操作。

导入过去的会话

将现有的 Claude 历史记录导入 Mind Map — 提炼内容，而非原始转储：

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

涵盖 Claude Code（CLI — 完整提示词）、Cowork（标题 + 开场消息）、VS Code Copilot（完整提示词）和 Cursor（聊天标题 + 提示词）；每条记忆都会标记来源。筛选条件：--source code|cowork|copilot|cursor、--project <name>、--limit N。导入的记忆会保留原始日期，因此旧记忆会自动归入冷痕迹。

对于有完整记录的来源（Claude Code、Cursor、Copilot），导入的记忆会保留讨论内容（你的提示词 + 助手实质性的回答），而不只是标题。升级后，可使用 --reimport 重新运行，在原位置刷新现有记忆。

说明：

• Cursor 会将聊天记录存储在一个（通常有数 GB 的）SQLite DB 中，并通过 Node 内置的 SQLite 读取 — 因此导入 Cursor 需要 Node 22.5+（其他来源不需要）。
• 无法导入 ChatGPT 和 Claude.ai 网页聊天 — 它们存储在云端，而非本地文件中。（计划在未来支持“从数据导出文件导入”。）

整理

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

移除自动化／定时任务记忆，并合并重复的会话。任何你提升过的内容都会始终保留。

Persona — 每个工具都可读取的个人档案

除了单独的讨论外，Mind Map 还会维护一个 persona：一份不断提炼、持续演进的工作方式档案 — 包括你的技术栈、风格、沟通偏好和限制 — 这样任何工具都能应用这些信息，并**不再反复询问相同的环境配置问题。**它独立于你的讨论记忆。

• 主动声明的事实：告诉工具 “我喜欢简洁、代码优先的回答”，它就会调用 mindmap_persona_set。置信度高，归你所有，且可编辑。
• 推断得出的事实：mindmap_persona_learn 会从现有记忆中归纳反复出现的信号。无需 LLM（采用关键词启发式方法）；启用 LLM 后效果更丰富。
• 工具会在会话开始时调用 mindmap_persona，并应用其中的内容。

将以下内容添加到客户端的指令中，即可自动执行：

在会话开始时调用 mindmap_persona 并应用其中的内容。当我陈述长期有效的偏好时，调用 mindmap_persona_set。

掌控你的上下文

无法提取、检查或带走的记忆，就不是真正属于你的记忆。三项功能让 Mind Map 的记忆真正归你所有：

Memory Passport — 将所有内容导出为一个便于携带的开放文件，并将你的上下文从封闭花园中带出来：

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

无法通过本地服务实时访问云端聊天 — 但它们的数据导出文件属于你，而此功能会将其导入为提炼后的记忆。

玻璃盒记忆 — 查看存储的具体内容及其原因：

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

每条记忆都会显示其来源（来自哪里）、可信度（你重复使用过多少次）和衰减预测（何时会淡化为一行痕迹）。在仪表板中，每条记忆都有一个一键式忘记按钮。与不透明的向量存储不同，你的记忆没有任何内容对你隐藏。

Persona 投射 — 将你的 persona 写入每个工具自己的配置中，让非 MCP 工具也了解你的工作方式：

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

它只会编辑受管理的代码块（``…:end），绝不会改动你自己的内容。

可选：使用你自己的 LLM 密钥

Mind Map 完全可以在不使用任何 LLM 的情况下运行——每项功能都有无需 LLM 的实现路径。如果你想要更智能的人设推断和主题图谱标签，可以接入你自己的提供方（anthropic、openai、google 或本地 ollama）。此功能需要主动启用，并且有完善的回退机制：没有密钥或调用失败时，会自动回退到无需 LLM 的实现路径。任何费用说明都只是粗略估算——绝不是账单。

Mind Map 绝不会存储你的 API 密钥。它只会将提供方和模型名称保存到 ~/.mindmap/llm.json；调用时会从环境变量读取密钥。由你设置密钥；Mind Map 只负责读取。

更智能的搜索（可选）。搜索开箱即用地使用 BM25——无需 LLM。使用支持嵌入功能的提供方（OpenAI、Google 或 Ollama——Anthropic 没有嵌入 API），即可构建本地嵌入缓存，用于混合搜索（将 BM25 与语义相似度通过倒数排名融合结合）：

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

它只会为新增或已更改的记忆重新生成嵌入，并将向量缓存到 ~/.mindmap/embeddings.json；resume / search / brainstorm 会自动使用这些缓存。若未启用此功能（或使用 Anthropic），搜索仍会使用 BM25——效果绝不会变差。

第 1 步——选择提供方

在仪表板的 Persona 选项卡（LLM 部分）中选择，或通过 mindmap_llm 工具设置（例如“将我的 mindmap llm 提供方设为 anthropic”）。此操作会将 {provider, model} 写入 ~/.mindmap/llm.json。Mind Map 会为每个提供方查找一个环境变量：

提供方	读取的环境变量	默认模型
anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-6
openai	OPENAI_API_KEY	gpt-4o
google	GOOGLE_API_KEY	gemini-1.5-pro
ollama	（无——本地运行）	llama3.1

第 2 步——提供密钥

需要密钥的进程必须能够访问该密钥。有两种方式，具体使用哪一种取决于使用场景：

A. Shell 配置文件——适用于仪表板 / CLI，以及 Claude Code（其 MCP 服务会继承你的 Shell 环境）：

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

然后运行 source ~/.zshrc 并重启。在同一个 Shell 中启动仪表板，它就能读取到密钥。

B. 客户端 MCP 配置中的 env 区块——适用于 GUI 客户端（Claude Desktop、Cursor、Windsurf）。这些客户端启动 MCP 服务时不会使用你的 Shell 环境，因此无法获取上述 export 命令设置的变量。将 env 映射添加到 Mind Map 的配置项中：

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

权衡之处：方法 B 会将密钥以纯文本形式写入该客户端的配置文件。这是某些 GUI 客户端传递密钥的唯一方式——但如果你不希望密钥保存在磁盘上，建议使用方法 A（或者从已导出该变量的终端启动 GUI 应用，这样它就能继承该变量）。

按照设计，仪表板或工具中都没有密钥输入框——要让在网页表单中输入的密钥发挥作用，就必须传输并存储它，而这正是 Mind Map 要避免的凭据落盘模式。请自行设置环境变量。

使用 ollama 时完全不需要密钥——只需在本地运行 ollama serve，然后选择 ollama 提供方。

第 3 步——验证

不带参数调用 mindmap_llm（或打开仪表板的 Persona 选项卡）。检测到密钥时，它会报告已就绪——例如 *“✓ 检测到 ANTHROPIC_API_KEY。”*设置环境变量后，请重启服务/客户端，以便加载该变量。

查看你的记忆 — 控制面板

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

一个仅限本地回环访问的 Web UI，包含六个视图：

• 列表 — 按 🔥/🌤️/❄️ 层级分组记忆，并可搜索；点击一条记忆即可查看摘要、要点和完整讨论（按需重建并以 Markdown 呈现的完整对话）。📜 标记和筛选器用于标识包含完整对话记录的记忆；**归档到…**控件可将记忆归入集合。
• 树状图 — 🧠 → 来源 → 项目 → 讨论，并将关联的对话串连接起来。
• 图谱 — 自动生成的主题图谱：以类别为中心节点，按关联度连接各个会话，并提供类别筛选标签和实时搜索。可选的**✨ LLM 标签**按钮可使用你自己的 LLM 为主题集群重新命名。
• 整理 — 你的集合（每项都附有*↳ 上次进度*）、✨ 自动整理建议器，以及对记忆自动整理方式的实时细分（按层级、来源、工作区、主题）。
• 角色设定 — 查看和编辑你的个人资料（见上文）、添加偏好、运行推断并配置可选的 LLM——全部都可在浏览器中完成。
• 活动 — 实时控制台，显示所有工具的每次 MCP 调用（已脱敏，来源为 ~/.mindmap/calls.jsonl）。

⟳ 同步按钮可按需导入新会话；整洁度评分奖励的是整洁、可信的记忆，而不是数量庞大的记忆。

工具

工具	功能
mindmap_capture	静默保存上下文摘要（让记忆循环轻松完成的一环）。
mindmap_resume	查找并返回与某个主题最相关的上下文；重复使用时会提升其层级。也可用作启动器：传入 collection，即可从例如“未完成的项目”中恢复上下文。
mindmap_resume_options	列出不同的候选主题（包含工作区），供用户选择要恢复的内容。
mindmap_import	按需同步会话——“用我最近的工作更新思维导图”。
mindmap_organize	将记忆归入集合——“把这个加入我的目标”“先搁置这个”。
mindmap_collections	查看集合；打开一个集合后，可查看每项内容的工作区和上次进度。
mindmap_curate	自动整理：扫描所有内容并建议创建集合（未完成的项目、目标、决策、搁置项）。先预览再执行。
mindmap_brainstorm	结合你的记忆围绕主题进行头脑风暴——加载以往的创意对话串，让创意在不同工具间延续。
mindmap_search	以只读方式搜索所有层级和工具中的内容。
mindmap_list	使用筛选条件浏览记忆。
mindmap_get	获取一条记忆的完整内容。
mindmap_transcript	重建一条记忆的完整原始对话（Claude Code / Cursor / Copilot）。
mindmap_promote	明确将一条记忆标记为可信（→ 热）。
mindmap_update	精简 / 编辑 / 重新标记——由人整理记忆的环节。
mindmap_link	连接相关对话串（轻量级“地图”）。
mindmap_prune	按需执行整合流程（使用 dry_run 预览）。
mindmap_forget	软归档并保留痕迹，或使用 hard 永久删除。
mindmap_health	游戏化的整洁度评分（可选）。
mindmap_tidy	批量列出最久未更新的记忆，供你保留 / 精简 / 忘却。
mindmap_config	查看 / 更改衰减周期和开关。
mindmap_persona	读取你的角色设定——在会话开始时应用，以免反复询问。
mindmap_persona_set	记录长期偏好（技术栈 / 风格 / 限制条件……）。
mindmap_persona_forget	隐藏或删除一条角色设定信息。
mindmap_persona_learn	从你的记忆中推断角色设定信息（若已配置，则由 LLM 辅助）。
mindmap_persona_sync	将你的角色设定写入工具的原生配置文件。
mindmap_llm	配置可选的自带密钥 LLM（提供商 / 模型；密钥保留在你的环境中）。
mindmap_audit	透明账本：显示每条记忆的来源、信任度和衰减预测。
mindmap_passport_export	将所有记忆和角色设定导出到一个可移植文件中。
mindmap_passport_import	导入一个护照，或导入 ChatGPT / Claude.ai 数据导出文件。

它如何存储内容

~/.mindmap/
├── threads/<id>.json   # one file per memory (human-readable JSON)
├── index.json          # fast list/search index
├── config.json         # tunable thresholds + gamification toggle
├── persona.json        # your evolving profile (declared + inferred facts)
├── collections.json    # your collections (Goals, Parking Lot, …) — ids only
├── llm.json            # optional LLM provider + model (never your API key)
├── calls.jsonl         # redacted log of every MCP call (the Activity view)
└── embeddings.json     # optional local embedding cache for semantic search

你拥有并可以自行检查、使用 grep 搜索、备份或同步的纯文件。各层对应以下心智模型：热 = mem、温 = files、冷 = drive（trace）。

保存前会屏蔽机密信息。 由于记忆是纯文件，而且导入内容可能包含过去会话中粘贴的密钥，因此每条记忆都会经过常见凭据格式（API 密钥、令牌、私钥）的扫描，并在写入前将其替换为 [REDACTED:…]。经过屏蔽的记忆会标记为（🔒）。尽力而为，在本地处理，不使用大模型；可通过 redactSecrets 配置开关。

调整衰减

// 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
}

开发

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

未来规划

ChatGPT / 云客户端（暂缓）。 云客户端无法访问本地服务，除非将其公开（通过隧道或主机），这会违背本地优先的承诺。代码库中已提供 HTTP 传输方式（TRANSPORT=http，支持 Bearer 令牌身份验证和来源允许列表），供任何选择自行托管的人使用，但这并非默认路径。之后若要重新考虑 ChatGPT，可能需要提供可选的托管层并采用逐用户加密，让用户主动决定是否信任，而不是默认启用。

其他方向：

• 为每个客户端添加自动捕获钩子，让“捕获”步骤不可见。
• 基于嵌入的语义回忆（当前搜索基于令牌重叠）。
• 在图谱中添加由大模型辅助生成的相关性边（标签已可选启用）。
• OAuth + 逐用户数据隔离（只有未来真的推出托管层时才需要）。

许可证

Apache-2.0 — 参见 LICENSE 和 NOTICE。