robo-cortex

robo-cortex

为 AI 编码 Agent 提供 Git 感知的知识完整性保障。

你的 AI Agent 调试了一个 bug，吸取了教训，但到下周就忘了——更糟的是，它还可能继续引用一条已经被代码变更推翻的“教训”。robo-cortex 是专为这种情况打造的本地知识库：记忆会锚定到 git blob 哈希，因此相关代码一旦变更，记忆就会自动标记为待审核，而不是被默默信任或悄然丢失。换句话说：为 AI Agent 记忆提供漂移检测和陈旧记忆检测，通过 git 历史确定性地完成——不是大模型猜测，也不是基于嵌入相似度的启发式判断。

---

为什么选择 robo-cortex，而不是另一个记忆工具

大多数 Agent 记忆工具都由嵌入、向量数据库和云端依赖组成。robo-cortex 刻意避开了这些。它具备通用键值记忆存储不具备的四项能力：

1. Git 感知的过时（漂移）检测。 每条记忆都可以关联到特定文件路径，并在记录时通过 git blob 哈希捕获。当关联代码发生变更时，下次调用 retrieve/search/affected 会自动将记忆标记为 needs_review；如果变更被提交回退，记忆也会自动恢复。恢复需要满足三个条件：(a) 回退必须已提交（git blob 哈希必须再次与 HEAD 匹配），(b) 记忆必须由系统标记（而不是通过 change_status 手动标记），并且 (c) 回退后必须运行一次惰性触发操作（retrieve/search/affected）来扫描变更。很少有记忆工具能以这种确定性与实际代码历史关联——无需嵌入相似度，无需大模型判断，只需确认 git blob 哈希是否匹配。
2. 证据，而非感觉。 记忆可以附带证据（测试输出、提交、可重新运行的命令），并以机械方式计算其强度——无需主观判断。只有获得真实证据支持，或由人类明确提升状态后，provisional 记忆才会变为 active。
3. 零依赖，完全本地。 纯标准库 + SQLite（使用 FTS5 搜索）。没有嵌入、无需 API 密钥，也不会发起网络调用，除非你明确配置 Gitea 证据验证。.cortex/memory.db 就是一个文件——随时可以用 sqlite3 检查。
4. 真正的生命周期与审计记录。 每次状态变更（active → superseded → archived 等）都必须提供 --reason，并永久记录。任何内容都不会悄然消失；错误的教训会被标记为 invalidated，而不是删除。

实测效果（基准测试，如实陈述）

一项包含 30 次会话的基准测试（取自此仓库中 3 个真实历史 bug，将其重新引入，并由小型模型 Claude Haiku 4.5 在有和没有 robo-cortex 记忆包的情况下各解决 10 次）测得，在修复质量完全相同（30/30 正确，零项不合格）的情况下：新增 token 减少约 12%，API 等效成本降低约 15%（按任务配对差值的中位数计算）；对于那个在没有辅助时最难定位修复方案的任务，降幅最高达到token 减少 26%／成本降低 39%。记录经验本身也计入了成本：记忆在被重复使用约 1–6 次会话后即可收回成本（中位数约为 5 次）。我们不对耗时作任何声称——时间差异主要受噪声影响。完整的方法说明、每次运行的原始证据（使用日志、差异、提示词）以及可复用的测试工具都在仓库中：docs/benchmark-results.md、benchmark-results-20260718/、scripts/benchmark/。已知局限，直言不讳：只有一个受测模型（小型模型——此前在较大型模型上进行的 n=3 试点测得效果较小，为 2.7%，见 EVALUATION.md §9）、一个文档完善的代码库（可能会压低效果）、3 种任务类型。我们宁愿发布实测得出的适度数字，也不愿发布未经测量的夸大数字。

---

快速开始

**前置条件：**robo-cortex 需要 Git 仓库（过时检测需要通过 Git 历史进行比较）：

git init && git add -A && git commit -m "initial commit"

安装

pip install robo-cortex

如果 pip install 因 error: externally-managed-environment 而拒绝安装（近期 Debian/Ubuntu 系统上很常见），请使用虚拟环境或 pipx：

python3 -m venv .venv && source .venv/bin/activate && pip install robo-cortex
# or: pipx install robo-cortex

如果你计划将 robo-cortex 与支持 MCP 的 Agent（Claude Desktop/Code 等）搭配使用，请改为安装 MCP 扩展：

