DeusData/codebase-memory-mcp · 上手攻略

  • 仓库：DeusData/codebase-memory-mcp
  • 链接：https://github.com/DeusData/codebase-memory-mcp
  • 分类：trending / rag / database / code-intelligence
  • 作者：Tom
  • 更新：2026-07-03

把整个仓库索引成一张"函数/类/调用链/HTTP 路由/跨服务调用"的知识图谱，让 Claude Code、Codex、Cursor、Zed 等 AI 编码 Agent 用 MCP 工具直接查图，而不是反复 grep 整库。单文件静态二进制、零依赖、零 API key、158 种语言、亚毫秒查询、token 用量减少 99%。

1. 是什么

codebase-memory-mcp（仓库路径也叫 codebase-memory）是一个用 C 写的 MCP（Model Context Protocol）服务器。它把任意代码库通过 tree-sitter 的 AST 解析 + Hybrid LSP（轻量级本地类型解析，参考了 typescript-go / pyright / gopls / Roslyn / Eclipse JDT / rust-analyzer 的算法思路）转成一张持久化的 SQLite 知识图谱，节点包括函数、类、调用链、HTTP 路由、gRPC/GraphQL/tRPC 端点、事件 channel（EMITS / LISTENS_ON）、基础设施节点（Dockerfile / K8s manifest / Kustomize overlay）等，边类型覆盖 CALLS / IMPORTS / DEFINES / IMPLEMENTS / INHERITS / HTTP_CALLS / ASYNC_CALLS / EMITS / LISTENS_ON / DATA_FLOWS / SIMILAR_TO / SEMANTICALLY_RELATED 12+ 种。

它本身不含 LLM——把"自然语言 → 图查询"这一段让给你已经在用的 MCP 客户端（Claude Code / Codex CLI / Cursor / Gemini CLI / Zed / OpenCode / Antigravity / Aider / KiloCode / VS Code / OpenClaw / Kiro，README 写 11 个），所以不烧额外 token 调 API、不需要 Ollama、不需要 Docker。

整套设计 + benchmark 写在预印本 arXiv:2603.27277 Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP。在 31 个真实仓库上评估，83% 答准率，token 用量是 grep 法的 1/10，工具调用次数降到 1/2.1。

2. 解决什么问题

AI 编码 Agent 跑中型以上仓库时有两个老毛病：

  1. 靠 grep + Read 反复 "摸索"："ProcessOrder 谁在调？" 这个问题在 50k LOC 的库里，Agent 经常要 grep → read → grep → read，烧掉几十万 token、几十次工具调用。
  2. 改完代码不知道影响面：重构一个函数，谁会跟着爆？跨服务调用怎么处理？

codebase-memory-mcp 直接给你一张图：

  • get_architecture 一次返回语言分布、package 拓扑、entry points、routes、hotspots、模块边界、Louvain 社区检测结果。
  • trace_path(function_name="ProcessOrder", direction="inbound") 直接走图查反向调用链，< 10ms。
  • detect_changes 把当前 git diff 映射到受影响符号 + 风险分级。
  • semantic_query 在图上跑向量搜索（自带 Nomic nomic-embed-code 嵌入，40K tokens / 768d int8，编译进二进制）。
  • find_dead_code 全图扫出零调用方函数（自动排除 entry point）。
  • query_cypher 写 Cypher-like 查询自由探索：MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name。

简单说：让 Agent "问图" 而不是 "翻文件"。

3. 快速安装

一行脚本会自动检测平台、下载预编译二进制、自动 ad-hoc 签名（macOS 免手动 xattr / codesign）、再扫到你机器上装了哪些 AI CLI，把 MCP server 条目、skill 文件、pre-tool hook 一起写进配置。

macOS / Linux

# 标准（纯 MCP server）
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

# 带 3D 图可视化 UI（http://localhost:9749）
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

可选参数：--skip-config（只要二进制，不要写 agent 配置）、--dir=<path>（自定义安装目录）。

Windows (PowerShell)

Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
# 强烈建议先 notepad install.ps1 看一眼
.\install.ps1

手动安装

从 releases 拉对应平台包：

# macOS / Linux
tar xzf codebase-memory-mcp-*.tar.gz
./install.sh

# Windows
Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
.\install.ps1

源码编译（开发者）

