乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > AI Agent 代码记忆方案对比:CodeGraph、Serena、RepoMap 与 AGENTS.md

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

当前时间： 2026-08-11 13:52:39 分类：办公文件 评论(0)
AI Agent 代码记忆方案对比:CodeGraph、Serena、RepoMap 与 AGENTS.md


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. 文件监听自动同步，保持索引实时更新

核心工具：

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

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

  1. 平均节省 16% 成本
  2. 减少 47% token 消耗
  3. 提速 22%
  4. 减少 58% 工具调用

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

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

优势：

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

劣势：

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

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. 支持符号级别的精确操作（重命名、查找引用等）

核心能力：

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

优势：

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

劣势：

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

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

类型：代码库地图生成工具，为 Agent 提供精简的代码概览

代表实现：Aider 的 repomap、Cursor 的 codebase indexing

工作原理：

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

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

优势：

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

劣势：

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

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

类型：纯文本的项目说明文件

支持 Agent：所有主流 Agent（Claude Code、Cursor、Hermes Agent、GitHub Copilot）

工作原理：

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

优势：

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

劣势：

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

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

类型：将代码分块后做向量化存储，通过语义相似度检索

代表工具：Cursor 的 codebase indexing、GitHub Copilot Chat、Continue

工作原理：

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

优势：

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

劣势：

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

三、方案对比总表

维度CodeGraphSerenaRepoMapAGENTS.mdRAG+Embedding
类型知识图谱 + MCP语义分析 + MCP代码地图文档向量检索
安装复杂度低（一键安装）中（需 LSP）低最低中
运行方式MCP ServerMCP 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 三层组合

  1. CodeGraph：精确的结构查询（调用链、影响分析）
  2. RAG：模糊的语义查询（"用户认证是怎么实现的"）
  3. 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 工具：

  1. codegraph_explore：探索代码结构
  2. codegraph_search：搜索符号
  3. codegraph_callers：查找调用者
  4. codegraph_callees：查找被调用者
  5. codegraph_impact：影响分析

六、总结

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

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

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