AI工具

codebase-memory-mcp 使用教程：给 Claude Code、Codex 加代码库记忆

整理 DeusData/codebase-memory-mcp 的一键安装、Windows 安装、UI、自动索引、更新卸载和适合 AI 编程 Agent 的代码库记忆场景。

DeusData/codebase-memory-mcp 是一个代码智能 MCP server。它会把代码库索引成持久知识图谱，让 Claude Code、Codex、Gemini CLI、Aider、OpenCode 等 Agent 更快查询项目结构。

项目地址：

https://github.com/DeusData/codebase-memory-mcp

文档站：

https://deusdata.github.io/codebase-memory-mcp/

一键安装

macOS / Linux：

1

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

如果想同时安装图形界面：

1

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

Windows：

1
2
3
4
5
6
7
8

# 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (Optional but recommended) Inspect the script
notepad install.ps1

# 3. Run it
.\install.ps1

手动安装

macOS / Linux 解压后安装：

1
2

tar xzf codebase-memory-mcp-*.tar.gz
./install.sh

Windows：

1
2

Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
.\install.ps1

打开 UI 

1

codebase-memory-mcp --ui=true --port=9749

自动索引和更新

开启自动索引：

1

codebase-memory-mcp config set auto_index true

更新：

1

codebase-memory-mcp update

卸载：

1

codebase-memory-mcp uninstall

适合怎么用

它适合代码库比较大、Agent 经常反复读文件的场景。比如：

  1. 老项目结构复杂，AI 总是找错入口。
  2. 多语言仓库里需要快速查依赖关系。
  3. 想减少 Agent 把大量文件塞进上下文。
  4. 希望用 MCP 给多个编码工具共享同一份代码记忆。

安装后建议先让 Agent 做一个小任务：解释项目结构、找到某个 API 的调用链、定位某个配置入口。确认它能正确查询后，再用于真实改代码任务。

AI Agent 代码库记忆工具的路线对比

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：最基础，也最应该先做

如果一个项目什么代码库记忆都没有，第一步不应该是上复杂索引，而是先补一份项目规则文件。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Project Guide

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Rules

- Prefer existing helpers in `src/lib`.
- Do not edit database migrations unless explicitly requested.
- Do not delete files without listing paths and waiting for confirmation.
- For UI changes, check mobile and desktop layouts.

这类文件特别适合保存“项目怎么做事”：

  • 当前项目用 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 返回过多、上下文越来越乱这类问题，也要意识到：索引不是越多越好，真正有价值的是“当前任务相关的上下文”。相关排查可以看：Claude Code token 消耗突然变高原因：教程、排障和 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 本身排障可以参考：。

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 那样方便，但在关键任务上更稳。

它尤其适合这种流程：

  1. 人类先选入口文件、相关模块和 diff。
  2. RepoPrompt 生成上下文包。
  3. AI 做设计、审查或修改建议。
  4. 真正写代码前再缩小范围。

如果你的团队经常抱怨“AI 读了一堆无关文件”“回答看起来对但其实拿错上下文”，这种人工打包工具值得考虑。

Sourcegraph：适合企业多仓库和大规模代码理解

Sourcegraph 的定位更偏企业级代码理解平台。它强调对大型代码库和多仓库环境的索引、搜索、权限和代码演进控制，也把“给人和 Agent 提供完整代码上下文”作为核心卖点。

它适合：

  • 多仓库企业团队；
  • 大型 monorepo；
  • 跨服务迁移；
  • 需要权限、审计、SSO、集中搜索；
  • Agent 需要理解不止当前本地仓库；
  • 安全、合规和代码治理要求较高的组织。

个人开发者通常不需要一上来用 Sourcegraph。它的价值在“规模”：当代码分散在几十个仓库里，靠本地 IDE 索引和几个 Markdown 规则文件已经不够，团队需要一个统一的代码理解层。

如果你只是一个本地项目，AGENTS.md + Cursor / Serena / codebase-memory-mcp 往往更轻。

不同项目怎么选

下面按项目规模给一套更实际的选型。

个人小项目

推荐组合：

1
2
3

AGENTS.md 或 CLAUDE.md
+ Git
+ IDE 内置搜索

小项目不要把工具链弄得太重。先写清楚命令、目录和禁区，再让 Agent 做小步修改。

重点不是“记住所有文件”，而是“别用错命令、别误删文件、别改无关目录”。误删防护可以继续看：。

中型业务项目

推荐组合：

1
2
3

