项目定位与目标

AI Mind Map 是一个 MCP（Model Context Protocol）服务器，其核心目标是显著降低 AI 编程助手（如 Claude、Cursor、Copilot 等）在处理代码库时的 Token 消耗。根据官方说明，它通过持久化的代码库记忆、知识图谱和智能上下文管理，可实现 80–99% 的 Token 减少，从而避免 AI 反复读取整个代码库造成的浪费。

资料来源：README.md:1-30

项目以 ai-mind-map 作为 npm 包名发布，并通过 bin 字段同时提供 ai-mind-map（CLI 入口）和 ai-mind-map-server（MCP 服务器入口）两个可执行命令，方便用户通过 npx ai-mind-map install 一键完成安装与配置。

资料来源：package.json:1-50

技术栈与依赖

项目使用 Node.js（>=18.0.0）作为运行环境，核心依赖包括：

资料来源：package.json:50-90

type: "module" 表明整个项目采用原生 ESM，TypeScript 通过 tsc 编译为 dist/ 目录下的 JavaScript 输出，并附带 prepublishOnly 钩子确保发布前完成构建与测试。

核心架构

AI Mind Map 的整体架构由三个主要子系统组成：知识图谱（Knowledge Graph）、变更追踪（Change Tracker）、记忆系统（Memory），它们共同汇聚到 上下文引擎（Context Engine），并最终通过 MCP 协议以 stdio 方式暴露给 AI Agent。

flowchart TB
    subgraph K["知识图谱"]
        TS[Tree-sitter AST]
        SQL[SQLite + FTS5]
        PR[PageRank]
    end
    subgraph C["变更追踪"]
        CH[Chokidar Watcher]
        GIT[Git Diff Engine]
        CL[Change Log + BM25]
    end
    subgraph M["记忆系统"]
        MEM[Persistent Memory]
        DEC[Decisions]
    end
    subgraph E["上下文引擎"]
        CMP[Content-Aware Compression]
        PD[Progressive Disclosure 3-Tier]
        TBM[Token Budget Manager]
    end
    K --> E
    C --> E
    M --> E
    E -->|MCP stdio| AI[AI Agent]

资料来源：README.md:120-180、src/context/progressive-disclosure.ts:1-30

关键模块说明

内容感知压缩（Content-Aware Compression）

compressor.ts 提供三种压缩等级 —— minimal（清理空白与注释）、moderate（保留签名与文档注释，用 { ... } 替换函数体）、aggressive（仅保留签名或仅保留错误信息）。它会自动检测 source_code、build_log、test_output、stack_trace、json_data、markdown、diff、config_file、plain_text 共 9 种内容类型并选用相应策略。

资料来源：src/context/compressor.ts:1-60

渐进式披露（Progressive Disclosure）

progressive-disclosure.ts 实现三层上下文加载：Tier 1（常驻，≤500 tokens） 包含项目身份、目录骨架与当前任务；Tier 2（可搜索，≤2000 tokens） 包含知识图谱查询结果、近期变更、相关记忆与活跃决策；Tier 3（按需加载） 才输出完整压缩文件内容、详细测试输出与历史 diff。每个层级都有独立的 Token 预算。

资料来源：src/context/progressive-disclosure.ts:1-50

Token 预算管理

token-budget.ts 借鉴 Aider 的 --map-tokens 思路，对 graphResults、changeSummary、memoryRetrieval、fileContent 四个组件分别分配预算，并支持智能截断、动态再分配与格式化预算报告。

资料来源：src/context/token-budget.ts:1-60

变更追踪

diff-engine.ts 基于 simple-git 提供 Git 感知的差异分析，并在项目非 Git 仓库时回退到文件系统时间戳。change-log.ts 则使用 SQLite + FTS5 实现持久化变更历史，支持 BM25 排序检索、会话管理与按符号/时间范围查询。

资料来源：src/change-tracker/diff-engine.ts:1-50、src/change-tracker/change-log.ts:1-60

三层记忆模型

AI Mind Map 借鉴认知科学中的记忆分层，将记忆划分为：

• 工作记忆（Working Memory）：当前任务上下文，全量加载；
• 情景记忆（Episodic Memory）：会话摘要与近期决策，按需检索；
• 语义记忆（Semantic Memory）：代码库图谱、架构与约定，仅查询、永不整体导出。