pip install 'robo-cortex[mcp]'

使用方法

cd /path/to/your/project
roco init

# Record a project-specific lesson (scope=repo: no extra fields needed)
roco record --type lesson --scope repo \
  --statement "Copy-to-clipboard fails on HTTP; use a textarea+execCommand fallback." \
  --confidence high

# Retrieve it later
roco retrieve --task "copy to clipboard http"

matched=1 returned=1 needs_review=0 contradicted=0
[1] score=0.650 repo   lesson       Copy-to-clipboard fails on HTTP; use a textarea+execCommand fallback.

--path 会将一条记忆关联到文件，但只接受在 HEAD 中已存在的路径（绝不会创建指向失效链接的记忆）。对于刚写完但尚未提交的代码：现在先不带 --path 记录记忆，提交后再关联路径：

roco record --type decision --scope repo --statement "..." --confidence high
# id=7, no linked path yet

git add new_module.py && git commit -m "add new_module.py"
roco record 7 --add-path new_module.py

可复用的经验（并非此项目特有）使用 scope=global，并且需要提供 --assumptions——即经验适用的条件，以免它意外地在所有场景中都被推荐：

roco record --type lesson --scope global \
  --statement "Safari 14 breaks CSS grid+gap. Use flexbox+margin instead." \
  --confidence high \
  --assumptions "css grid gap safari"

全局范围命令（record --scope global、show、search、status、link、evidence、list）可在任何位置运行，包括 Git 仓库之外——全局存储（~/.cortex/global.db）不与任何项目绑定。retrieve 是唯一例外：它按设计会感知本地仓库，因此仍需要已初始化的仓库。

启用强制检查（推荐）

roco hooks install

安装 Git 提交前钩子：如果提交涉及与状态为 active/provisional/needs_review 的记忆关联的代码，提交就会被阻止，并显示记忆 ID 和审核提示，直到你完成审核或明确绕过检查。例如，当 src/scanner.py 文件属于此次提交，且有记忆与其关联时：

robo-cortex: this commit touches code linked to memories that need review:
  [1] path_changed:src/scanner.py@working_tree  scanner batches at 50 items deliberately

Review with: roco show <id>
Then either re-verify (roco status <id> activate --reason "...") or supersede it, and commit again.
To bypass this check: git commit --no-verify

绕过检查是可行且有文档说明的——git commit --no-verify 会跳过检查，和其他 Git 钩子一样。这是“默认强制检查，明确绕过”，而非“无法跳过”。查看 roco hooks --help 了解 uninstall/status。若要在拉取请求上进行 CI 级检查，以替代或补充本地提交检查，请参阅 docs/ci-example.yml。

此外还有一个可选的提交后钩子，仅用于提供信息（它不会阻止提交——等它运行时，它所报告的提交已经完成）：

roco hooks install --post-commit

每次提交后，它都会运行 roco affected --diff-range HEAD~1..HEAD 并报告任何存在风险的内容，让标记立即显示，而不必等到下次调用 retrieve/search/affected。--post-commit 也可与 uninstall/status 配合使用，且独立于提交前钩子。

---

简写：roco

robo-cortex 和 roco 是完全相同的命令（同一个二进制文件，有两个脚本入口点）。选择你用起来顺手的那个：

roco retrieve --task "..."          # Shorter alias
robo-cortex retrieve --task "..."   # Full name, backwards compatible

名称冲突说明： PyPI 上已有一个名为 roco 的无关软件包（“Runtime Config Generator”）。如果同一环境中也安装了该软件包，则最后安装的软件包会占用 roco 命令——请使用完整名称 robo-cortex 以避免歧义，或运行 roco --version 确认实际执行的是哪个版本。

Shell 自动补全

roco completion bash >> ~/.bashrc

可补全子命令名称以及各子命令自身的标志（不包括标志值，也不包括 hooks install 这类嵌套的子子命令）。这是根据已安装版本生成的静态脚本——升级后请重新运行该命令，以获取新命令或标志。

---

三种使用方式

场景	最佳方式	原因
一次性 CLI 命令（Shell、脚本、手动测试）	CLI：roco retrieve --task "..."	最简单，无依赖，立即生效
运行自有代码的 Python Agent 或脚本	Python SDK：from robo_cortex import retrieve, record	在进程内运行（无需子进程），异常真实，错误无需解析字符串
使用工具调用的 LLM Agent（Claude Code 或任何 MCP 客户端）	MCP 服务：添加到 MCP 配置中	Agent 决定何时调用；工具说明随软件包一并提供