README 提到 Go（带 CGO）作为主开发栈，但 release 二进制是静态链接的 C 原生产物。社区文档里给出过：

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
CGO_ENABLED=1 go build -o codebase-memory-mcp ./cmd/codebase-memory-mcp/
sudo mv codebase-memory-mcp /usr/local/bin/

编译完一样用 install.sh 注册到各 Agent。

验证

装完重启你的 AI CLI。在 Claude Code 里 /mcp 应当能看到 codebase-memory-mcp 出现在可用服务器列表里；Codex CLI 里新工具在下一轮 session 出现。直接对它说：

Index this project

它会调 index_repository 跑全量索引；之后再问"what calls foo?" 就会走 trace_path 而不是 grep。

4. 核心用法

4.1 14 个 MCP 工具速查（按 README 整理，部分为高频）

工具 作用 典型耗时
index_repository 全量索引当前仓库到 SQLite Django 49k 节点 ~6s；Linux kernel 28M LOC ~3 min
get_architecture 一次性返回语言、packages、entry points、routes、hotspots、layers、clusters 几十 ms
trace_path 沿边遍历调用链（inbound / outbound / both） < 10 ms
search_graph 结构化搜索：name regex、label 过滤、min/max degree、file scoping < 10 ms
search_code 图增强 grep（只在已索引文件里） 视仓库
semantic_query 向量搜索（Nomic embed，编译进二进制，无 API key） 几十 ms
find_dead_code 找零调用方函数（自动排除 entry point） 全仓 ~150 ms
detect_changes 把 git diff 映射到受影响符号 + 风险分级 < 100 ms
query_cypher 自定义 Cypher-like 查询 < 1 ms
manage_adr 持久化架构决策记录（ADR）跨 session 写 SQLite
cross_service_summary 多仓索引后的跨服务架构汇总 视规模
cli 直接命令行模式（不开 MCP） —

4.2 CLI 模式（不开 MCP 也行）

codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*"}'
codebase-memory-mcp cli trace_path '{"function_name": "ProcessOrder", "direction": "inbound"}'

适合脚本化、CI、临时调试。

4.3 配合 Claude Code 的典型对话

你：what calls ProcessOrder?
→ Claude Code 调 trace_path(function_name="ProcessOrder", direction="inbound")
→ 拿到结构化调用链
→ 翻译成自然语言回答你

你：show me the architecture of this project
→ 调 get_architecture
→ 返回语言/包/入口/路由/hotspot/模块边界/Louvain 社区

你：what will break if I refactor this function?
→ 调 detect_changes
→ 返回受影响符号 + 风险等级

4.4 自动索引 + 后台监听

codebase-memory-mcp config set auto_index true
# 限制单仓最多处理 50k 个文件
codebase-memory-mcp config set auto_index_limit 50000

启用后，新仓库在 MCP session 启动时自动建索引；老仓库被后台 watcher 持续监听 git 改动并增量重建。

4.5 跨团队共享图（杀手级特性）

把下面这个文件 commit 到仓里，队友 clone 完第一次启动 codebase-memory-mcp 时，先 import 这个压缩图再增量——免去全量重建：

.codebase-memory/graph.db.zst    # zstd 1.5.7 压缩，典型 8~13:1
  • Best（zstd -9 + 剥索引 + VACUUM INTO）：在显式 index_repository 时生成。
  • Fast（zstd -3）：watcher 增量写出来用于低延迟共享。
  • 自动在 .gitattributes 加 merge=ours，避免队友并发编辑产生冲突。
  • 不想共享就 .gitignore 掉 .codebase-memory/。

README 把它类比成 "graphify 的 graphify-out/ 目录，但单文件、压缩、双档导出、merge 不打架"。

4.6 3D 图可视化（仅 ui 包）

codebase-memory-mcp --ui=true --port=9749

浏览器开 http://localhost:9749，可以看到多 galaxy 视图：函数、类、路由、调用边、相似节点聚类。适合 onboarding 新人 / 解释架构 / 找"那块代码到底在哪"。

4.7 14 MCP 工具覆盖的边类型

CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS
HTTP_CALLS, ASYNC_CALLS        // 跨服务
EMITS, LISTENS_ON              // channel
DATA_FLOWS                     // 形参 ↔ 实参 + 字段访问链
SIMILAR_TO                     // MinHash + LSH 克隆检测
SEMANTICALLY_RELATED           // 词汇不同但同义（score ≥ 0.80）
CROSS_*                        // 跨多仓