AGENTS.md / CLAUDE.md
+ Cursor codebase indexing
+ 必要时加 Serena MCP

中型项目通常已经有多个模块、测试、构建命令和目录约定。规则文件负责稳定约束，IDE 索引负责日常问答，Serena 负责更复杂的语义导航。

大型单仓库

推荐组合：

1
2
3
4

AGENTS.md / CLAUDE.md
+ Serena MCP
+ codebase-memory-mcp
+ 分目录说明文件

大型单仓库最怕 Agent 把整个项目当成一坨文本。应该按模块拆：

  • 根目录写全局规则；
  • 子目录写局部规则；
  • MCP 工具负责查 symbol 和依赖；
  • 重要任务先做只读影响面分析；
  • 修改时只改小范围。

如果还会用 Claude Code subagent，可以把“代码检索”和“专项审查”拆成不同角色：。

多仓库团队

推荐组合：

1
2
3
4
5

每仓库 AGENTS.md / CLAUDE.md
+ 团队通用记忆
+ Sourcegraph 或企业代码搜索平台
+ MCP 工具层
+ 权限和审计规则

多仓库团队最重要的是统一规则和权限。不要让每个 Agent 自己猜：

  • 哪些仓库能读；
  • 哪些仓库能改；
  • 哪些服务之间有依赖；
  • 哪些迁移必须分阶段；
  • 哪些生产配置不能碰。

这种场景里，代码库记忆已经不是个人效率工具，而是工程治理的一部分。

选型时看这 7 个问题

选工具前，先回答这几个问题：

  1. 代码库有多大？几千行、几十万行还是多仓库？
  2. Agent 主要问题是“不知道规则”，还是“找不到代码关系”？
  3. 你只用一个 IDE，还是同时用 Codex、Claude Code、Cursor、Aider 等多个工具？
  4. 是否需要团队共享同一份规则和索引？
  5. 是否有密钥、生产配置、客户数据等敏感文件？
  6. 是否经常做跨文件重构和迁移？
  7. 你能接受维护额外 MCP server 或企业平台吗？

如果主要问题是规则混乱，先写 AGENTS.md / CLAUDE.md。

如果主要问题是 Agent 找不到代码，考虑 Cursor 索引、Serena 或 codebase-memory-mcp。

如果主要问题是多仓库治理，考虑 Sourcegraph 这类平台。

如果主要问题是高风险任务上下文要可审查，考虑 RepoPrompt。

常见错误

错误一：把记忆文件写成项目百科

CLAUDE.md 和 AGENTS.md 不应该塞进所有历史背景。它们应该只写会影响操作的稳定规则。

更长的背景文档可以放在 docs/，然后在规则文件里写“需要时读取哪一份”。

错误二：索引范围太大

不要把这些目录都交给 Agent 当主要上下文：

1
2
3
4
5
6
7
8
9

node_modules/
dist/
build/
public/
.next/
.cache/
coverage/
logs/
tmp/

索引工具要配合 .gitignore、.cursorignore、工具自己的 ignore 文件或 MCP 配置使用。否则上下文会变贵、变慢、变脏。

错误三：把搜索结果当事实

代码检索只能说明“找到了一些相关内容”，不代表结论一定正确。

Agent 仍然需要：

  • 读入口文件；
  • 查调用链；
  • 看测试；
  • 看配置；
  • 跑最小验证；
  • 汇报不确定性。

错误四：忘了权限和隐私

代码库记忆工具可能读取大量源码、配置和文档。接入前要确认：

  • 是否会上传代码；
  • 索引存在哪里；
  • 团队成员是否共享索引；
  • 是否包含 .env、密钥、客户数据；
  • MCP server 是否限制了工作目录；
  • 日志里是否会打印敏感内容。

错误五：工具太多，规则太少

很多团队会同时装 Cursor、Claude Code、Codex、Serena、MCP、代码搜索，但没有一份清楚的项目规则。结果每个工具都能读代码，却都不知道团队希望它怎么做。

先把规则写清楚，再加索引工具。

推荐落地路线

如果你现在还没有代码库记忆体系，可以按这个顺序来：

  1. 给项目加一份简短 AGENTS.md 或 CLAUDE.md。
  2. 写清楚技术栈、命令、目录、禁区和验证方式。
  3. 配好 .gitignore、.cursorignore 或索引排除规则。
  4. 日常 IDE 开发先用 Cursor / 内置索引。
  5. Agent 经常找错代码时，再加 Serena 或 codebase-memory-mcp。
  6. 高风险改动前，用 RepoPrompt 这类工具人工打包上下文。
  7. 多仓库团队再考虑 Sourcegraph 或企业代码搜索平台。