这三种方式都会调用相同的底层 robo_cortex.core 函数——根据调用代码已经使用的方式来选择。

MCP 配置

{
  "mcpServers": {
    "robo-cortex": {
      "command": "roco",
      "args": ["mcp", "--repo", "/path/to/project"]
    }
  }
}

可用工具：retrieve_context、record_memory、search_memory、attach_evidence、verify_evidence、change_status、get_memory、list_affected。完整规范见 MCP_TOOLS.md。

Python SDK

from robo_cortex import retrieve, record

memories = retrieve("feature description", repo_path="/srv/project")
if memories["data"]:
    print(f"Found solution: {memories['data'][0]['statement']}")

record(
    type="lesson",
    statement="What you learned",
    confidence="high",
    repo_path="/srv/project",
)

完整 API（包括用于对同一仓库进行多次调用的 RoboCortex 类）见 PYTHON_SDK.md。

---

记忆生命周期：状态转换

每条记忆都有一个状态，用于反映其可信度和适用性。新记忆的初始状态为 provisional；人工审核或证据会改变其状态：

状态	含义	可转换为
provisional	新记忆，尚未验证	active、needs_review、abandoned
active	可信，适用于未来工作	needs_review、superseded、invalidated、archived、abandoned
needs_review	存疑或依赖上下文；需要人工判断	active、superseded、invalidated
superseded	已被更好的解决方案取代（必须链接到替代记忆的 ID）	archived
invalidated	已证明错误或不再适用	archived
abandoned	没有结果的经验；探索走入死胡同	archived
archived	终止状态（只读）	—

自动转换

• provisional → active：将证据附加到记忆时会自动发生（roco evidence add）——首条支持性数据会将记忆提升为可信状态。

手动转换

使用 roco status <id> <verb> --reason "..." 手动更改状态：

# Promote a provisional memory (no evidence yet)
roco status 5 activate --reason "Tested and validated on three projects"

# Mark a memory as superseded by a better lesson
roco status 7 supersede --supersedes 12 --reason "Version 2 of this pattern handles edge cases better"

# Mark as proven false
roco status 9 invalidate --reason "Benchmark shows this optimization actually makes things slower"

# Archive old/resolved items
roco status 3 archive --reason "No longer applicable after database migration"

--reason 是必填项且不可更改——它会成为记忆审计历史的一部分，且无法编辑。

---

确定范围（全局还是仓库）

项目特有的经验使用 scope=repo：

• 此代码库采用的模式（我们使用 FastAPI + SQLAlchemy）
• 项目特有的决策（针对我们的基础设施调整批处理大小）
• 测试：“这是否涉及我们的代码、基础设施或团队决策？”

可复用的经验使用 scope=global：

• 浏览器／库的缺陷（Safari CSS、Node.js 异步模式）
• 语言／框架模式
• 最佳实践（防止 SQL 注入）

scope=global 必须包含 assumptions，即经验适用的前提条件：

{
  "type": "lesson",
  "scope": "global",
  "statement": "Copy-to-clipboard fails on HTTP. Use textarea + execCommand() fallback.",
  "assumptions": "Web app with clipboard feature, needs to work on HTTP",
  "confidence": "high"
}

---

在项目间共享知识

roco export --scope global --output kb.jsonl
# In another project:
roco import kb.jsonl

导入操作具有幂等性（重新导入同一文件时，会根据 id+scope 跳过重复项），且验证方式与 record 完全相同——缺少 assumptions 的 scope=global 条目，或无效的 type／confidence，会被跳过并显示警告，而不会被静默插入或导致原始数据库错误。

两个独立积累知识的项目可以通过 roco merge 汇合：

roco merge kb_a.jsonl kb_b.jsonl --output kb_merged.jsonl
# Both projects then: roco import kb_merged.jsonl

根据 ID+scope 去重；冲突由置信度决定（较高者胜出），置信度相同时则按时间戳决定。完整工作流（包括团队知识库和备份用例）请参阅 EXPORT_IMPORT.md。

