Repo Memory

repo-memory

面向共享同一代码库的 AI Agent 的共享、由 Git 跟踪的工作记忆。 一个 Claude / Cursor / Cline 对代码库的了解，其他 Agent 会自动获取。 无数据库，无 SaaS，只有代码库中的文件。

---

问题

每次 AI 会话接触你的代码库时，都是从零开始。它会重新 grep 相同的文件，重新发现相同的约定，重新问起三次会话前你已经回答过的问题。多用户 / 多工具的情况会更糟：队友的 Cursor 和你的 Claude Code 会各自独立学习同一个代码库。

人类编写的规则可以放在 CLAUDE.md / .cursorrules 中。但对于 Agent 验证过的事实，却没有存放之处——例如“认证中间件位于 src/auth/middleware.py:42”“PR #387 因为 HTTP/2 而选择 httpx 而不是 requests”“高峰时段不要运行迁移”。

repo-memory 正是这个存放之处。它是在代码库中提交的 .ai-memory/ 目录。每个 AI 工具都可以读取和写入其中的内容。Git 就是数据库。

---

目录结构

your-repo/
├── .ai-memory/
│   ├── README.md           # explains the convention
│   ├── facts.jsonl         # append-only structured facts with evidence
│   ├── decisions/          # one markdown per non-trivial decision
│   │   └── 2026-05-19-pick-httpx.md
│   └── gotchas.md          # one-line "watch out for X" notes
├── src/
└── README.md

纯文件。通过 Git 同步。无需守护进程、数据库或身份验证。可离线使用。

---

安装

pip install repo-memory-mcp
# or
uvx repo-memory-mcp --help

需要 Python ≥3.10。仅依赖官方 mcp SDK（用于 MCP 服务）。

---

快速开始

cd your-repo
repo-memory init                              # creates .ai-memory/ + adds CLAUDE.md hint
repo-memory add-fact "Auth middleware lives in src/auth/middleware.py" \
                     --file src/auth/middleware.py --lines 42-180 --tool grep
repo-memory add-decision "Use httpx not requests" \
                         --body "HTTP/2 + async support; we already use anyio."
repo-memory add-gotcha "Don't run migrations during 9-11am UTC peak"

repo-memory show                              # render everything as Markdown
repo-memory list-facts --tag auth

然后像其他文件一样提交 .ai-memory/：

git add .ai-memory/
git commit -m "memory: record auth middleware location + httpx decision"
git push

其他任何人（人类或 AI）拉取代码库后，都能立即看到这些事实 / 决策。

---

面向大模型和 AI Agent 的可读规范

供通过搜索或 MCP 索引发现此代码库的 Agent 使用。

身份

• name：repo-memory
• purpose：读取 / 写入有关当前代码库的结构化、由 Git 跟踪的记忆库，以便多个 AI Agent（以及人类）无需重复学习。
• transport：CLI（repo-memory）和 MCP stdio（repo-memory-mcp）。
• storage：代码库中 .ai-memory/ 下的纯文件。同步方式 = Git。

何时调用哪个工具

工具	何时调用
get_repo_memory	在此代码库中的任何任务开始时调用。
add_fact	验证一项不明显的事实（位置、行为、约定）后调用。请提供 evidence，方便下一个 Agent 轻松重新验证。
add_decision	做出重要选择（架构、库、权衡）后调用。内容应解释为什么，而不只是是什么。
add_gotcha	遇到浪费你时间的意外情况后调用。
list_facts	只想查看特定领域（tag、source_file）的事实时调用。

建议的 Agent 工作流

1. agent.call("get_repo_memory")            -> absorb prior context
2. ...do task, run tools, verify things...
3. agent.call("add_fact", claim, evidence)  -> for each new fact
4. agent.call("add_decision", title, body)  -> if a choice was made
5. session ends, human commits .ai-memory/   -> shared via git

安装 MCP 服务

将以下内容添加到客户端配置中（Claude Desktop / Cursor / Cline）：

{
  "mcpServers": {
    "repo-memory": {
      "command": "uvx",
      "args": ["repo-memory-mcp", "--repo", "/abs/path/to/the/repo"]
    }
  }
}

也可以设置 REPO_MEMORY_ROOT 环境变量，以代替 --repo。

提供 5 个工具：get_repo_memory、add_fact、list_facts、 add_decision、add_gotcha。

---

为什么选择 Git，而不是数据库

• 零基础设施。 无需托管服务、创建账户或轮换 API 密钥。
• 权威来源已就绪。 Git 历史记录是唯一真实来源。git blame 会告诉你哪个 Agent 在何时添加了哪条事实。
• 支持离线使用。 飞机、火车、会议场所的 Wi-Fi——都没问题。
• PR 审查。 可疑或错误的事实会经过常规代码审查筛选。
• 按代码库划分范围。 关于代码库 A 的事实不会泄漏到代码库 B；记忆库位于代码库本地。

---

架构（面向工具作者）

facts.jsonl——每行一个 JSON 对象：

{
  "id": "abc123def456",
  "ts": "2026-05-19T18:00:00Z",
  "claim": "Auth middleware lives in src/auth/middleware.py",
  "evidence": {
    "file": "src/auth/middleware.py",
    "lines": "42-180",
    "tool": "grep",
    "command": "rg 'def authenticate' src/",
    "verified_at": "2026-05-19T18:00:00Z"
  },
  "tags": ["auth"],
  "added_by": "claude-opus-4.7"
}

仅追加。过时条目会保留。读取者可查看 verified_at，并根据需要重新验证。

---

自动发现提示

repo-memory init 还会在仓库的 CLAUDE.md（如果已有 AGENTS.md，则为 AGENTS.md）中追加一段简短的发现说明，告知进入仓库的任何 AI Agent 先检查 .ai-memory/，并将新的发现记录回其中。此操作具有幂等性，重复运行不会造成重复内容。

使用 --no-claude-md 可选择退出。

追加的区块由 和 分隔，因此你可以随意手动编辑 CLAUDE.md 的其他部分。

---

CLI 参考

命令	效果
repo-memory init [--no-claude-md]	创建 .ai-memory/ 骨架，并（默认）更新 CLAUDE.md/AGENTS.md。
repo-memory show [--limit N]	将所有内容打印为一份 Markdown 文档。
repo-memory add-fact "<claim>" [--file F --lines L --tool T --command C --tag T --by AGENT]	追加一条事实。
repo-memory list-facts [--tag T] [--source-file F] [--since ISO] [--limit N] [--json]	列出／筛选事实。
repo-memory add-decision "<title>" [--body MD]	写入一个决策文件。
repo-memory list-decisions	列出决策文件路径。
repo-memory add-gotcha "<note>"	追加一条单行注意事项。

如果当前工作目录不是仓库根目录，所有命令都可以使用 --root PATH。

---

关于作者

由 yubinkim444 创建，他也制作了 Kay's Records——一款适用于 iOS 和 Android 的应用。

如果这个项目为你节省了时间，不妨试用这款应用，这是表达感谢的最好方式。

许可证

MIT © yubinkim444