这样做的好处是每一步都有明确收益，不会一开始就把工具链堆复杂。

code-review-graph、Claude.md 与 Codex Skills 怎么组合

很多人说 AI Agent 需要“代码库记忆”。 但这个词太宽。 有的人想让 Agent 记住项目规则。 有的人想让 Agent 找到函数调用链。 有的人想让 Agent 不要每次都重新扫描全仓库。 还有的人想让 Agent 自动执行固定审查流程。 这四个问题听起来相似，实际需要的工具完全不同。 Claude.md、AGENTS.md 更像项目规则文件。 code-review-graph 更像代码关系图和审查辅助工具。 codebase-memory-mcp 更像跨工具共享的代码索引服务。 Codex Skills 更像可复用工作流说明书。 选错以后，结果不是功能少一点，而是维护成本变高。 这篇文章不重复单个工具教程，而是做选型。

选型结论先说清楚

小项目先用 AGENTS.md 或 Claude.md。 中型项目加 Codex Skills，把重复流程固定下来。 代码审查任务优先看 code-review-graph。 多工具共享代码索引时，再考虑 codebase-memory-mcp。 不要一开始就把四种都装上。 更好的顺序是：规则文件先行，流程沉淀第二，结构索引第三，MCP 服务最后。 如果你已经读过 AI Agent 代码库记忆工具对比，这篇可以作为更窄的实操选型表。

四类工具解决四类问题

工具 主要解决的问题 最适合场景 最大风险
Claude.md / AGENTS.md 项目规则和长期约定 小团队、单仓库、固定规范 写太长，污染上下文
Codex Skills 重复任务流程 发布、翻译、部署、SEO、审查 把没跑顺的流程固化
code-review-graph 调用关系和变更影响 PR 审查、架构影响分析 图谱过期或排除目录不准
codebase-memory-mcp 跨工具共享代码索引 多 Agent、多 IDE、大仓库 服务权限和索引维护成本
这张表里的重点是“主要解决的问题”。
它们不是同一种工具的四个品牌。
它们更像四层能力。
规则层告诉 Agent 怎么做。
流程层告诉 Agent 反复做什么。
结构层告诉 Agent 代码之间怎么连。
服务层让不同 Agent 通过统一接口查同一份索引。

先判断你缺的是哪种记忆

选工具前先问四个问题。

  • Agent 是忘了项目规范吗？
  • Agent 是找不到相关代码吗？
  • Agent 是每次都重复同一套步骤吗？
  • Agent 是多个工具之间上下文不同步吗？ 如果只是忘了规范，写 AGENTS.md 就够了。 如果只是重复同一套工作流，写 Skill 更直接。 如果经常漏调用链和影响范围，用代码图谱。 如果 Codex、Claude Code、Cursor 都要查同一份结构化索引，再接 MCP。 不要因为“记忆”这个词就把所有工具混在一起。

Claude.md 和 AGENTS.md：项目规则层

Claude.md、AGENTS.md 的价值在于短。 它们应该告诉 Agent 稳定规则，而不是保存项目百科。 适合写进去的内容包括：

  • 项目启动命令。
  • 测试命令。
  • 代码风格。
  • 禁止修改的目录。
  • 发布前检查。
  • 常见陷阱。
  • 安全边界。
  • 语言和文案要求。 不适合写进去的内容包括：
  • 完整业务背景。
  • 过期讨论记录。
  • 每个模块的详细说明。
  • 长篇设计文档。
  • 一次性任务日志。
  • 没验证过的个人偏好。 一个好的规则文件应该像路标。 它提醒 Agent 不要走错路。 它不应该变成一本厚手册。 如果你想专门优化规则文件，可以继续遵循 Claude.md 不是越长越好的原则。

Codex Skills：工作流记忆层

Skill 不是代码索引。 它记住的是“做事方式”。 例如这个站点的新文章流程：

  • 判断是不是新建文章。
  • 找到下一个编号。
  • 只创建 index.zh-cn.md。
  • 设置 front matter。
  • 控制发布日期。
  • 检查行数。
  • 不生成其他语言。 这些步骤不适合每次都写在提示词里。 它们适合沉淀成 Skill。

Skills 适合的任务

  • 内容发布流程。
  • 多语言翻译流程。
  • 部署流程。
  • SEO 冷却期检查。
  • 本地转写流程。
  • 安全检查清单。
  • 固定格式报告。
  • 代码审查步骤。