每条记忆都有重要性评分，访问时递增、随时间衰减（默认每天 5%），低于阈值时被剪枝，确保有用记忆得以保留、陈旧记忆自然消退。

资料来源：README.md:180-220

安装与运行

最新 v2.0.0 版本在 CLI、Cyphter-like 图查询、测试套件、CI/CD 与安装器方面完成了生产级升级。用户可执行 npx ai-mind-map install 自动检测并配置 7 种主流 AI Agent；ai-mind-map doctor 用于诊断环境；ai-mind-map index /path/to/project 用于建立索引。

资料来源：README.md:60-100

项目定位与运行前置条件

AI Mind Map 本质上是一个本地运行的 MCP 服务器，通过 stdio 协议向 AI 代理暴露 41 个工具，覆盖知识图谱查询、语义搜索、变更追踪、记忆系统与高级分析等能力 资料来源：[README.md:1-80]。整个服务器以 Node.js 进程方式驻留用户侧，依赖本地 SQLite 索引、Tree-sitter 解析器和 Git 仓库信息。

运行前必须满足的最低前置条件：

仓库要求 MIT 协议、TypeScript ^5.8.3 编译、tsx ^4.22.4 直接执行，因此开发模式也只需 Node.js 18+ 即可启动 资料来源：[package.json:1-80]。

安装流程与跨平台脚本

仓库提供三条并行的安装入口，分别面向 Unix 类系统与 Windows 系统，目的是把"克隆 → 依赖安装 → 构建 → 注册到代理"串成一步。

通用安装步骤

1. 克隆仓库并进入目录。
2. 执行对应平台的安装脚本：

• macOS / Linux：./install.sh
• Windows PowerShell：./install.ps1
• Windows CMD：./setup.bat

1. 脚本将完成 npm install、npm run build，并把构建产物 dist/ 暴露给后续的代理注册步骤。

src/install.ts 承担安装编排逻辑，封装了与各平台脚本共享的步骤（依赖检查、构建、写入代理配置）资料来源：[src/install.ts:1-120]。这种"脚本外壳 + TS 内核"的设计，让 PowerShell / Bash 脚本保持轻量、只做平台差异处理，把真正的安装语义集中在 TypeScript 模块里以便单测覆盖。

跨平台差异点

• 可执行权限：Unix 脚本需要在首次运行前 chmod +x install.sh；Windows 脚本由 PowerShell 执行策略决定，可能需要 Set-ExecutionPolicy -Scope Process Bypass 临时放行。
• 路径分隔符：install.ps1 与 setup.bat 自动处理反斜杠与盘符，而 install.sh 使用 POSIX 路径。
• 构建产物：npm run build 在所有平台都生成相同的 dist/index.js，这是 MCP stdio 通信的入口 资料来源：[README.md:1-80]。

代理集成：把 41 个工具接入 AI

安装完成后，需要让 AI 代理知道如何启动 MCP 服务器。这通过编辑代理自己的配置文件实现。

配置结构

AI Mind Map 期望的 MCP 配置遵循标准 JSON 形态，关键字段包括：

• command：Node.js 可执行文件绝对路径。
• args：数组，第一个元素是 dist/index.js 的绝对路径，后续参数可包含 --project-root <path>、--log-level <info|debug>。
• env：可选，用于覆盖默认行为（如自定义索引目录）。

docs/AGENT_GUIDE.md 中记录了 Claude Desktop、Cursor、Continue、Cline 等代理的具体配置片段，仓库还在 templates/CLAUDE.md 提供了一份 Claude 专属的 system prompt 模板，建议与 MCP 配置一并启用 资料来源：[docs/AGENT_GUIDE.md:1-200]资料来源：[templates/CLAUDE.md:1-80]。

推荐的代理工作流

集成后，AI 代理可在一次会话内串联调用知识图谱、变更追踪与记忆工具：

flowchart LR
    A[AI 代理<br/>Claude/Cursor] -- stdio --> B[MCP 服务器<br/>dist/index.js]
    B --> C[知识图谱<br/>SQLite + Tree-sitter]
    B --> D[变更追踪<br/>simple-git + chokidar]
    B --> E[记忆系统<br/>Mem0 风格]
    B --> F[上下文引擎<br/>压缩 + 渐进披露]
    A -- 41 个工具调用 --> B

