内容
<p align="center">
<h1 align="center">🧠 AI 思维导图</h1>
<p align="center">
<strong>MCP 服务器，可降低 AI 编码代理令牌使用量 80-99%</strong>
</p>
<p align="center">
<a href="https://github.com/shdra06/ai-mind-map/actions/workflows/ci.yml"><img src="https://github.com/shdra06/ai-mind-map/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/shdra06/ai-mind-map/releases"><img src="https://img.shields.io/github/v/release/shdra06/ai-mind-map?label=release" alt="Release"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/shdra06/ai-mind-map" alt="License"></a>
<a href="https://www.npmjs.com/package/ai-mind-map"><img src="https://img.shields.io/npm/v/ai-mind-map" alt="npm"></a>
<a href="https://www.npmjs.com/package/ai-mind-map"><img src="https://img.shields.io/npm/dm/ai-mind-map" alt="npm downloads"></a>
</p>
<p align="center">
停止浪费令牌重新阅读代码库。给你的 AI 代理一个持久的记忆。
</p>
</p>
---
## ⚡ 一键安装
```bash
npx ai-mind-map install
```
> 自动检测 Claude、Cursor、VS Code、Windsurf、Antigravity、Zed、Continue.dev — 立即配置所有这些。<br> **无需配置文件。无需手动设置。只需运行并重启你的代理。**
---
<p align="center">
<a href="#-quick-start">快速开始</a> •
<a href="#-how-it-works">工作原理</a> •
<a href="#-50-mcp-tools">所有 50+ 工具</a> •
<a href="#-connect-to-your-ai-agent">连接</a> •
<a href="#-cli-commands">CLI 命令</a> •
<a href="#-configuration">配置</a>
</p>
---
## ❓ 问题
每次 AI 编码代理（Claude Code、Cursor、Copilot、Windsurf、Antigravity）处理请求时，它都会**从头开始读取整个代码库**。这浪费了大量的令牌：
```
没有 AI 思维导图：
❌ 代理读取 auth.ts → 5,000 令牌
❌ 代理再次读取 auth.ts → 5,000 令牌（相同文件！）
❌ 代理再次读取 auth.ts → 5,000 令牌（仍然是相同文件！）
总计：15,000 令牌用于 3 个关于一个文件的查询
使用 AI 思维导图：
✅ mindmap_get_signature("authenticate") → 50 令牌
✅ mindmap_get_signature("validateToken") → 40 令牌
✅ mindmap_trace_dependencies("authenticate") → 100 令牌
总计：190 令牌 — 这是 99% 的减少
```
> **行业研究表明，约 42% 的 AI 编码代理消耗的令牌是可避免的浪费** — 重复读取文件、重新发现架构、重新辩论已确定的决策。
---
## ✨ AI 思维导图的作用
AI 思维导图是一个 **MCP（模型上下文协议）服务器**，为你的 AI 代理提供：
| 功能 | 功能描述 | 令牌节省 |
|---------|-------------|---------------|
| 🗺️ **知识图谱** | 将整个代码库解析为可查询的函数、类和关系图谱 | **99%** |
| 📝 **变更跟踪器** | 精确知道自 AI 上次会话以来发生了什么变化 | **80%** |
| 🧠 **持久记忆** | 跨会话记住架构决策、约定和上下文 | **90%** |
| 🗜️ **智能压缩** | 智能压缩构建日志、测试输出、堆栈跟踪 | **50-98%** |
| 📊 **渐进加载** | 只加载需要的部分 — 先加载签名，完整代码仅在需要时加载 | **90%** |
| ⚡ **实时同步** | 文件监视器在编码过程中保持图谱更新 | 始终保持最新 |
### 灵感来源
该项目结合了来自以下项目的成熟技术：
| 来源 | 技术 | 结果 |
|--------|-----------|-------------|
| [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) | 知识图谱 + SQLite | 99% 减少（120 倍更少的令牌） |
| [Aider](https://github.com/Aider-AI/aider) | 基于 PageRank 的仓库地图 | 90%+ 减少 |
| [Mem0](https://github.com/mem0ai/mem0) | 具有衰减的持久记忆 | 3-4 倍成本降低 |
| [context-mode](https://github.com/mksglu/context-mode) | 上下文 sandboxing + BM25 | 98% 上下文减少 |
| [context-mem](https://github.com/context-mem/context-mem) | 渐进披露 | 90%+ 节省 |
---
## 🚀 快速开始
### 方法 1：npx（最快 — 零安装）
```bash
# 直接运行，无需安装任何内容
npx ai-mind-map install
# 就是这样。它会自动检测 Claude、Cursor、VS Code、Windsurf、Antigravity、Zed、Continue.dev
```
### 方法 2：全局安装
```bash
npm install -g ai-mind-map
# 自动检测和配置所有 AI 代理
ai-mind-map install
# 检查一切是否正常运行
ai-mind-map doctor
```
### 方法 3：克隆（用于开发）
```bash
git clone https://github.com/shdra06/ai-mind-map.git
cd ai-mind-map
npm install --legacy-peer-deps
npm run build
node dist/cli.js install
```
### 安装操作
1. ✅ 扫描系统中的 AI 编码代理（Claude、Cursor、VS Code、Windsurf、Antigravity、Zed、Continue.dev）
2. ✅ 将 MCP 配置写入每个代理的配置文件
3. ✅ 部署规则文件，以便代理了解我们的 41 个工具
4. ✅ 运行诊断以验证一切正常运行
### 验证是否正常运行
```bash
ai-mind-map doctor
```
输出：
```
🩺 AI 思维导图 — 诊断
────────────────────────────────────────────────────────
✔ Node.js v24.x (>= 18 required)
✔ SQLite 内存测试通过
✔ TypeScript Build dist/index.js 存在
✔ 代理 检测到 3 个，配置了 3 个
```
---
## 🔌 连接到你的 AI 代理
### 自动（推荐）
```bash
npx ai-mind-map install
```
这会自动检测 **所有 7 个代理** 并为你编写配置。完成。
### 配置写入内容
运行 `install` 后，每个代理的配置文件包含：
```json
{
"mcpServers": {
"ai-mind-map": {
"command": "npx",
"args": ["-y", "ai-mind-map"]
}
}
}
```
这告诉代理：*“当你需要 MCP 工具时，运行 `npx ai-mind-map` ”*。它会在首次使用时从 npm 下载，然后使用缓存。
### 手动设置（如果你愿意）
如果你想手动配置，请在代理的配置文件中添加以下内容：
<details>
<summary><b>Claude Code</b> — <code>~/.claude/claude_desktop_config.json</code></summary>
```json
{
"mcpServers": {
"ai-mind-map": {
"command": "npx",
"args": ["-y", "ai-mind-map"]
}
}
}
```
</details>
<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>
```json
{
"mcpServers": {
"ai-mind-map": {
"command": "npx",
"args": ["-y", "ai-mind-map"]
}
}
}
```
</details>
<details>
<summary><b>VS Code</b> — 设置 JSON（<code>Ctrl+Shift+P</code> → "打开用户设置 JSON")</summary>
```json
{
"mcp.servers": {
"ai-mind-map": {
"command": "npx",
"args": ["-y", "ai-mind-map"]
}
}
}
```
</details>
<details>
<summary><b>Antigravity (Gemini)</b> — <code>~/.gemini/config/mcp.json</code></summary>
```json
{
"mcpServers": {
"ai-mind-map": {
"command": "npx",
"args": ["-y", "ai-mind-map"]
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b> — 设置 JSON</summary>
```json
{
"mcp.servers": {
"ai-mind-map": {
"command": "npx",
"args": ["-y", "ai-mind-map"]
}
}
}
```
</details>
<details>
<summary><b>任意 MCP 兼容代理</b></summary>
```
命令： npx
参数： -y ai-mind-map
传输： stdio
```
</details>
> **💡 配置完成后，重启你的 AI 代理，以便它获取新的 MCP 服务器。**
---
## 🔧 50+ MCP 工具
连接后，你的 AI 代理会自动获取所有工具 + 内置指南，告诉它 **哪个工具调用第一个以及何时使用每个工具**。
### AI 代理如何发现我们的工具
```
AI 代理连接 → 服务器发送 3 件事：
1. ✅ 指令 → "Call mindmap_session_resume FIRST"（自动加载）
2. ✅ 工具/列表 → 所有 50 个工具的描述 + 架构（自动加载）
3. ✅ 提示/列表 → 交互式指南（按需）
```
### 🌐 客户端兼容性
| 客户端 | 是否支持？ | AI 如何学习我们的工具 |
|--------|:------:|------------------------|
| **Claude Code / Desktop** | ✅ | `instructions` + `tools/list` + 提示 + 规则文件（CLAUDE.md） |
| **Cursor** | ✅ | `tools/list` + 规则文件（.cursorrules） |
| **VS Code Copilot** | ✅ | `tools/list` + 规则文件（.github/copilot-instructions.md） |
| **Windsurf** | ✅ | `tools/list` + 规则文件（.windsurfrules） |
| **Antigravity (Gemini)** | ✅ | `tools/list` + 规则文件（.agents/AGENTS.md） |
| **Zed** | ✅ | `tools/list` + MCP 配置 |
| **Continue.dev** | ✅ | `tools/list` + MCP 配置 |
| **任意 MCP 客户端** | ✅ | `tools/list`（通用 MCP 规范） |
| **Ollama / LM Studio** | ⚠️ | 不是原生 MCP 客户端 — 通过 Continue.dev 或 Open WebUI 使用 |
| **Codex (OpenAI)** | ⚠️ | 不原生支持 MCP — 需要 MCP 桥接 |
> **关键**: `tools/list` 与 **每个** MCP 客户端配合使用。规则文件（`CLAUDE.md`, `.cursorrules` 等）作为客户端不尊重 `instructions` 字段的 fallback。
---
### ⚡ 代码内存引擎（v1.4.0） — **新**
| 工具 | 功能描述 | 令牌节省 |
|------|-------------|:---:|
| `mindmap_session_resume` ⭐⭐ | **从上次会话恢复** — 返回已处理的内容、更改内容、项目统计信息 | 15-30K/会话 |
| `mindmap_session_start` | 开始跟踪新的 AI 编码任务 | — |
| `mindmap_session_end` | 结束会话并为下一个代理提供摘要 | — |
| `mindmap_changelog` | **符号级差异** — 自某个时间以来添加/修改/** — 哪些符号被修改了 | 20-50K/会话 |
| `mindmap_hotspots` | 修改频率最高的文件 + 符号 | 5-10K |
| `mindmap_digest` | **2000令牌内的完整项目摘要** | 10-25K/会话 |
| `mindmap_file_digest` | 无需读取文件即可理解文件 | 3-10K/文件 |
| `mindmap_verify` | 基于哈希的内容验证 — 检查缓存的代码是否仍然有效 | 3-10K/文件 |
### 知识图谱（6）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_search` | 按函数/类名或自由文本搜索代码库 |
| `mindmap_get_structure` | 项目架构概览，约 100 令牌 |
| `mindmap_trace_dependencies` | 跟踪调用链 — 调用者调用谁 |
| `mindmap_get_signature` | 无需读取文件即可获取函数签名 |
| `mindmap_find_references` | 查找符号的使用位置 |
| `mindmap_get_file_map` | 文件中所有符号及其行范围 |
### ⭐ 智能工具（3） — **99% 令牌节省**
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_explain` | **关于符号的一切** — 调用者、被调用者、层、影响范围、git 历史记录 — 仅需一次调用 |
| `mindmap_git_changes` | **Git 感知符号级差异** — 哪些函数发生变化，影响哪些函数 |
| `mindmap_smart_search` | **丰富搜索** — 返回完整上下文，使 AI 永远不需要读取文件 |
### 🔍 语义搜索（3）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_semantic_search` | 按**含义**搜索 — “身份验证”、“错误处理”、“数据验证” |
| `mindmap_semantic_stats` | 词汇量、索引覆盖率 |
| `mindmap_synonyms` | 编程同义词查找 |
### 📝 变更跟踪（3）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_what_changed` | 最近代码更改的摘要 |
| `mindmap_session_diff` | 自上次 AI 会话以来发生了什么变化 |
| `mindmap_impact_analysis` | 变更的影响范围 |
### 🧠 记忆（5）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_recall` | 检索相关记忆 |
| `mindmap_remember` | 存储一个事实或约定 |
| `mindmap_get_decisions` | 过去的架构决策 |
| `mindmap_decide` | 记录新的决策 |
| `mindmap_session_summary` | 以前的会话摘要 |
### 🔬 高级分析（7）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_query_graph` | 类似 Cypher 的图查询 |
| `mindmap_dead_code` | 检测未使用的函数 |
| `mindmap_architecture` | 完整的架构概览 |
| `mindmap_get_code_snippet` | 按符号名称读取源代码 |
| `mindmap_search_code` | 类似 grep 的文本搜索 |
| `mindmap_list_projects` | 列出索引的项目 |
| `mindmap_health` | 系统诊断 |
### 🏗️ 流分析（4）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_trace_flow` | 跟踪行为流程 |
| `mindmap_interaction_map` | 完整的交互地图 |
| `mindmap_classify_file` | 将文件分类为架构层 |
| `mindmap_layer_overview` | 层分布概览 |
### 🔍 调试（3）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_debug_changes` | 详细的变更分析 |
| `mindmap_file_before` | 变更前的文件内容 |
| `mindmap_file_history` | 文件变更历史 |
### 🧬 自我进化（3）
| 工具 | 功能描述 |
|------|-------------|
| `mindmap_teach` | **AI 教授新模式** — 持久化每个项目 |
| `mindmap_get_learned` | 查看系统学习的所有规则 |
| `mindmap_forget` | 删除已学习的规则 |
---
## 💻 CLI 命令
所有命令均可使用 `npx`（无需安装）或全局安装后使用（`npm install -g ai-mind-map`）：
```bash
# 设置和诊断
npx ai-mind-map install # 自动配置所有 AI 代理
npx ai-mind-map doctor # 检查一切是否正常运行
npx ai-mind-map install --uninstall # 从所有代理中删除配置
# 索引和搜索
npx ai-mind-map index /path/to/project # 索引代码库
npx ai-mind-map search "authenticate" # 搜索知识图谱
npx ai-mind-map trace "processOrder" # 跟踪调用链
# 记忆
npx ai-mind-map recall "authentication" # 回忆过去的知识
npx ai-mind-map remember "We use JWT" # 存储约定
# 状态
npx ai-mind-map status # 显示索引统计信息
npx ai-mind-map changes # 显示最近的更改
```
---
## ⚙️ 配置
### 项目级配置（可选）
在项目根目录创建 `.mindmap.json` 文件以自定义行为：
```json
{
"languages": ["typescript", "python", "javascript"],
"ignore": ["node_modules", "dist", "*.test.*", "coverage"],
"tokenBudgets": {
"graphResults": 2000,
"changeSummary": 1000,
"memoryRetrieval": 1500,
"fileContent": 3000,
"totalContext": 10000
},
"memory": {
"maxMemories": 500,
"decayRate": 0.95,
"importanceThreshold": 0.1,
"maxDecisions": 200
},
"compression": "moderate",
"watchEnabled": true
}
```
### CLI 选项
```
node dist/index.js [options]
选项：
--project-root <path> 项目根目录（默认为自动检测 git）
--db-path <path> SQLite 数据库位置（默认为 .mindmap/mindmap.db）
--log-level <level> 日志级别：debug | info | warn | error（默认为 info）
```
---
## 🌐 语言支持
基于 Tree-sitter 的 AST 解析，具有自动正则表达式备用：
| 语言 | AST 解析 | 正则表达式备用 | 提取内容 |
|----------|:-----------:|:--------------:|----------|
| JavaScript | ✅ | ✅ | 函数、类、导入、导出 |
| TypeScript | ✅ | ✅ | + 接口、类型、枚举、装饰器 |
| Python | ✅ | ✅ | 函数、类、装饰器、文档字符串 |
| Java | ✅ | ✅ | 类、方法、接口、注解 |
| Go | ✅ | ✅ | 函数、结构体、接口、方法 |
| Rust | ✅ | ✅ | 函数、结构体、特征、实现、枚举 |
| C/C++ | ✅ | ✅ | 函数、类、结构体、宏 |
| C# | ✅ | ✅ | 类、方法、接口、属性 |
| Ruby | ✅ | ✅ | 类、模块、方法、块 |
| PHP | ✅ | ✅ | 类、函数、特征、命名空间 |
| Bash | ✅ | ✅ | 函数、变量、别名 |
| CSS/HTML | ✅ | ✅ | 选择器、类、ID |
---
## 🏗️ 架构
```
┌─────────────────────────────────────────────────────┐
│ AI 思维导图 MCP 服务器 │
│ │
│ ┌─────────────────┐ ┌────────────────┐ ┌────────┐ │
│ │ 知识图谱 │ │ 变更跟踪器 │ │ 内存 │ │
│ │ ─────────────── │ │ ────────────── │ │ ────── │ │
│ │ Tree-sitter AST │ │ Chokidar 监视 │ │ Mem0 │ │
│ │ SQLite + FTS5 │ │ Git 差异 │ │ 风格 │ │
│ │ PageRank │ │ BM25 搜索 │ │ 衰减 │ │
│ └────────┬────────┘ └───────┬────────┘ └───┬────┘ │
│ │ │ │ │
│ ┌────────┴───────────────────┴────────────────┴────┐ │
│ │ 上下文引擎 │ │
│ │ 内容感知压缩（9 种） │ │
│ │ 渐进式披露（3 层） │ │
│ │ 令牌预算管理器 │ │
│ └──────────────────────┬────────────────────────────┘ │
│ │ │
│ 41 个 MCP 工具 │
└─────────────────────────┼───────────────────────────────┘
│ stdio
┌─────────┴──────────┐
│ 你的 AI 代理 │
│ Claude / Cursor / │
│ Copilot / Windsurf │
└────────────────────┘
```
### 内存系统工作原理
AI 思维导图使用 **三层内存架构**（灵感来自认知科学）：
| 层级 | 功能描述 | 令牌成本 | 生命周期 |
|-------|------|-----------|----------|
| **工作内存** | 当前任务上下文 | 完整价格 | 本次对话 |
| **情景记忆** | 会话摘要、最近决策 | 按需检索 | 数天至数周 |
| **语义记忆** | 代码库图谱、架构、约定 | 按需查询 | 永久（带有衰减） |
记忆体有 **重要性分数**，它们：
- 📈 **增加** 当被访问时 (+0.1 per access, capped at 1.0)
- 📉 **衰减** 随着时间推移（可配置，默认为每天 5%）
- 🗑️ **被丢弃** 当重要性分数低于阈值时
这意味着经常使用的记忆体保持存在，而不常用的记忆体自然会淡出。
---
## 📊 预期令牌节省
| 场景 | 没有思维导图 | 有思维导图 | 节省 |
|----------|:----------------:|:-------------:|:-------:|
| 查找函数签名 | ~5,000 令牌 | ~50 令牌 | **99%** |
| 了解项目结构 | ~50,000 令牌 | ~500 令牌 | **99%** |
| 会话间恢复 | ~20,000 令牌 | ~2,000 令牌 | **90%** |
| 跟踪依赖链 | ~30,000 令牌 | ~200 令牌 | **99%** |
| 检查更改内容 | ~10,000 令牌 | ~500 令牌 | **95%** |
| 压缩构建日志 | ~8,000 令牌 | ~400 令牌 | **95%** |
---
## 🤝 贡献
贡献欢迎！以下是贡献步骤：
1. Fork 仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 进行更改
4. 运行构建：`npm run build`
5. 提交：`git commit -m "Add amazing feature"`
6. 推送：`git push origin feature/amazing-feature`
7. 打开拉取请求
### 开发
```powershell
# 监视模式（自动重新编译）
npm run dev
# 不编译的情况下进行类型检查
npx tsc --noEmit
# 本地运行服务器
node dist/index.js --project-root . --log-level debug
```
---
## 📄 许可证
MIT — 可随意使用。详见 [LICENSE](LICENSE)。
---
## 🙏 致谢
建立在巨人的肩膀上：
- [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) — 知识图谱架构（99% 令牌减少）
- [Aider](https://github.com/Aider-AI/aider) — 具有 PageRank 排名的仓库地图
- [Mem0](https://github.com/mem0ai/mem0) — 具有重要性衰减的持久记忆
- [context-mode](https://github.com/mksglu/context-mode) — 上下文 sandboxing 采用 BM25
- [context-mem](https://github.com/context-mem/context-mem) — 渐进式披露模式
- [CocoIndex](https://github.com/cocoindex-io/cocoindex-code) — 增量 AST 索引
- [Repomix](https://github.com/yamadashy/repomix) — 代码库压缩技术
- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) — 多语言 AST 解析
- [MCP 协议](https://modelcontextprotocol.io) — 使这一切成为可能的协议
---
<p align="center">
<strong>⭐ 如果它为你节省了令牌，请给这个仓库点赞！</strong>
</p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器