Skills 不适合的任务

  • 单次问题排查。
  • 仍在摸索的流程。
  • 需要大量临场判断的任务。
  • 没有稳定验收标准的任务。
  • 只为了让回答更长的提示词集合。 Skill 最好的形态是“少解释，多约束”。 它应该减少 Agent 犯固定错误的概率。 如果你想从零写，可以看 Codex Skills 怎么写自己的工作流。

code-review-graph：变更影响层

code-review-graph 的重点不是让 Agent 记住聊天记录。 它更关注代码结构。 它用图谱思路帮助你回答：

  • 这个函数被谁调用。
  • 这个路由影响哪些模块。
  • 这个 PR 改了哪些调用链。
  • 哪些测试可能需要补。
  • 哪些文件应该一起审查。 这类问题靠普通提示词很难稳定回答。 因为 Agent 如果只读 diff，容易漏掉间接影响。 如果让它全仓库搜索，又容易浪费上下文。 图谱工具的价值就在这里。 它把代码结构提前算好。 Agent 需要时再查。

code-review-graph 适合谁

  • 经常做 PR 审查的人。
  • 仓库模块之间调用复杂的人。
  • 想让 Codex 或 Claude Code 审查变更影响的人。
  • 不想每次都让 Agent 扫全仓库的人。
  • 想把审查流程接入 GitHub Actions 的团队。

code-review-graph 不适合谁

  • 只有几个文件的小脚本。
  • 没有 PR 或 diff 流程。
  • 只想保存聊天记忆。
  • 不愿维护索引生成结果。
  • 无法区分生成文件和源代码目录。 如果你要上手，可以看 code-review-graph 怎么用。 如果要接 CI，可以看 code-review-graph 接入 GitHub Actions。

codebase-memory-mcp：共享索引层

codebase-memory-mcp 更适合多工具环境。 如果你只用一个 Agent，未必需要它。 但如果你同时用 Codex、Claude Code、Cursor、Gemini CLI，问题会出现。 每个工具都有自己的上下文。 每个工具都可能重新扫描代码。 每个工具对项目结构的理解可能不一致。 这时 MCP 形式的代码索引就有价值。 它可以把代码库结构作为一个服务暴露给不同 Agent。 Agent 不需要每次重新构建理解。

codebase-memory-mcp 适合的场景

  • 大仓库。
  • 多语言仓库。
  • 多个 Agent 共享同一项目。
  • 需要本地优先的代码索引。
  • 需要通过 MCP 统一接入。
  • 需要减少重复扫描成本。

使用前要想清楚

它是一个服务。 服务就有运行状态。 服务就有端口、权限、索引目录和升级问题。 如果团队没人维护，这类工具很容易变成“装过但没人敢动”。 所以它适合已经有稳定 Agent 使用习惯的团队。 不适合还在试用阶段的人。 安装教程可以看 codebase-memory-mcp 使用教程。

按仓库规模选择

仓库规模会明显影响选型。 一个脚本仓库和一个大型单体仓库，不应该用同一套记忆方案。

10 个文件以内

这类项目不需要复杂记忆。 建议只保留：

  • README.md。
  • AGENTS.md。
  • 基础测试命令。
  • Git diff 审查。 如果 Agent 还找不到文件，问题通常不是工具少，而是任务描述太宽。

10 到 200 个文件

这类项目开始需要轻量结构说明。 建议增加：

  • 模块目录说明。
  • 常用命令清单。
  • 一个开发或发布 Skill。
  • 必要时加 code-review-graph。 这时规则文件仍然要短。 不要把每个模块都写进 AGENTS.md。

200 到 2000 个文件

这类项目开始出现影响范围问题。 建议增加：

  • 调用关系图谱。
  • 变更影响审查。
  • CI 中的最窄测试策略。
  • 团队共享规则。
  • 忽略生成目录的索引配置。 code-review-graph 在这一层更有价值。 它帮助 Agent 少靠猜。

多语言大仓库

这类项目需要共享索引和服务化能力。 建议增加：

  • codebase-memory-mcp。
  • 统一 MCP 配置。
  • 索引更新策略。
  • 权限白名单。
  • 服务监控。
  • 版本升级记录。 这时工具本身已经是基础设施。 不能只靠个人习惯维护。

按任务类型选择

不同任务对记忆的要求也不同。

修 Bug

修 Bug 最需要复现步骤和相关文件。 优先级是：

  • 错误日志。
  • 复现命令。
  • 最近改动。
  • 相关测试。
  • 调用关系。 如果 Bug 很局部，不必上 MCP。 如果 Bug 跨模块，再用图谱。