该工作流的核心收益来自 三段式记忆（工作记忆、情景记忆、语义记忆）与 三档渐进披露（Tier 1 ≤500 tokens、Tier 2 ≤2 000 tokens、Tier 3 按需）资料来源：[README.md:1-120]。

常见失败模式与排错

集成过程中最常遇到的问题集中在依赖、路径与协议握手三方面。

1. Node.js 版本过低：若运行 node -v 输出低于 18.0.0，better-sqlite3 与 tree-sitter 的 native binding 可能加载失败。engines 字段已强制声明该下限 资料来源：[package.json:1-80]。
2. 未执行 npm run build：代理调用 dist/index.js 时报"模块未找到"，通常因为只跑了 npm install。install.sh / install.ps1 默认会执行构建，但手动开发流程可能遗漏。
3. 项目根目录错误：服务器通过 --project-root 定位目标仓库，若代理配置里写错路径，Tree-sitter 索引与 Git diff 都会指向空目录。所有变更追踪工具（mindmap_what_changed、mindmap_session_diff）都会返回空结果。
4. stdio 握手失败：部分代理仅支持 HTTP/SSE 传输，而 AI Mind Map 当前仅暴露 stdio 资料来源：[README.md:1-80]。需要在代理侧选择"本地 stdio MCP 服务器"模式。
5. 可选语言解析器缺失：tree-sitter-bash、tree-sitter-c、tree-sitter-go 等放在 optionalDependencies 中，安装失败不会阻断主流程，但对应语言的符号提取会降级为正则启发式 资料来源：[package.json:1-80]。

See Also

• 知识图谱与 PageRank 排序：知识图谱与搜索
• 上下文压缩与 Token 预算：上下文引擎
• 变更追踪与 Git 集成：变更追踪
• 记忆系统与决策记录：记忆与决策

概览

AI Mind Map 是一个基于 Model Context Protocol (MCP) 的服务端进程，目标是减少 AI 编码助手在阅读代码库时产生的 token 消耗。package.json 中将其定义为 "MCP server that reduces AI coding agent token usage by 80-99%"，并通过 bin 字段提供 ai-mind-map 与 ai-mind-map-server 两个可执行入口（package.json:18-21）。

整体设计遵循分层原则：底层是多语言 AST 解析与 SQLite 知识图谱；中层是 git/文件系统感知的变更追踪与记忆系统；上层是面向 LLM 的上下文工程（压缩、预算管理、渐进披露）。三层共同对外暴露 41 个 MCP 工具，通过 stdio 与宿主 Agent（Claude、Cursor、Copilot 等）通信（README.md:165-189）。

核心架构层次

下图描绘了运行时各模块的依赖关系与数据流向：

flowchart TB
    subgraph Host["AI Agent (Claude / Cursor / Copilot)"]
        UI[对话界面]
    end

    subgraph Core["AI Mind Map MCP Server"]
        KG[知识图谱<br/>Tree-sitter + SQLite FTS5 + PageRank]
        CT[变更追踪<br/>Chokidar + simple-git]
        MEM[记忆系统<br/>Mem0 风格 + 衰减]
        CE[上下文引擎]
        CE --> CMP[内容感知压缩]
        CE --> TBM[Token 预算管理]
        CE --> PD[渐进披露]
        KG --> CE
        CT --> CE
        MEM --> CE
    end

    UI <-->|stdio / MCP| Core

知识图谱、变更追踪、记忆系统三个子模块互相独立，但都将原始数据交给 Context Engine 做统一整形，再通过 MCP 协议输出。这种"中间层聚合"的设计避免了每个工具重复实现 token 控制逻辑（README.md:165-189）。

上下文引擎（Context Engine）

上下文引擎是 AI Mind Map 区别于普通 codebase 索引器的关键，由三个相互协作的组件构成。

内容感知压缩

src/context/compressor.ts 实现了 CompressionLevel（minimal / moderate / aggressive）与 ContentType（source_code、build_log、test_output、stack_trace、json_data、markdown、diff、config_file、plain_text）二维分桶策略。detectContentType 通过对 diff 头、stack trace、测试输出等特征做正则匹配来决定走哪条压缩管线（src/context/compressor.ts:73-101）。compressSourceModerate 保留签名、导入语句、文档注释，将函数体替换为 { ... }，以中等代价换取高语义保留（src/context/compressor.ts:148-186）。

Token 预算管理

