AI Agent 代码记忆方案对比：CodeGraph、Serena、RepoMap 与 AGENTS.md

发布于 2026-06-04 20:09

AI Agent 代码记忆方案对比：CodeGraph、Serena、RepoMap 与 AGENTS.md

一、为什么需要专门的代码记忆方案

传统 AI Agent 做代码开发时，靠的是"临时探索"——每次需要理解代码时，用 grep、glob、Read 工具扫描文件。这种方式有三个问题：

  1. 费 Token：每次探索都消耗大量 token，在大型项目中尤其明显
  2. 慢：文件 I/O 多，响应延迟高
  3. 不精确：grep 只能做文本匹配，不理解语义关系（调用链、继承、接口实现）

专门的代码记忆方案通过预构建索引解决这些问题，让 Agent 能快速、精确地理解代码结构。

二、主流方案对比

1. CodeGraph（MCP 模式）

项目地址：github.com/colbymchenry/codegraph
类型：本地优先的代码知识图谱，通过 MCP Server 提供服务
支持 Agent：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro

工作原理：

  1. 用 tree-sitter 解析源代码生成 AST
  2. 提取符号（函数、类、方法）和关系（调用、导入、继承、实现）
  3. 存入本地 SQLite 数据库，支持 FTS5 全文搜索
  4. 通过 MCP Server 暴露查询工具给 Agent
  5. 文件监听自动同步，保持索引实时更新

核心工具：

  • codegraph_explore：一次调用返回入口点、相关符号和代码片段
  • codegraph_search：按名称搜索符号
  • codegraph_callers：查找谁调用了某个函数
  • codegraph_callees：查找某个函数调用了谁
  • codegraph_impact：分析修改某个符号的影响范围
  • codegraph_node：获取单个符号的完整源码

Benchmark 数据（7 个真实项目，Claude Opus 4.8）：

  • 平均节省 16% 成本
  • 减少 47% token 消耗
  • 提速 22%
  • 减少 58% 工具调用

支持语言：20+ 种，包括 TypeScript、Python、Go、Rust、Java、C#、Swift、Kotlin 等

框架感知：支持 Django、Flask、FastAPI、Express、NestJS、Gin、Spring、Rails 等 14 种 Web 框架的路由到 Handler 映射

优势：

  • 100% 本地运行，数据不上云
  • 自动同步，索引实时更新
  • 支持跨语言调用链（Swift ↔ ObjC、React Native Bridge）
  • 零配置，安装即用
  • 支持 Hermes Agent

劣势：

  • 需要安装 CLI 和配置 MCP Server
  • 首次索引大型项目需要时间
  • 对非标准代码结构（如大量宏、代码生成）支持有限

2. Serena（MCP 模式）

项目地址：github.com/serena-ai/serena
类型：开源的语义代码分析 MCP Server
支持 Agent：任何支持 MCP 的 Agent（Claude Code、Cursor、Hermes Agent 等）

工作原理：

  1. 基于 tree-sitter 和 LSP（Language Server Protocol）做语义分析
  2. 构建符号级别的代码图谱
  3. 通过 MCP 工具暴露查询能力
  4. 支持符号级别的精确操作（重命名、查找引用等）

核心能力：

  • 符号查找和导航
  • 引用查找（谁调用了这个函数）
  • 类型推断和跳转
  • 代码补全上下文构建
  • 多语言 LSP 集成

优势：

  • 开源免费
  • 基于 LSP，语义理解更精确
  • 支持符号级别的操作（不只是查询）
  • 活跃开发中

劣势：

  • 依赖 LSP Server，需要为每种语言安装对应的 LSP
  • 配置相对复杂
  • 对大型项目的索引性能不如 CodeGraph
  • 不支持框架级别的路由映射

3. RepoMap（上下文压缩模式）

类型：代码库地图生成工具，为 Agent 提供精简的代码概览
代表实现：Aider 的 repomap、Cursor 的 codebase indexing

工作原理：

  1. 扫描项目文件结构
  2. 提取关键符号（类、函数、接口）的签名
  3. 生成精简的"代码地图"文本
  4. 作为上下文注入 Agent 的 prompt

核心思想：不是构建完整的知识图谱，而是生成一份"目录 + 签名"的精简索引，让 Agent 快速知道"有什么"和"在哪里"。

优势：

  • 实现简单，不需要额外服务
  • 不依赖 MCP，任何 Agent 都能用
  • 生成的文本可以直接放入 AGENTS.md 或 CLAUDE.md
  • 对小型项目足够用

劣势：

  • 信息密度低，缺少调用关系
  • 不支持动态查询
  • 大型项目需要手动维护
  • 无法回答"这个函数被谁调用"这类问题

4. AGENTS.md / CLAUDE.md（文档模式）

类型：纯文本的项目说明文件
支持 Agent：所有主流 Agent（Claude Code、Cursor、Hermes Agent、GitHub Copilot）

工作原理：

  1. 在项目根目录创建 AGENTS.md 或 CLAUDE.md
  2. 手动编写项目结构、关键约定、调用链路等信息
  3. Agent 启动时自动读取，作为系统提示的一部分