写新功能

写新功能最需要边界。 优先级是：

  • 需求范围。
  • 不改动范围。
  • 数据结构。
  • API 契约。
  • 测试入口。 规则文件能防止 Agent 乱改架构。 Skill 可以保存固定实现流程。

代码审查

代码审查最需要变更影响。 优先级是：

  • diff。
  • 调用方。
  • 被调用方。
  • 路由入口。
  • 测试覆盖。
  • 安全边界。 这里 code-review-graph 比长提示词更合适。

文档和发布

文档和发布最需要流程记忆。 优先级是：

  • front matter。
  • 文件命名。
  • 构建规则。
  • 多语言同步。
  • 链接检查。
  • 发布检查。 这类任务更适合 Skills。

数据更新策略

代码库记忆如果不更新，很快就会误导 Agent。 不同工具的更新方式不同。 规则文件靠人工维护。 Skills 随流程变化更新。 code-review-graph 需要在代码变更后重建或增量更新。 codebase-memory-mcp 需要维护索引服务和数据目录。

什么时候必须更新

  • 新增模块。
  • 删除目录。
  • 路由结构变化。
  • 测试命令变化。
  • 构建工具变化。
  • 代码生成目录变化。
  • 团队权限规则变化。
  • CI 流程变化。
  • Agent 工具升级。
  • MCP 服务升级。

更新后的验收

  • Agent 能说明入口文件。
  • Agent 能找到相关测试。
  • Agent 不会扫描生成目录。
  • Agent 能解释一次真实 diff。
  • Agent 能遵守禁止修改范围。
  • Agent 能正确调用 Skill。
  • MCP 查询返回的是最新文件。
  • 图谱结果和实际代码一致。

失败案例和修复

规则文件太长

表现是 Agent 每次都读得慢，还会引用无关规则。 修复方法是删。 保留稳定约定。 把流程移到 Skill。 把背景移到文档。

Skill 写得太泛

表现是每种任务都套同一个流程。 修复方法是拆。 一个 Skill 只服务一类工作。 例如发布、翻译、部署、审查分别写。

图谱没有排除生成目录

表现是 Agent 关注构建产物，而不是源代码。 修复方法是更新 ignore 配置。 把 dist/、public/、node_modules/、缓存目录排除。

MCP 权限过大

表现是 Agent 能访问太多不相关资源。 修复方法是分级。 只读工具先行。 写入工具单独审批。 生产工具默认关闭。

四种工具可以怎么组合

个人小项目建议：AGENTS.md、少量项目文档、Git diff、最窄测试命令。 中型 Web 项目建议：AGENTS.md、一个发布或测试 Skill、code-review-graph、PR 审查模板。 多 Agent 团队项目建议：AGENTS.md、团队级 Skills、code-review-graph、codebase-memory-mcp、CI 审查、权限边界文档。 内容站和自动化工作流建议：发布 Skill、翻译 Skill、SEO 冷却期规则、部署 Skill、少量站点目录说明。 这类组合的关键不是工具多。 关键是每一层解决的问题不重叠。

选型决策树

先问：Agent 是否经常违反项目规则？ 是，就写 AGENTS.md 或 Claude.md。 Agent 是否经常重复同一套步骤？ 是，就写 Skill。 Agent 是否经常漏掉调用链或影响范围？ 是，就用 code-review-graph。 是否有多个 Agent 需要共享代码索引？ 是，再考虑 codebase-memory-mcp。 否，先不要加工具。 这个顺序能避免把简单问题复杂化。

和已有文章怎么串起来

这篇文章适合作为选型入口。 单工具安装继续交给已有文章。 code-review-graph 的具体命令看 7/99。 GitHub Actions 接入看 7/137。 codebase-memory-mcp 安装看 6/113。 规则文件思想看 4/118。 通用记忆路线看 7/42。 这样读者不会在一篇文章里被所有命令淹没。 他们先选方向，再进入具体教程。

最终选择建议

如果你只想让 Agent 不犯固定错误，选 AGENTS.md 或 Claude.md。 如果你想让 Agent 按固定流程办事，选 Codex Skills。 如果你想让 Agent 做变更影响分析，选 code-review-graph。 如果你想让多个 Agent 共享代码结构，选 codebase-memory-mcp。 真正成熟的代码库记忆，不是把所有东西都记住。 而是把规则、流程、结构和服务放到合适的位置。