Codex Hermes MCP 隔离桥接

本仓库通过独立 MCP 桥接，为本地 Codex 提供 Hermes 风格的长期上下文和可选工具， 同时不修改 Hermes 源码，也不写入 Codex 原生 Skill 目录。

隔离承诺

• Codex 只通过两个本地 stdio MCP 注册项连接桥接层。
• 核心服务只写入 ~/.local/share/codex-hermes-mcp-bridge。
• ~/.hermes/memories、~/.hermes/state.db 和 ~/.hermes/skills 始终只读。
• 不向 ~/.codex/skills 或 ~/.agents/skills 写入文件或创建链接。
• MCP 可以生成 Skill 候选提案，但只能通过本地 CLI 人工批准。
• 可选 Hermes 工具适配器可以使用 Hermes 运行时 API，但不会修改 Hermes 源码仓库； 更新不兼容时只停用该适配器。
• 卸载只删除带所有权标记的桥接代码和 MCP 配置；桥接数据、Hermes 数据和 Codex 数据全部保留。

无法保证与所有未知未来版本绝对兼容。本项目提供的是范围明确、可测试的保证：遇到 不兼容时安全关闭对应能力，不损坏数据，也不让 Codex 原生任务依赖桥接层才能运行。

主要能力

独立核心 MCP 服务提供：

• 桥接层自有的长期用户记忆和项目记忆；
• 对现有 Hermes 记忆及 user/assistant 会话的只读检索；
• 桥接层自有的项目 Checkpoint；
• 对 Hermes Skill 的只读发现和加载；
• 隔离的 bridge Skill，以及创建、局部更新和归档提案；
• 只能由人工执行的 Skill 批准与拒绝；
• 有边界的持续进化建议和兼容性诊断。

可选适配器会暴露当前 Hermes 环境可用的网页、浏览器、视觉、图像、语音和 Kanban 工具。Codex 配置将该服务标记为非必需，并对所有工具调用启用审批。

安装

安装条件：Python 3.11+、Codex，以及本地 Hermes。克隆并执行安装器：

git clone https://github.com/yejuntian/codex-hermes-mcp-bridge.git
cd codex-hermes-mcp-bridge
./scripts/install.sh

安装器会在 ~/.local/lib/codex-hermes-mcp-bridge 创建独立虚拟环境，在 ~/.local/bin 创建桥接启动器和单独的可选适配器启动器，备份 ~/.codex/config.toml，然后追加带所有权标记的 MCP 配置块。

如果当前 Python 包源无法提供 MCP SDK，安装器会从现有 Hermes venv 复制一份依赖 快照到独立 core venv。可选适配器使用 Hermes 自己的运行时，但不会向该运行时安装 文件或修改源码。安装完成后请重新启动 Codex，或打开一个新任务。

验证安装：

codex-hermes-bridge doctor
codex mcp list

Skill 人工审批

Codex 可以通过 skill_propose 暂存候选，但不能批准自己的提案。请在本地查看完整 内容后再决定：

codex-hermes-bridge proposal list
codex-hermes-bridge proposal show sp_0123456789abcdef
codex-hermes-bridge proposal approve sp_0123456789abcdef

被拒绝的候选会保留为审计记录。删除提案通过后只会归档 bridge-owned Skill，不会 永久删除。Hermes Skill 通过本桥接始终只读，不能被局部更新或删除。

更新与卸载

拉取或切换到目标仓库版本后执行：

./scripts/update.sh

更新只替换桥接运行环境及其所有权配置块。每次更新 Hermes 或 Codex 后，建议执行：

codex-hermes-bridge doctor

卸载桥接层：

./scripts/uninstall.sh

卸载会保留 ~/.local/share/codex-hermes-mcp-bridge。只有在明确希望永久清除桥接记忆 和 Skill 时，才应另行删除该数据目录。

进一步阅读：架构说明、兼容性策略、 本机原型迁移说明。