CodeGraph：给 AI 编程助手装上项目记忆

“好的工具不是让 AI 更快地扫描文件，而是让 AI 从一开始就不需要扫描。“

核心观点 / 起源

如果你经常使用 Claude Code、Cursor 或 Codex 这类 AI 编程助手，一定遇到过这个场景：你打开一个中型以上的项目，让 AI 帮忙改某个功能。它先花几十秒读文件，然后才给出建议。改完一个文件，它又要读另一个。每次对话、每个上下文窗口，它都像是第一次看到这个项目——即便你昨天刚让它改过同一个模块。

这不是 AI 不够聪明，而是它的工作方式决定了它记不住。当前 AI 编程助手的典型工作流是：收到问题 → 扫描文件 → 解析结构 → 理解上下文 → 回答。每一次对话，前面几轮都在做热身——用大量 token 来建立对项目的基本认知。在大型项目中，这个代价非常直观：为了让 AI 理解一个函数，你可能需要 5-10 次工具调用来翻阅相关文件。如果有一个办法，能让 AI 助手在一开始就认识你的项目呢？这就是 CodeGraph 正在做的事情。

CodeGraph 是一个预索引的代码知识图谱工具，由 Colby McHenry 开发并开源（MIT 协议）。它的核心思路非常简单：在 AI 编程助手工作之前，先把你的代码库扫描、解析、建立索引和关系图，然后通过标准协议暴露给 AI 助手使用。目前该项目在 GitHub 上获得了 27,500+ Stars，npm 周下载量超过 32K，已成为 AI 编程工具链中不可忽视的存在。

它的工作链路是：代码库 → tree-sitter 解析语法树（WASM 运行，无需安装语言环境）→ SQLite 数据库存储（FTS5 全文索引 + 符号关系图）→ MCP（Model Context Protocol）标准接口 → AI 编程助手。一次索引，多次使用。构建完成后，AI 不再需要逐个文件扫描，一次工具调用就能获取入口点、符号定义和代码片段。

CodeGraph 团队在 7 个真实世界的大型代码库（VS Code、Django、Tokio、Excalidraw、OkHttp、Gin、Alamofire）上做了基准测试，结果相当亮眼：token 消耗减少 57%，工具调用次数减少 71%，费用降低 35%，响应时间加快 46%。这意味着一个实际场景中，10 次文件扫描变成 1 次图查询，AI 可以直奔主题。

支撑点

预索引哲学：把运行时扫描变成构建时索引，是现代 IDE 符号索引思路在 AI 场景的延伸
tree-sitter + WASM：零语言依赖即可解析 20+ 语言，准确率远高于正则匹配
SQLite FTS5：全文搜索支持模糊查询和相关性排序，零配置零依赖
自动文件同步：原生 OS 文件监听（FSEvents / inotify / ReadDirectoryChangesW），代码变了索引自动更新
MCP 协议：标准化接口，Claude Code、Cursor、Codex、OpenCode、Gemini 等 8+ 个 AI 工具即插即用

过程 / 推演

大多数代码分析工具只能做到符号级别——找到函数、类、变量的定义和引用。CodeGraph 更进一步，内置了对 14 种 Web 框架的路由解析能力。它能理解 Django 的 urlpatterns 配置，能解析 Express/Koa 的路由定义，能识别 Spring Boot 的注解路由。这意味着当 AI 需要找到处理 /api/users 请求的代码时，CodeGraph 可以直接返回对应的处理器函数，而不是仅仅说 users 这个符号出现在文件 X 的第 Y 行。

安装和使用同样简单。两条命令即可上手：

# 安装
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# 或通过 npm
npx @colbymchenry/codegraph

# 使用
cd your-project
codegraph init    # 扫描并构建知识图谱
codegraph mcp     # 启动 MCP 服务器供 AI 连接

codegraph init 会自动识别项目中的代码文件（自动忽略 .gitignore 列表），用 tree-sitter 解析语法树，构建符号索引和调用关系图，保存到本地 SQLite 数据库。不需要 API 密钥，数据 100% 本地，不会离开你的机器。

一点补充

客观来说，CodeGraph 解决了一个非常具体的问题，但不是万能的。它擅长解决 AI 对项目的零认知问题、大型代码库的工具调用爆炸问题、以及跨文件理解的效率问题。但它不能替代 AI 模型的推理能力，不支持未经索引的新文件，极大型 monorepo 也需要个性化调优。理解这些边界才能用好它。

结语 / 反思

CodeGraph 的核心理念反映了一个广泛的趋势：AI 工具链正在从即插即用走向基础设施化。早期的 AI 编码助手是黑盒——你把问题扔进去，它给你答案。但随着使用深入，人们发现一个有记忆的 AI 远比每次都从头想的 AI 更实用。预索引、RAG、持久上下文——这些技术本质上都在做同一件事：给 AI 装上长期记忆。

CodeGraph 选择了代码理解这个垂直场景，用务实的技术方案做出了一个真正可用的工具。如果你在大型项目中使用 AI 编程助手，它值得你花 5 分钟装上——你省下的第一个小时，就在第一次对话里。

项目地址：github.com/colbymchenry/codegraph 官网文档：colbymchenry.github.io/codegraph