AI Agent 写代码时最常见的问题，不是模型完全不会写，而是它不知道这个代码库真正长什么样。
它可能不知道入口文件在哪里，不知道某个 helper 已经存在，不知道测试命令怎么跑，也不知道团队约定哪些目录不能碰。于是每次开新会话都要重新解释一遍项目背景，或者让 Agent 反复 grep、反复读文件、反复把无关内容塞进上下文。
这就是“代码库记忆工具”要解决的问题。
不过这类工具并不是一种东西。CLAUDE.md、AGENTS.md 是规则文件；Cursor 做的是 IDE 内索引；Serena 更像给 Agent 加一组语义代码工具；codebase-memory-mcp 走的是持久知识图谱；RepoPrompt 偏人工上下文打包；Sourcegraph 则更适合企业级多仓库代码理解。
这篇不讲玄学，直接从使用场景对比：AI Agent 代码库记忆工具怎么选，哪些适合个人项目，哪些适合大仓库，哪些适合团队。
先给结论
如果你只想快速选型，可以按下面这张表看：
| 工具/路线 | 最适合 | 主要价值 | 不适合 |
|---|---|---|---|
CLAUDE.md / AGENTS.md |
几乎所有项目 | 保存项目规则、命令、禁区、协作约束 | 自动理解复杂调用关系 |
| Cursor codebase indexing | Cursor 用户、IDE 内开发 | 让聊天和编辑能引用当前项目索引 | 跨工具共享、复杂 Agent 编排 |
| Serena MCP | 大代码库、语义导航、重构 | 符号级检索、引用查找、语义编辑 | 只想写简单提示词的小项目 |
codebase-memory-mcp |
多工具共享代码索引 | 通过 MCP 暴露持久代码知识图谱 | 不想维护额外服务的用户 |
| RepoPrompt / RepoPrompt CE | 需要人工精确控制上下文 | 选择文件、CodeMap、diff，组装可审查上下文 | 想完全自动索引的团队 |
| Sourcegraph / Cody | 企业多仓库、大规模代码理解 | 集中索引、搜索、权限、跨仓库上下文 | 个人小项目、轻量本地工作流 |
我的建议是：
- 小项目：先写
AGENTS.md或CLAUDE.md。 - 中型项目：规则文件 + IDE 索引。
- 大型单仓库：规则文件 + Serena 或
codebase-memory-mcp。 - 多仓库团队：规则文件 + MCP 索引工具 + Sourcegraph 这类平台。
- 高风险改动：再加 RepoPrompt 这类人工上下文打包工具，先让人审上下文，再让 Agent 动手。
不要一开始就堆满工具。代码库记忆的目标不是“让 Agent 知道一切”，而是让它在当前任务里少猜、少读错、少浪费上下文。
先区分三种“记忆”
很多对比文章会把所有工具混在一起，其实它们解决的问题不同。
1. 规则记忆
代表：CLAUDE.md、AGENTS.md、GEMINI.md、项目 README 中的 AI section。
它们记录的是：
- 项目技术栈；
- 常用命令；
- 测试方式；
- 目录说明；
- 禁止修改的文件；
- 代码风格；
- 提交和验证规则。
这种记忆最便宜，也最稳定。缺点是它不会自动理解代码关系。
2. 检索记忆
代表：Cursor codebase indexing、Sourcegraph、代码搜索、向量索引、知识图谱。
它们解决的是：
- 这个函数在哪里定义；
- 谁调用了这个接口；
- 哪些文件可能相关；
- 某个配置在哪些地方出现；
- 跨仓库依赖在哪里。
这种记忆适合中大型代码库。缺点是需要索引、刷新、权限和忽略规则。
3. 操作记忆
代表：Serena MCP、带语义编辑能力的 Agent 工具、代码智能 MCP server。
它们不只是“找到代码”，还会给 Agent 一组更接近 IDE 的工具，例如：
- 查找 symbol；
- 查引用；
- 看文件 outline；
- 替换函数体；
- 重命名 symbol；
- 做更小粒度的编辑。
这种记忆最适合复杂重构和大仓库导航。缺点是安装、配置和工具选择更复杂。
CLAUDE.md / AGENTS.md：最基础，也最应该先做
如果一个项目什么代码库记忆都没有，第一步不应该是上复杂索引，而是先补一份项目规则文件。
例如：
|
|
这类文件特别适合保存“项目怎么做事”：
- 当前项目用
pnpm还是npm； - 测试命令是
pytest还是vitest； - 哪些目录是生成物；
- 哪些文件不能改；
- 改 API 后要跑什么检查；
- 团队希望 AI 最后怎么汇报。
它的优势是简单、可提交到 Git、团队共享、跨工具可读。Claude Code、Codex、Gemini CLI、Cursor 等工具即使实现细节不同，也都能从这种项目说明里受益。
缺点也很明显：它是手写规则，不会自动告诉 Agent “这个函数在哪里被调用”。所以它更像地基，不是完整代码索引。
站内这篇已经详细讲过多项目记忆怎么分层：/2026/07/08/claude-code-multi-project-memory-team-workflow/。
Cursor codebase indexing：适合 IDE 内闭环
Cursor 的 codebase indexing 更适合已经在 Cursor 里日常开发的人。它会为当前代码库建立索引，让聊天、编辑和 @Codebase 这类上下文引用更容易命中相关文件。
它适合：
- 前端、全栈、移动端等日常 IDE 开发；
- 希望在编辑器里直接问“这个功能在哪里实现”；
- 需要让 AI 根据当前项目补代码；
- 不想额外维护 MCP server；
- 团队成员主要都用 Cursor。
它的优势是入口自然。用户不需要单独打开一个工具，也不需要手动复制大量文件。索引和编辑都在同一个 IDE 里。
但它也有边界：
- 索引主要服务 Cursor 内部工作流；
- 跨工具共享能力有限；
- 大仓库要注意索引范围和忽略规则；
- 不能只依赖它来表达项目规则，仍然需要
AGENTS.md或类似文件； - 对生产配置、密钥、生成物目录要做好排除。
如果你已经遇到 Claude Code token 暴涨、MCP 返回过多、上下文越来越乱这类问题，也要意识到：索引不是越多越好，真正有价值的是“当前任务相关的上下文”。相关排查可以看：/2026/07/08/claude-code-token-usage-spike-troubleshooting-faq/。
Serena MCP：适合大代码库的语义导航和重构
Serena 的定位更接近“给 AI Agent 用的 IDE 能力”。官方介绍里强调它提供语义代码检索、编辑、重构和调试工具，并通过 MCP 接入不同客户端。
它适合：
- 大型 Python、Java、TypeScript、Go 等代码库；
- Agent 经常找错函数、读错文件；
- 需要查 symbol、引用、声明和实现；
- 需要更安全地做跨文件重构；
- 想让 Claude Code、Codex、OpenCode、Gemini CLI 等 MCP 客户端共享同一套代码工具。
Serena 的优势在于“符号级”操作。普通 Agent 经常靠全文搜索和行号编辑，复杂项目里容易误伤。语义工具能让它更像 IDE 一样工作：找函数、看引用、替换函数体，而不是把整个文件读进上下文后猜。
但 Serena 也不是所有人都需要。
如果你只是写小脚本、改单页应用、做一两个文件的 bug 修复，内置搜索和普通编辑已经够用。Serena 更适合“代码结构复杂，Agent 经常迷路”的项目。
安装 MCP 工具以后，也要注意工具列表、返回结果和权限边界。MCP 本身排障可以参考：/2026/07/08/mcp-tool-call-failure-troubleshooting-faq/。
codebase-memory-mcp：适合多工具共享持久代码记忆
DeusData/codebase-memory-mcp 是另一条路线。它把代码库索引成持久知识图谱，然后通过 MCP 提供给支持 MCP 的 Agent 使用。
它适合：
- 同时使用 Claude Code、Codex、Cursor、Aider、OpenCode 等多个工具；
- 希望多个 Agent 共享同一个代码索引；
- 项目较大，Agent 经常重复读取同一批文件；
- 想减少上下文里塞大量源码；
- 想要本地化、可重复的代码查询能力。
它的优势是“持久”和“跨工具”。不像某个 IDE 内置索引只服务一个客户端，MCP server 可以被不同工具接入。对重度 AI 编程用户来说，这类工具更像本地代码情报服务。
缺点是你要多维护一个组件：
- 安装和更新；
- 索引刷新；
- MCP 配置；
- 权限范围；
- 忽略规则；
- 和不同客户端的兼容性。
如果你只是偶尔让 AI 改两行代码，没必要上它。如果你每天在多个 Agent 之间切换，它会更有价值。
站内已经有单独教程：/2026/06/22/codebase-memory-mcp-code-intelligence-guide/。
RepoPrompt：适合人工精确控制上下文
RepoPrompt 和 RepoPrompt CE 的思路不是“让系统自动读完整个仓库”，而是帮助用户组装一份可审查的上下文。
它适合：
- 想明确控制模型看到哪些文件；
- 做复杂需求前，需要人工选择关键文件；
- 担心自动索引带入无关内容；
- 想把文件、CodeMap、目录结构、Git diff 一起交给 AI；
- 做高风险重构、架构评审、代码审查。
这类工具的优势是可控。你可以先看上下文包，再交给模型。它不像全自动 Agent 那样方便，但在关键任务上更稳。
它尤其适合这种流程：
- 人类先选入口文件、相关模块和 diff。
- RepoPrompt 生成上下文包。
- AI 做设计、审查或修改建议。
- 真正写代码前再缩小范围。
如果你的团队经常抱怨“AI 读了一堆无关文件”“回答看起来对但其实拿错上下文”，这种人工打包工具值得考虑。
Sourcegraph：适合企业多仓库和大规模代码理解
Sourcegraph 的定位更偏企业级代码理解平台。它强调对大型代码库和多仓库环境的索引、搜索、权限和代码演进控制，也把“给人和 Agent 提供完整代码上下文”作为核心卖点。
它适合：
- 多仓库企业团队；
- 大型 monorepo；
- 跨服务迁移；
- 需要权限、审计、SSO、集中搜索；
- Agent 需要理解不止当前本地仓库；
- 安全、合规和代码治理要求较高的组织。
个人开发者通常不需要一上来用 Sourcegraph。它的价值在“规模”：当代码分散在几十个仓库里，靠本地 IDE 索引和几个 Markdown 规则文件已经不够，团队需要一个统一的代码理解层。
如果你只是一个本地项目，AGENTS.md + Cursor / Serena / codebase-memory-mcp 往往更轻。
不同项目怎么选
下面按项目规模给一套更实际的选型。
个人小项目
推荐组合：
|
|
小项目不要把工具链弄得太重。先写清楚命令、目录和禁区，再让 Agent 做小步修改。
重点不是“记住所有文件”，而是“别用错命令、别误删文件、别改无关目录”。误删防护可以继续看：/2026/07/10/ai-coding-avoid-accidental-file-deletion/。
中型业务项目
推荐组合：
|
|
中型项目通常已经有多个模块、测试、构建命令和目录约定。规则文件负责稳定约束，IDE 索引负责日常问答，Serena 负责更复杂的语义导航。
大型单仓库
推荐组合：
|
|
大型单仓库最怕 Agent 把整个项目当成一坨文本。应该按模块拆：
- 根目录写全局规则；
- 子目录写局部规则；
- MCP 工具负责查 symbol 和依赖；
- 重要任务先做只读影响面分析；
- 修改时只改小范围。
如果还会用 Claude Code subagent，可以把“代码检索”和“专项审查”拆成不同角色：/2026/07/10/claude-code-subagent-project-fit-guide/。
多仓库团队
推荐组合：
|
|
多仓库团队最重要的是统一规则和权限。不要让每个 Agent 自己猜：
- 哪些仓库能读；
- 哪些仓库能改；
- 哪些服务之间有依赖；
- 哪些迁移必须分阶段；
- 哪些生产配置不能碰。
这种场景里，代码库记忆已经不是个人效率工具，而是工程治理的一部分。
选型时看这 7 个问题
选工具前，先回答这几个问题：
- 代码库有多大？几千行、几十万行还是多仓库？
- Agent 主要问题是“不知道规则”，还是“找不到代码关系”？
- 你只用一个 IDE，还是同时用 Codex、Claude Code、Cursor、Aider 等多个工具？
- 是否需要团队共享同一份规则和索引？
- 是否有密钥、生产配置、客户数据等敏感文件？
- 是否经常做跨文件重构和迁移？
- 你能接受维护额外 MCP server 或企业平台吗？
如果主要问题是规则混乱，先写 AGENTS.md / CLAUDE.md。
如果主要问题是 Agent 找不到代码，考虑 Cursor 索引、Serena 或 codebase-memory-mcp。
如果主要问题是多仓库治理，考虑 Sourcegraph 这类平台。
如果主要问题是高风险任务上下文要可审查，考虑 RepoPrompt。
常见错误
错误一：把记忆文件写成项目百科
CLAUDE.md 和 AGENTS.md 不应该塞进所有历史背景。它们应该只写会影响操作的稳定规则。
更长的背景文档可以放在 docs/，然后在规则文件里写“需要时读取哪一份”。
错误二：索引范围太大
不要把这些目录都交给 Agent 当主要上下文：
|
|
索引工具要配合 .gitignore、.cursorignore、工具自己的 ignore 文件或 MCP 配置使用。否则上下文会变贵、变慢、变脏。
错误三：把搜索结果当事实
代码检索只能说明“找到了一些相关内容”，不代表结论一定正确。
Agent 仍然需要：
- 读入口文件；
- 查调用链；
- 看测试；
- 看配置；
- 跑最小验证；
- 汇报不确定性。
错误四：忘了权限和隐私
代码库记忆工具可能读取大量源码、配置和文档。接入前要确认：
- 是否会上传代码；
- 索引存在哪里；
- 团队成员是否共享索引；
- 是否包含
.env、密钥、客户数据； - MCP server 是否限制了工作目录；
- 日志里是否会打印敏感内容。
错误五：工具太多，规则太少
很多团队会同时装 Cursor、Claude Code、Codex、Serena、MCP、代码搜索，但没有一份清楚的项目规则。结果每个工具都能读代码，却都不知道团队希望它怎么做。
先把规则写清楚，再加索引工具。
推荐落地路线
如果你现在还没有代码库记忆体系，可以按这个顺序来：
- 给项目加一份简短
AGENTS.md或CLAUDE.md。 - 写清楚技术栈、命令、目录、禁区和验证方式。
- 配好
.gitignore、.cursorignore或索引排除规则。 - 日常 IDE 开发先用 Cursor / 内置索引。
- Agent 经常找错代码时，再加 Serena 或
codebase-memory-mcp。 - 高风险改动前，用 RepoPrompt 这类工具人工打包上下文。
- 多仓库团队再考虑 Sourcegraph 或企业代码搜索平台。
这样做的好处是每一步都有明确收益，不会一开始就把工具链堆复杂。
总结
AI Agent 代码库记忆工具没有唯一答案。它们解决的是不同层次的问题：
CLAUDE.md/AGENTS.md解决项目规则。- Cursor indexing 解决 IDE 内上下文。
- Serena MCP 解决语义导航和重构工具。
codebase-memory-mcp解决跨工具持久代码记忆。- RepoPrompt 解决人工可审查上下文打包。
- Sourcegraph 解决企业级多仓库代码理解。
真正稳的组合，通常不是选一个“最强工具”，而是先用规则文件打底，再按代码库规模增加索引、语义工具和团队治理能力。
对个人开发者来说，AGENTS.md + Git + IDE 索引已经能解决很多问题。对重度 AI 编程用户来说，Serena 和 codebase-memory-mcp 更值得尝试。对企业团队来说，代码库记忆最终会变成权限、搜索、审计和 Agent 协作的一部分。