5. 典型适用场景

  • 中型 monorepo / 长期维护的老项目：Grep 慢、Read 多、Agent 老迷路。先 index 一次，之后的会话都走图。
  • 跨服务 / 微服务：HTTP 路由 ↔ 调用点匹配、gRPC/GraphQL/tRPC 端点解析、EMITS/LISTENS_ON 事件 channel——一个 get_architecture 看完全图。
  • Code Review / 重构前风险评估：detect_changes + trace_path 比人脑走读稳。
  • 新人 Onboarding：3D UI + get_architecture 一次出图，比读一周文档快。
  • Infrastructure-as-code 工程：Dockerfile / K8s manifest / Kustomize overlay 也作为图节点，能看 IMPORTS 边跨 IaC 引用。
  • 跨团队共享索引：把 .codebase-memory/graph.db.zst commit 进去，新人 clone 后秒级进入工作状态。

6. 坑与注意

  1. 不内置 LLM = 优势也是约束：所有"自然语言 → 图查询"翻译都依赖你正在用的 Agent 解释能力。Agent 弱的时候，回答也会偏——你得会写 Cypher-like。
  2. Hybrid LSP 覆盖有限：Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 共 11 种语言有"语义类型解析"，其余 147 种语言只有 AST 级（结构对，但跨文件类型推断会弱）。Go 项目用得最舒服。
  3. 大型 monorepo 首次索引吃内存：Linux kernel 全量索引 3 分钟，峰值 RAM 较吃紧；config set auto_index_limit 50000 控上限。Watcher 是后台增量，不会再卡。
  4. 写入 agent 配置文件：README 明确提示"this tool reads your codebase and writes to your agent configuration files"——它是设计如此。介意的话跑 install.sh 时加 --skip-config，再手动把 MCP 条目加进你想用的那个 CLI。
  5. macOS 配额属性 / 代码签名：安装脚本里自动 xattr -d com.apple.quarantine + ad-hoc 签名；如手动下载二进制，要自己处理。Windows 第一次跑可能触发 SmartScreen，需要"更多信息 → 仍要运行"。
  6. SLSA / 签名 / VirusTotal 70+ 引擎扫描是默认流程，但官方不收集遥测——隐私是优势，但真出问题（内存泄漏、性能退化）也没人主动看到。需要你 CBM_DIAGNOSTICS=1 启动后让服务器写 $TMPDIR/cbm-diagnostics-<pid>.ndjson（每 5s 一行 RSS / page_faults / fd / queries），再自己提交。
  7. 版本节奏快：最近 commit 在 2026-07-02，CLI / MCP tool 名称可能小版本变动；建议 codebase-memory-mcp update 保持最新，旧 release 的 .codebase-memory/graph.db.zst 不保证向前兼容。

7. 与同类对比

工具 形态 区别
Sourcegraph / Cody SaaS + 本地索引 闭源、按月付、远程索引；codebase-memory 离线、零 API key
Aider repo map 内嵌在 Aider 里 跟 Aider 绑死、无 MCP 暴露、图不持久化
cursor / Windsurf 内置 codebase indexing 闭源 不开源、不可跨 CLI 复用、跨服务能力弱
graphify 相似思路（图 + 导出） graphify 的导出是目录，codebase-memory 是单文件 zstd + 两档 + gitattributes merge=ours，更适合团队
ctags / LSP 单文件方案 经典 没有跨文件类型推断、不能给 Agent 用 MCP 调、没有调用链图
在 Agent 里直接 grep + Read 0 装 慢、烧 token、工具调用次数爆炸；benchmark 里 ~412k tokens vs ~3.4k tokens

一句话：codebase-memory-mcp 是"AI 编码 Agent 友好的、单二进制可分发的、把 grep 时代换成图查询时代"的本地代码智能引擎。

8. 一句话推荐结论

在 Claude Code / Codex / OpenCode 上跑中型以上仓库的人，闭眼 curl -fsSL ... | bash -s -- --ui 装上，索引一次后你会立刻发现 Agent 不再"反复翻文件"了。 这是 2026 年最值得装的一个 MCP server——前提是你愿意把 .codebase-memory/graph.db.zst commit 到仓里，让队友同步受益。