src/context/token-budget.ts 把响应按 graphResults、changeSummary、memoryRetrieval、fileContent 四个组件分别记账，通过 BudgetReport 给出剩余预算与相对原始全文的节省百分比（src/context/token-budget.ts:27-49）。当组件超出预算时，会调用 truncateToTokenBudget 在逻辑边界（行/段落）处截断，避免切断符号名或括号。

渐进披露（Progressive Disclosure）

src/context/progressive-disclosure.ts 定义了三层上下文：

• Tier 1（Always Loaded，≤ 500 tokens）：项目身份、目录骨架、约定、当前任务。
• Tier 2（Searchable，≤ 2000 tokens）：图谱查询结果、最近变更、相关记忆、活跃决策。
• Tier 3（On-Demand）：完整文件内容、测试输出、历史 diff，按需取用（src/context/progressive-disclosure.ts:48-58）。

buildContextPackage 在调用时按预算动态分配 Tier 3 容量，并通过 breakdown 数组返回每个组件的实际 token 占用与上限（src/context/progressive-disclosure.ts:140-176）。这种"按需展开"的模式直接对应 README 中宣称的 80-99% token 节省（README.md:191-205）。

变更追踪与工具暴露

src/change-tracker/diff-engine.ts 提供 git 感知的差异分析：优先通过 simpleGit 拉取 DiffResultTextFile，项目不在 git 控制下时回退到 fs.stat 的 mtime 比对。DiffSummary 同时返回人类可读文本和结构化的 FileChange[]，供上下文引擎在 Tier 2 注入（src/change-tracker/diff-engine.ts:27-43）。

最终，41 个 MCP 工具（mindmap_explain、mindmap_search、mindmap_recall 等）通过 src/index.ts 注册到 @modelcontextprotocol/sdk 上，宿主 Agent 通过 stdio 调用。每个工具在内部都会调用上下文引擎的三个组件，从而保证响应始终受预算约束（package.json:55-56）。

部署与生命周期

CLI 入口 dist/cli.js 暴露 install、doctor、index、search、trace、recall、remember、status、changes 等子命令；其中 install 会探测 7 种 AI Agent 并写入 MCP 配置，doctor 校验 Node 版本、SQLite、构建产物与 Agent 连接状态（README.md:97-121）。生产构建依赖 prepublishOnly 脚本：先 tsc 编译再 npm test，确保发布前通过 npx tsx --test 单元测试（package.json:23-34）。

See Also

• README.md
• package.json
• src/context/compressor.ts
• src/context/token-budget.ts
• src/context/progressive-disclosure.ts
• src/change-tracker/diff-engine.ts

概述

AI Mind Map 是一个 MCP（Model Context Protocol）服务器，其核心目标是将 AI 编码代理的 token 消耗降低 80–99%。该系统由两大支柱构成：知识图谱（Knowledge Graph） 与 变更跟踪（Change Tracker）。知识图谱负责把代码库静态地建模为可查询的函数、类与调用关系图；变更跟踪则负责在会话之间捕捉"自上次以来发生了什么"。两者共同为上下文引擎（Context Engine）提供原材料，再经由内容感知压缩、分层加载与 token 预算管理，输出给 LLM 代理使用。资料来源：README.md:18-32

在 v2.0.0 版本中，项目从单纯的代码库记忆工具升级为生产级系统，新增了 CLI、Cypher 查询、CI/CD 流程与安装脚本，同时修复了 package-lock.json 未包含在 CI 构建中的问题。资料来源：package.json:34-58

知识图谱

架构组成

知识图谱子系统在 README 的架构图中占据左侧模块位置，由三类组件协作：

它把代码库解析为可查询的函数、类与调用关系节点，并对外暴露 6 个核心工具（mindmap_search、mindmap_get_structure、mindmap_trace_dependencies、mindmap_get_signature、mindmap_find_references、mindmap_get_file_map）。资料来源：README.md:90-105

智能工具层

在基础图查询之上，AI Mind Map 提供了 3 个"智能工具"，号称可实现 99% 的 token 节省：

• mindmap_explain：单次调用返回一个符号的签名、调用者、被调用者、所在架构层、变更影响半径与 git 历史。
• mindmap_git_changes：基于 git 的符号级 diff，精确告知哪些函数被修改、哪些下游被影响。
• mindmap_smart_search：富上下文搜索，使 AI 不必再读取原始文件。