优势：

  • 零依赖，任何 Agent 都支持
  • 完全可控，精确描述关键信息
  • 可以包含业务逻辑、团队规范等非代码信息
  • 版本控制友好

劣势：

  • 手动编写和维护
  • 无法自动更新
  • 信息量受限于 token 预算
  • 不包含动态查询能力

5. RAG + Embedding（向量检索模式）

类型：将代码分块后做向量化存储，通过语义相似度检索
代表工具：Cursor 的 codebase indexing、GitHub Copilot Chat、Continue

工作原理：

  1. 将代码文件分块（通常按函数或类）
  2. 用 Embedding 模型生成向量
  3. 存入向量数据库
  4. 查询时用语义相似度找相关代码片段

优势：

  • 支持自然语言查询（"用户认证是怎么实现的"）
  • 能发现隐式关联（语义相似但无直接调用关系的代码）
  • 对模糊查询效果好

劣势：

  • 无法精确回答调用链问题
  • 向量检索结果可能不完整
  • 需要 Embedding API（可能付费）
  • 对大型项目的分块策略敏感

三、方案对比总表

维度 CodeGraph Serena RepoMap AGENTS.md RAG+Embedding
类型 知识图谱 + MCP 语义分析 + MCP 代码地图 文档 向量检索
安装复杂度 低（一键安装） 中（需 LSP） 低 最低 中
运行方式 MCP Server MCP Server 静态文件 静态文件 API/本地
调用链查询 ✓ 精确 ✓ 精确 ✗ 手动写 ✗ 不精确
影响分析 ✓ ✓ ✗ ✗ ✗
自然语言查询 ✗ ✗ ✗ ✗ ✓
自动同步 ✓ 文件监听 ✗ 需手动 ✗ 需手动 ✗ 需手动 ✗ 需手动
跨语言支持 ✓ 20+ 语言 ✓ 依赖 LSP ✓ ✓ ✓
框架感知 ✓ 14 种框架 ✗ ✗ 手动写 ✗
离线可用 ✓ 100% 本地 ✓ 100% 本地 ✓ ✓ ✗ 需要 API
Token 效率 高（预索引） 高（预索引） 中 高（精简） 中（需检索）
维护成本 低（自动） 中 高（手动） 高（手动） 中
适合项目规模 中大型 中大型 小型 所有 中大型

四、选型建议

小型项目（< 50 文件）

推荐：AGENTS.md

项目小，直接写文档就够了。维护成本低，任何 Agent 都能用。

## 核心模块
- controller/blog.go：博客控制器
- model/blog.go：博客数据模型
- service/blog.go：博客业务逻辑

## 调用链
创建文章：controller.Create → service.Create → model.Insert

中型项目（50-500 文件）

推荐：CodeGraph + AGENTS.md 组合

CodeGraph 处理结构查询，AGENTS.md 补充业务知识。

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

AGENTS.md 中记录 CodeGraph 的使用方式：

## 代码查询
项目已配置 CodeGraph MCP，可以直接查询：
- 调用链：codegraph_callers / codegraph_callees
- 影响分析：codegraph_impact
- 代码探索：codegraph_explore

大型项目（> 500 文件）

推荐：CodeGraph + RAG + AGENTS.md 三层组合

  • CodeGraph：精确的结构查询（调用链、影响分析）
  • RAG：模糊的语义查询（"用户认证是怎么实现的"）
  • AGENTS.md：业务知识和团队规范

团队协作场景

推荐：AGENTS.md + Skill 文档

多人协作时，文档比工具更重要。确保：

  1. AGENTS.md 在项目根目录，版本控制
  2. docs/skills/ 下有详细的开发规范
  3. 踩坑经验及时记录到 Skill 的 references 中

五、CodeGraph 在 Hermes Agent 中的配置

CodeGraph 官方支持 Hermes Agent，配置步骤：

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

# 2. 配置 MCP Server（自动检测 Hermes Agent）
codegraph install

# 3. 初始化项目
cd /path/to/your-project
codegraph init -i

# 4. 重启 Hermes Agent 使 MCP 生效

配置完成后，Hermes Agent 会自动获得以下 MCP 工具：

  • codegraph_explore：探索代码结构
  • codegraph_search：搜索符号
  • codegraph_callers：查找调用者
  • codegraph_callees：查找被调用者
  • codegraph_impact：影响分析

六、总结

没有银弹。不同方案解决不同层面的问题：

  • CodeGraph / Serena：解决"代码结构是什么"的问题，精确、高效
  • RAG + Embedding：解决"相关代码在哪里"的问题，灵活、模糊
  • AGENTS.md / Skill：解决"业务逻辑和规范是什么"的问题，可控、稳定

最佳实践是组合使用：用 CodeGraph 处理结构查询，用 AGENTS.md 记录业务知识，用 Skill 沉淀团队规范。三层配合，才能让 AI Agent 真正"懂"你的项目。

← 返回博客列表
文章信息

标题: AI Agent 代码记忆方案对比：CodeGraph、Serena、RepoMap 与 AGENTS.md

发布时间: 2026-06-04 20:09