AI 编程 agent 在大仓库里干活,大部分预算都花在「四处张望」上。它 grep 一下,读个文件,再 grep,再打开三个文件,光是重建一张调用图就烧掉几千 token。codebase-memory-mcp 直接冲这一步去:先把代码建成一张持久的图,然后通过 MCP 回答结构性问题(谁调用了它、它 import 了什么、改它会牵动哪些地方),agent 查图就行,不必反复读文件。

它用 C 写成,是一个零运行时依赖的单一静态二进制文件,不需要 Docker,也不需要 API key。这一点值得先点出来,因为它决定了这个项目的整体气质。

它到底做什么

服务端用 tree-sitter 解析 158 种语言的代码,把结果以图的形式存进 SQLite:函数、类、路由、import、调用边。在语法层的 tree-sitter 之上,它对 11 种语言(Python、TypeScript/JavaScript、Go、Rust、Java、Kotlin、C、C++、C#、PHP)再跑一遍叫「Hybrid LSP」的类型解析,能处理泛型和继承,所以像 user.profile.display_name() 这样的调用会顺着类型解析连到三个模块外的那个真实方法,靠的是类型信息。

它内部没有 LLM。设计上假定你的 MCP 客户端(Claude Code、Codex、Gemini CLI 等)就是那个语言模型,所以二进制只当一个纯结构后端,对外暴露 14 个工具:图搜索、调用链追踪、一个只读的 openCypher 子集、git diff 影响分析、死代码检测,以及架构总览。对一个 MCP 工具来说这个取舍是对的,也让二进制保持小而离线。

为什么这阵子有人盯它

卖点是速度和省 token,README 里的数字也很大:Linux 内核(2800 万行、7.5 万文件)约 3 分钟建完索引,Cypher 查询低于 1 毫秒,5 个结构性查询约 3,400 token,而同样的逐文件探索约 41.2 万 token。这些要当作作者自己的基准看待,跑在 Apple M3 Pro 上,细节写在项目的预印本里。图查询胜过反复 grep 是讲得通的,但你的实际收益更多取决于 agent 被怎样提示去用这些工具,查询延迟本身只是其中一环。

真正实用的一招是团队共享图产物:建索引时会在源码旁写一个 zstd 压缩的 .codebase-memory/graph.db.zst,队友 clone 仓库后导入这份快照,只对本地 diff 增量重建。它还会自动加一行 merge=ours 的 gitattribute,这个二进制 blob 永远不会引起合并冲突。对一个冷启动建索引很贵的大型 monorepo,这是实打实的工作流收益。

安装

一行安装脚本(在意的话先读脚本,它会写你的 agent 配置):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
# Windows
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1

包管理器也收了:Homebrew、Scoop、Winget、Chocolatey、AUR(yay -S codebase-memory-mcp-bin)、npm、PyPI,以及 go install。装完重启 agent,说一句「Index this project」即可。install 命令会自动探测已装的 agent,为每个写入 MCP 条目、指令文件和 hook。

几个该知道的坑

这部分 README 不会放在开头讲。

它很新。仓库 2026 年 2 月才建,截至 2026-06 就冲过 8,000 星,所以你接手的是一个仍在快速迭代中的工具,版本之间变动很大。锁版本前先读 release notes。

agent 配置安装动了什么很关键。这工具既读你的代码,也写你的 agent 配置文件;在 Claude Code 上它装了一个 PreToolUse hook,拦截 Grep/Glob 注入图上下文。维护者说 hook 设计上不阻塞,但有一条被跟踪的 issue 反映 v0.7.0 安装器接的是旧版的「阻塞」门,本该接的是增强版那一种。装完后如果 agent 的搜索行为变了,先去查这个 hook。

issue 区里还浮出两个真实限制。3D 图可视化在超过约 1 万节点的仓库上会卡死浏览器,所以在大图上把这个 UI 当演示道具看,别当日常工具。Rust 的跨 crate 调用图可能在 crate 边界处断掉,如果你装它就是为了在多 crate 工程里做全工作区追踪,这点要留意。写稿时两条都还开着。

同类对比

项目星数语言一句话
DeusData/codebase-memory-mcp约 8.4kC单文件、158 语言、图 + Hybrid LSP 类型、无 LLM
safishamsi/graphify见专页n/aREADME 直接点了它,最接近的同类,索引落到 graphify-out/ 目录
colbymchenry/codegraph见专页n/a另一种给 agent 用的代码图方案
mem0ai/mem0见专页Python另一条轴:做 agent 记忆,跟代码结构是两回事

如果你要的是通用 agent 记忆这条线,对标的是 mem0;要的是代码图这条线,项目自己点名的就是 graphify。

FAQ

codebase-memory-mcp 免费吗? 免费。MIT 许可、开源,无 API key 也无付费档。索引全程本地跑,代码不离开你的机器。

运行它需要 LLM 或 API key 吗? 不需要。它是一个没有内置模型的结构后端,智能来自你的 MCP 客户端(Claude Code、Codex、Gemini CLI),所以没有额外要配或要付的东西。

它和直接让 agent 去 grep 有什么区别? grep 每次提问都重读文件,每次都付 token。它把代码一次性建成图,把结构问题(调用者、调用链、某个 diff 的影响面)变成便宜的查表。仓库越大、越常问结构问题,收益越明显。

Windows 上能用吗,安装安全吗? 支持 macOS、Linux、Windows,以静态二进制形式分发;Windows 上未签名软件会触发 SmartScreen 警告。每个 release 都发布校验和与构建溯源。注意安装会写你的 agent 配置并加一个 hook,在意就先读安装脚本。

能上生产吗? 它快、功能多,但很新(2026 年初才建)且仍在变动,大图 UI 和 Rust 跨 crate 解析都有 open issue。拿来做索引和查询没问题,锁定版本并盯紧 changelog。

相关仓库