资料来源：README.md:108-120

flowchart LR
    A[代码库源码] --> B[Tree-sitter AST 解析]
    B --> C[SQLite + FTS5 存储]
    C --> D[PageRank 排序]
    D --> E[知识图谱查询]
    E --> F[41 个 MCP 工具]
    E --> G[上下文引擎]
    H[Chokidar 文件监听] --> B
    I[Git Diff] --> G

变更跟踪

Diff 引擎

变更跟踪的核心实现在 src/change-tracker/diff-engine.ts 中。该模块是无状态的（stateless）——所有公共方法都接收必要参数并返回结构化结果，类实例仅用于保存项目根路径与懒加载的 simpleGit 句柄。资料来源：src/change-tracker/diff-engine.ts:38-52

引擎通过 simpleGit 库进行 git 感知分析，生成富有人类可读性的变更摘要，适合作为 LLM 会话的前导上下文，让代理在动手前就知道自上次访问后项目发生了什么。资料来源：src/change-tracker/diff-engine.ts:3-12

核心数据模型

DiffSummary 是变更跟踪的聚合产物，其字段包括：

• text：多行人类可读摘要，可直接注入上下文。
• changes：逐文件变更记录数组（FileChange[]）。
• totalLinesAdded / totalLinesRemoved：新增与删除行数总计。
• filesAffected：受影响文件数。
• usedGit：是否真正使用了 git（否则回退到文件系统时间戳）。

DiffQueryOptions 则支持通过 includePatterns 与 excludePatterns 进行 glob 过滤，让用户能精确控制变更摘要的范围。资料来源：src/change-tracker/diff-engine.ts:21-36

Git 不可用时的回退

如果项目未处于 git 控制下，引擎会回退到文件系统时间戳分析，通过 node:fs/promises 的 stat 与 readdir 列举文件元信息。资料来源：src/change-tracker/diff-engine.ts:3-12

与上下文引擎的协作

变更跟踪与知识图谱的输出并不是直接喂给 LLM 的，而是先经过上下文引擎的三道处理：

1. 内容感知压缩（src/context/compressor.ts）：自动检测 9 种内容类型（source_code、build_log、test_output、stack_trace、json_data、markdown、diff、config_file、plain_text），并按 minimal / moderate / aggressive 三级强度施加不同的压缩策略。例如源码中度压缩会保留签名与文档注释、替换函数体为 { ... }。资料来源：src/context/compressor.ts:7-26, src/context/compressor.ts:121-160
2. Token 预算管理（src/context/token-budget.ts）：为 graphResults、changeSummary、memoryRetrieval、fileContent 四个组件分别分配预算，并在超限时进行智能截断。资料来源：src/context/token-budget.ts:25-44
3. 渐进式披露（src/context/progressive-disclosure.ts）：把上下文分为三层——Tier 1（始终加载，≤ 500 token）、Tier 2（可搜索，≤ 2000 token）、Tier 3（按需加载），确保代理先看到项目骨架与近期变更，细节仅在需要时调入。资料来源：src/context/progressive-disclosure.ts:7-30

通过这种"图谱 + 变更 → 压缩 → 预算 → 分层"的流水线，AI Mind Map 实现了在保持代码理解深度的同时大幅压低 token 消耗。

常见使用模式

README 推荐的三种典型场景如下：

• 理解一个符号：调用 mindmap_explain 即可获得签名、调用链、变更影响与历史。
• 查看自上次会话以来的变更：调用 mindmap_session_diff 或 mindmap_what_changed，由 diff 引擎生成摘要。
• 实时同步：通过 Chokidar 文件监听器在编码时持续更新图谱，使知识库始终保持新鲜。

资料来源：README.md:108-140, README.md:155-170

故障排查

参见

• 上下文压缩引擎：src/context/compressor.ts
• Token 预算管理器：src/context/token-budget.ts
• 渐进式披露：src/context/progressive-disclosure.ts
• 变更跟踪 Diff 引擎：src/change-tracker/diff-engine.ts
• 项目主页：README.md

Pitfall Log / 踩坑日志

项目：shdra06/ai-mind-map

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/shdra06/ai-mind-map | host_targets=mcp_host, claude, cursor, claude_code

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/shdra06/ai-mind-map | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/shdra06/ai-mind-map | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/shdra06/ai-mind-map | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map | release_recency=unknown