robo-cortex

# robo-cortex <!-- mcp-name: io.github.robotel-limited/robo-cortex --> [](https://pypi.org/project/robo-cortex/) [](https://pypi.org/project/robo-cortex/) [](https://opensource.org/licenses/MIT) [](https://smithery.ai/servers/robotel-top/robo-cortex) **面向 AI 编程代理的知识完整性**。 您的 AI 代理调试一个错误，学习了经验，但下周就忘记了 —— 或者更糟糕的是，不断引用一个已经被代码更新使其失效的“经验”。robo-cortex 是一个本地知识库，专为解决这一特定问题而设计：记忆通过 git blob 哈希值锚定，当它们所关联的代码发生变化时，记忆会自动被标记为需要审查，而不是被悄悄信任或丢失。 --- ## 为什么选择 robo-cortex，而不是另一个记忆工具 大多数代理记忆工具都是嵌入式 + 向量数据库 + 云依赖。robo-cortex 故意避免了这些。其他工具不具备的四项功能： 1. **Git 感知过期检测**。每个记忆都可以链接到特定的文件路径，通过 git blob 哈希值在记录时捕获。当链接的代码发生变化时，记忆会自动被标记为 `needs_review`，在下一次 `retrieve`/`search`/`affected` 调用时 —— 而且在代码恢复后，自动 healing 需要三个条件：（a）恢复必须是**已提交**（git blob 哈希值必须再次与 HEAD 匹配），（b）记忆必须由系统标记（而非手动通过 `change_status`），以及（c）您必须在恢复后运行一个延迟触发器（`retrieve`/`search`/`affected`）来扫描更改。没有其他记忆工具像这样与您的实际代码历史绑定。 2. **证据，而非直觉**。记忆可以携带附加证据（测试输出、提交、重新运行的命令），具有机械计算的强度 —— 而非判断调用。`provisional` 记忆只有在有真正的证据支持时，才能成为 `active`，或由人工明确提升。 3. **零依赖，完全本地**。纯标准库 + SQLite（用于搜索的 FTS5）。没有嵌入式、API 密钥或网络调用，除非您显式配置 Gitea 证据验证。`.cortex/memory.db` 只是一个文件 —— 随时可以使用 `sqlite3` 检查。 4. **具有审计轨迹的真实生命周期**。每个状态更改（`active` → `superseded` → `archived` 等）都需要一个 `--reason`，永久记录。没有任何内容被悄悄删除；错误的经验被标记为 `invalidated`，而非删除。 ## 衡量影响（基准，诚实陈述） 一个 30 会话基准测试（本存储库中的 3 个真实历史错误重新引入并由小型模型 —— Claude Haiku 4.5 —— 解决 10 次，有无 robo-cortex 记忆包），在 **相同的修复质量（30/30 正确，零取消资格）** 下测量，**约 12% 更少的 tokens 和约 15% 更低的 API 等效成本**（成对任务增量的中位数），最高可达 **-26% tokens / -39% 成本**，在任务中修复最难找到无辅助。记录一个经验本身被衡量：**一个记忆在重用它的大约 1-6 会话后支付自己**（中位数 ≈ 5）。我们 **不做出时钟声明** —— 时间差异被噪声主导。完整的基准测试方法、每次运行的原始证据（使用日志、差异、提示）和可重用的测试框架在存储库中：[docs/benchmark-results.md](https://github.com/robotel-limited/robo-cortex/blob/main/docs/benchmark-results.md)，[benchmark-results-20260718/](https://github.com/robotel-limited/robo-cortex/tree/main/benchmark-results-20260718)，[scripts/benchmark/](https://github.com/robotel-limited/robo-cortex/tree/main/scripts/benchmark)。已知限制，明确说明：一个主题模型（小型 —— 早期 n=3 试点在较大模型上测量较小 2.7% 效果，见 [EVALUATION.md](https://github.com/robotel-limited/robo-cortex/blob/main/EVALUATION.md) §9），一个有详细文档的代码库（可能压缩效果），3 种任务类型。我们宁愿发布一个谦逊的测量值，而不是一个我们没有的戏剧性测量值。 --- ## 快速开始 **先决条件：** robo-cortex 需要一个 git 仓库（过期检测需要 git 历史记录来比较）： ```bash git init && git add -A && git commit -m "初始提交" ``` ### 安装 ```bash pip install robo-cortex ``` 如果 `pip install` 拒绝使用 `error: externally-managed-environment`（在最近的 Debian/Ubuntu 上很常见），请使用虚拟环境或 `pipx`： ```bash python3 -m venv .venv && source .venv/bin/activate && pip install robo-cortex # 或：pipx install robo-cortex ``` 如果您计划将 robo-cortex 与支持 MCP 的代理（Claude Desktop/Code 等）一起使用，请安装 MCP 额外功能： ```bash pip install 'robo-cortex[mcp]' ``` ### 使用 ```bash cd /path/to/your/project roco init # 记录项目特定的经验（scope=repo：不需要额外字段） roco record --type lesson --scope repo \ --statement "复制到剪贴板在 HTTP 上失败；使用 textarea+execCommand 回退。" \ --confidence high # 稍后检索它 roco retrieve --task "复制到剪贴板 http" ``` ``` matched=1 returned=1 needs_review=0 contradicted=0 [1] score=0.650 repo lesson 复制到剪贴板在 HTTP 上失败；使用 textarea+execCommand 回退。 ``` `--path` 将记忆链接到文件，但只接受在 HEAD 处已经存在的路径（没有记忆会出生时指向一个失效的链接）。对于您刚刚编写但尚未提交的代码：现在记录记忆而不带 `--path`，提交，然后在之后附加路径： ```bash roco record --type decision --scope repo --statement "..." --confidence high # id=7，尚未链接路径 git add new_module.py && git commit -m "添加 new_module.py" roco record 7 --add-path new_module.py ``` 可重用的经验（不限于此项目）使用 `scope=global` 并需要 `--assumptions` —— 应用条件，以免被意外地在每个地方建议： ```bash roco record --type lesson --scope global \ --statement "Safari 14 破坏 CSS 网格 + 间隙。使用 flexbox + 边距代替。" \ --confidence high \ --assumptions "css 网格 间隙 safari" ``` ### 启用强制执行（推荐） ```bash roco hooks install ``` 安装 git 预提交钩子：如果提交影响到与记忆链接的代码，这些记忆处于 `active`/`provisional`/`needs_review` 状态，则提交将被阻止，并附上记忆的 ID 和审查提示，直到您审查或显式绕过。示例，对于与 `src/scanner.py` 链接的记忆，当该文件是提交的一部分时： ``` robo-cortex: 此提交影响到与记忆链接的代码，这些记忆需要审查： [1] path_changed:src/scanner.py@working_tree 扫描器每 50 项故意批量处理 使用以下命令审查：roco show <id> 然后重新验证（roco status <id> activate --reason "..."）或取代它，并再次提交。 要绕过此检查：git commit --no-verify ``` 绕过是真实且有文档的 —— `git commit --no-verify` 跳过它，与任何 git 钩子一样。这是“默认强制执行，显式绕过”，而不是“无法跳过”。有关 `uninstall`/`status` 的详细信息，请参见 `roco hooks --help`。对于拉取请求上的 CI 级检查，除了（或除了）本地提交，请参见 [docs/ci-example.yml](https://github.com/robotel-limited/robo-cortex/blob/main/docs/ci-example.yml)。 还有一个可选的提交后钩子，纯粹是信息性的（它从不阻止 - 它报告的提交已经发生）： ```bash roco hooks install --post-commit ``` 它在每次提交后运行 `roco affected --diff-range HEAD~1..HEAD`，并报告任何风险，这样一个标志立即出现，而不是等待下一次 `retrieve`/`search`/`affected` 调用。`--post-commit` 也与 `uninstall`/`status` 一起工作，独立于预提交钩子。 --- ## 缩写：`roco` `robo-cortex` 和 `roco` 是相同的命令（相同的二进制文件，两个脚本入口点）。使用适合您的： ```bash roco retrieve --task "..." # 较短的别名 robo-cortex retrieve --task "..." # 完整名称，向后兼容 ``` **名称冲突注意：** PyPI 已经有一个无关的包名为 `roco`（“运行时配置生成器”）。如果该包也安装在同一环境中，最后安装的包将赢得 `roco` 命令 - 使用完整名称 `robo-cortex` 以明确：或检查 `roco --version` 以确认您实际运行的是哪一个。 ### Shell 补全 ```bash roco completion bash >> ~/.bashrc ``` 完成子命令名称和每个子命令自己的标志（不是标志值，也不是嵌套子命令，如 `hooks install`）。它是一个静态脚本，从已安装的版本生成 - 升级后重新运行该命令以获取新命令或标志。 --- ## 三种使用方式 | 场景 | 最佳方法 | 为什么 | |----------|-------------|-----| | 一次性 CLI 命令（shell、脚本、手动测试） | CLI：`roco retrieve --task "..."` | 最简单，无依赖，立即 | | 运行您自己的代码的 Python 代理或脚本 | Python SDK：`from robo_cortex import retrieve, record` | 进程内（无子进程），真实异常，非字符串解析错误 | | 带有工具调用的 LLM 代理（Claude Code，或任何 MCP 客户端） | MCP 服务器：添加到您的 MCP 配置 | 代理决定何时调用；工具描述随软件包提供 | 所有三种调用相同的底层 `robo_cortex.core` 函数 - 根据调用代码已经使用哪种方式选择。 ### MCP 配置 ```json { "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](https://github.com/robotel-limited/robo-cortex/blob/main/MCP_TOOLS.md)。 ### Python SDK ```python from robo_cortex import retrieve, record memories = retrieve("功能描述", repo_path="/srv/project") if memories["data"]: print(f"找到解决方案：{memories['data'][0]['statement']}") record( type="lesson", statement="您学到了什么", confidence="high", repo_path="/srv/project", ) ``` 完整 API，包括 `RoboCortex` 类，用于对同一存储库进行多次调用，见 [PYTHON_SDK.md](https://github.com/robotel-limited/robo-cortex/blob/main/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 "..."` 手动更改状态： ```bash # 提升临时记忆（尚未有证据） roco status 5 activate --reason "在三个项目中测试和验证" # 将记忆标记为被更好的经验教训取代 roco status 7 supersede --supersedes 12 --reason "版本 2 的此模式更好地处理边缘情况" # 标记为已被证明是错误的 roco status 9 invalidate --reason "基准测试显示此优化实际上使事情变慢" # 存档旧的/已解决的项目 roco status 3 archive --reason "不再适用数据库迁移后" ``` `--reason` 是强制性的，并且是永久的 - 它成为记忆的审计历史的一部分，无法编辑。 --- ## 决定范围（全局 vs 存储库） **使用 `scope=repo`** 进行项目特定的学习： - 本代码库选择的模式（我们使用 FastAPI + SQLAlchemy） - 项目特定的决策（为我们的基础设施调整的批量大小） - **测试：** “此参考是否涉及我们的代码、基础设施或团队决策？” **使用 `scope=global`** 进行可重用经验： - 浏览器/库错误（Safari CSS，Node.js 异步模式） - 语言/框架模式 - 最佳实践（SQL 注入预防） `scope=global` 需要 `assumptions` - 应用条件，以免被意外地在每个地方建议： ```json { "type": "lesson", "scope": "global", "statement": "复制到剪贴板在 HTTP 上失败。使用 textarea + execCommand() 回退。", "assumptions": "具有剪贴板功能的 Web 应用程序，需要在 HTTP 上工作", "confidence": "high" } ``` --- ## 跨项目共享知识 ```bash roco export --scope global --output kb.jsonl # 在另一个项目中： roco import kb.jsonl ``` 导入是幂等的（重新导入相同的文件会跳过重复的 ID + 范围）并且精确验证，就像 `record` 一样 - 缺少 `assumptions` 的 `scope=global` 行或无效的 `type`/`confidence` 会被跳过，并带有警告，而不是被静默插入或原始数据库错误。 两个独立学习过的项目可以通过 `roco merge` 收敛： ```bash roco merge kb_a.jsonl kb_b.jsonl --output kb_merged.jsonl # 两个项目然后：roco import kb_merged.jsonl ``` 按 ID + 范围去重；冲突通过置信度解决（较高的胜出），通过时间戳打破僵局。有关完整的流程，包括团队知识库和备份用例，请参见 [EXPORT_IMPORT.md](https://github.com/robotel-limited/robo-cortex/blob/main/EXPORT_IMPORT.md)。 **不要将 `ROBO_CORTEX_GLOBAL_DB` 指向网络文件系统（NFS/SMB）作为“共享团队记忆”**。SQLite 不适用于网络挂载上的并发写入者，并且可能会损坏数据库。请通过 git 共享导出的知识 - 它是版本控制和可审计的，而实时共享的文件则不是。 --- ## 常见问题 **问：我需要一个 git 仓库吗？** 答：是的。过期检测、路径链接和 `affected` 都与 git 历史记录进行比较。没有 git，您仍然可以使用 export/import/merge 在机器之间移动知识，但 git 感知功能将无法工作。 **问：如果我（或我的代理）忘记检查记忆怎么办？** 答：`roco hooks install` 阻止了一个提交，该提交影响到与未经审查的记忆链接的代码 - 但绕过（`git commit --no-verify`）是真实且始终可用的，与任何 git 钩子一样。这是默认强制执行，并具有明确的逃脱机制，而不是无条件的保证。 **问：过时的笔记很危险。** 答：当链接的代码更改时，记忆会自动标记为需要审查。您在信任之前进行审查，或者将其标记为已取代。没有什么能静默地误导。 **问：跨团队共享记忆？** 答：两种方法： - **快照共享**（版本控制，审计）：从一个项目导出，提交到 git，团队成员导入。 - **实时共享数据库**：设置 `ROBO_CORTEX_GLOBAL_DB=/path/to/shared/global.db` 在本地路径上，所有 `roco` 调用都可以访问 - 而不是网络挂载（参见上面的警告）。 **问：离线？** 答：是的。所有内容都是本地 SQLite。零网络调用，除非您显式配置 Gitea 证据验证（`ROBO_CORTEX_GITEA_URL`）。 **问：错误的经验教训？** 答：将其标记为 `invalidated` 并附上原因。保存在历史记录中，今后不会被建议。 **问：只读数据库？** 答：`retrieve`/`search`/`affected` 在只读 `.cortex/memory.db`（只读检出，一些 CI 设置）上表现正常。读取返回结果，写入（过期刷新，使用跟踪）被跳过，`meta` 包含警告。记忆核心仍然有效，只是没有事件写入影响正确性。 **问：如何退出全局存储？** 答：设置 `ROBO_CORTEX_NO_GLOBAL=1`。CLI 和 MCP 都跳过打开 `~/.cortex/global.db` - `retrieve`/`search` 严格限定在当前存储库的范围内，没有跨项目知识通道。有用如果您想要严格的每个项目隔离。 **问：预期的规模是多少？** 答：robo-cortex 设计并测试了每个存储库（存储库范围和全局存储）数千个记忆。性能随着存储库范围超过此值而优雅地降低 - 每个候选人的评分保持 O（n），每个存储库的 FTS 候选人集限制为 200。如果您有比这多得多的记忆，请考虑将其分成多个项目或存档旧记忆。有关详细信息，请参见 [ARCHITECTURE.md](https://github.com/robotel-limited/robo-cortex/blob/main/ARCHITECTURE.md)。 --- ## 架构 ``` 代码库 ↓ git 预提交钩子（roco hooks install）-- 阻止影响未经审查的记忆的提交 ↓ robo-cortex 记忆（SQLite + FTS5） ↓ .cortex/memory.db（存储库）+ ~/.cortex/global.db（共享） ↓ retrieve_context() → 按过期和假设条件筛选的记忆，具有证据 ``` 无嵌入。无云。只有一个您检查的显式强制层（`.git/hooks/pre-commit` 是普通的 shell，可读性为 5 秒）。 --- ## 了解更多 - [ARCHITECTURE.md](https://github.com/robotel-limited/robo-cortex/blob/main/ARCHITECTURE.md) — 设计和数据模型 - [MCP_TOOLS.md](https://github.com/robotel-limited/robo-cortex/blob/main/MCP_TOOLS.md) — 代理的工具合约 - [PYTHON_SDK.md](https://github.com/robotel-limited/robo-cortex/blob/main/PYTHON_SDK.md) — 进程内 Python API - [EXPORT_IMPORT.md](https://github.com/robotel-limited/robo-cortex/blob/main/EXPORT_IMPORT.md) — 跨项目共享知识 - [EVALUATION.md](https://github.com/robotel-limited/robo-cortex/blob/main/EVALUATION.md) — 测试结果和基准，包括上述诚实的代币经济数字 - [ROADMAP.md](https://github.com/robotel-limited/robo-cortex/blob/main/ROADMAP.md) — 暂时不构建的内容及原因 - [CHANGELOG.md](https://github.com/robotel-limited/robo-cortex/blob/main/CHANGELOG.md) — 版本发布历史 --- ## 由 **免费使用。** 由 **Robotel Limited UK** ([https://robotel.top](https://robotel.top)) 提供。 架构设计时参考了 2026 年 7 月与 Anthropic 的 Claude（Fable）作为 AI 开发代理，结合 Robotel Limited 开发人员的专业知识，他们在生产环境中构建和操作 AI 编程代理已超过三年。 MIT 许可。开源。无遥测。无供应商锁定。