robo-cortex 是一个面向 AI 编程智能体的、Git 感知且证据驱动的记忆存储工具，由 Robotel Limited UK 开发并开源。它针对的核心问题是：编程智能体调试出结论后，容易遗忘，或继续引用已被代码变更推翻的旧“经验”。robo-cortex 将记忆锚定到 Git blob 哈希，当关联代码变化时自动将记忆标记为待审查，而不是被静默信任或静默丢失，即对智能体记忆做确定性的漂移检测与过期检测，依据 Git 历史而非 LLM 判断或嵌入相似度。
用途 为 AI 编程智能体提供可信赖的本地知识库，让调试经验、项目决策和可复用教训能够被记录、检索和验证，同时在代码演进后及时暴露可能已失效的记忆。
主要能力 Git 感知的过期（漂移）检测：每条记忆可关联具体文件路径，记录时捕获 Git blob 哈希。当关联代码变化后，下一次 retrieve、search 或 affected 调用会将其自动标记为 needs_review；一次已提交的回滚可自动使其恢复，恢复需满足三个条件：（a）回滚已提交（Git blob 哈希重新与 HEAD 一致），（b）该记忆是由系统而非手动 change_status 标记的，（c）回滚后运行了惰性触发（retrieve、search 或 affected）以扫描变更。 证据而非“感觉”：记忆可附带证据（测试输出、提交、可重复执行的命令），强度由机械方式计算。暂定记忆只有在获得真实证据支撑或人工显式升级后才会变为活动状态。 零依赖、完全本地：纯标准库加 SQLite（搜索使用 FTS5）。无嵌入、无 API 密钥、无网络调用，除非显式配置 Gitea 证据验证。.cortex/memory.db 就是一个文件，可随时用 sqlite3 检查。 带审计轨迹的真实生命周期：每次状态变更（active → superseded → archived 等）都要求提供 --reason，并被永久记录；错误教训被标记为 invalidated 而非删除。
使用方式 前置条件：需要 Git 仓库（过期检测需要 Git 历史进行比对）。如果 pip install 因 externally-managed-environment 报错（常见于较新的 Debian/Ubuntu），请使用虚拟环境或 pipx。若要与支持 MCP 的智能体（Claude Desktop/Code 等）配合使用，请安装 MCP 额外项。--path 用于将记忆链接到文件，但只接受在 HEAD 已存在的路径（不会产生指向死链的记忆）；对于刚写但尚未提交的代码，可先不带 --path 记录记忆，提交后再附加路径。可复用教训（非项目特定）使用 scope=global，且必须提供 --assumptions，说明该教训适用的条件。全局范围的命令（record --scope global、show、search、status、link、evidence、list）可在任何位置运行，包括 Git 仓库之外，因为全局存储 ~/.cortex/global.db 不绑定项目；retrieve 是例外，它按设计是本地仓库感知的，仍需要已初始化的仓库。 三种使用方式：CLI、MCP、Python SDK，三者调用相同的 robo_cortex.core 函数。CLI 提供 robo-cortex 与 roco 两个等价命令名（同一二进制、两个脚本入口）。注意 PyPI 上已有一个同名无关包 roco（Runtime Config Generator），若同环境安装，后安装者会占据 roco 命令，此时应使用完整的 robo-cortex 名称或以 roco --version 确认。MCP 可用工具包括 retrieve_context、record_memory、search_memory、attach_evidence、verify_evidence、change_status、get_memory、list_affected，完整契约见 MCP_TOOLS.md；Python SDK 见 PYTHON_SDK.md。另有 Shell 补全（补全子命令名及各子命令自身标志，不补全标志值，也不补全 hooks install 之类的嵌套子命令），为基于安装版本生成的静态脚本，升级后需重新运行。 强制约束（可选，推荐）：安装 Git pre-commit 钩子后，若提交触及与处于 active、provisional 或 needs_review 状态的记忆相关联的代码，提交会被阻止，并给出记忆 id 与审查提示，直到审查或显式绕过；绕过方式为 git commit --no-verify，属于“默认强制、可显式绕过”。还提供可选 post-commit 钩子，纯通知、不阻止提交，在每次提交后运行 roco affected --diff-range HEAD~1..HEAD 并报告有风险的内容。CI 级别检查可参考 docs/ci-example.yml。 状态生命周期：新记忆以 provisional 开始；通过 roco evidence add 附加证据后自动从 provisional 变为 active；可用 roco status <id> <verb> --reason "..." 手动变更状态，--reason 为强制且永久记录、不可编辑。 知识共享：export/import 支持跨项目共享，导入幂等（按 id+scope 跳过重复）并像 record 一样校验，缺失 assumptions 或 type/confidence 非法的 scope=global 条目会被跳过并给出警告。roco merge 可合并两个独立学习的项目，按 ID+scope 去重，冲突按 confidence 更高者胜、时间戳决胜。官方警告：不要将 ROBO_CORTEX_GLOBAL_DB 指向网络文件系统（NFS/SMB）来“共享团队记忆”，SQLite 在网络挂载上并发写入不安全，可能损坏数据库；应通过 Git 导出/导入共享。
适用场景 适合使用 AI 编程智能体进行长期项目开发的团队与个人，用于记录项目内约定与决策（scope=repo，如选用 FastAPI + SQLAlchemy、为自身基础设施调整的批次大小）以及可复用教训（scope=global，如浏览器/库缺陷、语言/框架模式、SQL 注入防护等最佳实践），并通过 Git 历史自动发现失效记忆，避免智能体引用过时经验。
限制与已知情况 需要 Git 仓库才能使用过期检测、路径链接和 affected 等 Git 感知功能；无 Git 时仍可用 export/import/merge 在机器间迁移知识。官方基准测试：30 次会话（3 个真实历史缺陷，分别由小模型 Claude Haiku 4.5 在有无 robo-cortex 记忆包的情况下各复现并解决 10 次），在修复质量相同（30/30 正确，零出局）下，中位数约减少 12% 的全新 token、约降低 15% 的 API 等效成本，在未辅助时最难定位的缺陷任务上可达减少 26% token / 降低 39% 成本；记录一条教训本身也计入计量，记忆约在 1 至 6 次复用会话后回本（中位数约 5）；不做墙钟时间声明。已知限制：单一受试模型（较小；更早针对更大模型的 n=3 试点测得较小 2.7% 效应，见 EVALUATION.md §9）、单一文档完善的代码库（可能压缩效应）、3 种任务类型。强制钩子可被 git commit --no-verify 绕过。只读数据库时 retrieve/search/affected 可优雅降级，读取返回结果，写入（过期刷新、使用跟踪）跳过，并在 meta 中给出警告。可通过 ROBO_CORTEX_NO_GLOBAL=1 完全退出全局存储。设计并测试规模为每存储数千条记忆，超出后性能优雅下降，评分按候选为 O(n)，每个存储的 FTS 候选集上限为 200。性能时间差异在测试中受噪声主导。不依赖嵌入、不上云。采用 MIT 许可证，开源、无遥测、无厂商锁定，可免费使用。