不要将 ROBO_CORTEX_GLOBAL_DB 指向网络文件系统（NFS/SMB），以实现“团队共享记忆”。 SQLite 不支持通过网络挂载进行并发写入，且可能损坏数据库。请改用 git 进行导出／导入来共享——这样可以保留版本记录并便于审计，而实时共享的文件无法做到这一点。

---

常见问题

问：我需要 Git 仓库吗？ 答：需要。过时检测、路径关联和 affected 都会与 Git 历史进行比较。没有 Git 时，你仍可使用 export/import/merge 在不同机器间迁移知识，但依赖 Git 的功能将无法使用。

问：如果我（或我的 Agent）忘了检查记忆怎么办？ 答：roco hooks install 会阻止提交触及与未审核记忆关联的代码——但绕过方式（git commit --no-verify）确实存在，而且始终可用，就像任何 Git 钩子一样。这是默认执行并提供明确的退出途径，而不是无条件保证。

问：过时的笔记很危险。 答：关联代码发生变化时，记忆会自动标记为 needs_review。你可以在信任它们之前进行审核，或将其标记为已取代。不会有任何内容在不知情的情况下误导你。

问：如何在团队间共享记忆？ 答：有两种方式：

• 快照共享（有版本记录、可审计）：从一个项目导出，将 JSONL 提交到 Git，然后由团队成员导入。
• 实时共享数据库：在所有 roco 调用都能访问的本地路径上设置 ROBO_CORTEX_GLOBAL_DB=/path/to/shared/global.db——不要使用网络挂载（参见上面的警告）。

问：可以离线使用吗？ 答：可以。所有数据都存储在本地 SQLite 中。除非你明确配置 Gitea 证据验证（ROBO_CORTEX_GITEA_URL），否则不会发起任何网络请求。

问：经验有误怎么办？ 答：将其标记为 invalidated 并说明原因。它会保留在历史记录中，今后不再被建议。

问：数据库只读怎么办？ 答：在只读的 .cortex/memory.db 上（只读检出、某些 CI 设置），retrieve/search/affected 会优雅降级。读取会返回结果，写入（过时状态刷新、使用情况跟踪）会被跳过，且 meta 会包含警告。记忆核心仍可正常工作，只是不进行那些不会影响正确性的附带写入。

问：如何退出全局存储？ 答：设置 ROBO_CORTEX_NO_GLOBAL=1。CLI 和 MCP 都会完全跳过打开 ~/.cortex/global.db——retrieve/search 会严格限定在当前仓库范围内，不会通过跨项目知识通道获取知识。如果你想实现严格的项目间隔离，这会很有用。

问：预期的规模是多少？ 答：robo-cortex 的设计和测试目标是每个存储中包含数千条记忆（仓库范围和全局范围合计）。超出这个规模后，性能会逐步下降——每个候选项的评分仍为 O(n)，且每个存储的 FTS 候选集上限为 200。如果你的记忆数量远超此规模，可以考虑拆分成多个项目，或归档旧记忆。详情请参阅 ARCHITECTURE.md。

---

架构

Codebase
    ↓
git pre-commit hook (roco hooks install) -- blocks commits touching unreviewed memories
    ↓
robo-cortex Memory (SQLite + FTS5)
    ↓
.cortex/memory.db (repo)  +  ~/.cortex/global.db (shared)
    ↓
retrieve_context() → ranked memories with evidence, gated by staleness + assumptions

没有嵌入向量。没有云服务。只有 SQLite、对 Git 的感知能力，以及一个可供检查的明确执行层（.git/hooks/pre-commit 是纯 Shell 脚本，五秒内就能读完）。

---

了解更多

• ARCHITECTURE.md — 设计与数据模型
• MCP_TOOLS.md — 面向 Agent 的工具契约
• PYTHON_SDK.md — 进程内 Python API
• EXPORT_IMPORT.md — 跨项目共享知识
• EVALUATION.md — 测试结果和基准，包括上文引用的真实 Token 经济性数据
• ROADMAP.md — 有意暂未实现的内容及其原因
• CHANGELOG.md — 版本发布历史

---

制作者

免费使用。 由 Robotel Limited UK (https://robotel.top) 提供。

该架构于 2026 年 7 月由 Anthropic 的 Claude（Fable）作为 AI 开发 Agent 设计，并融入了 Robotel Limited 开发人员的专业知识；他们拥有三年以上在生产环境中构建和运行 AI 编码 Agent 的实践经验。

MIT 许可证。开源。无遥测。无供应商锁定。