# 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。克隆并执行安装器：

```bash
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，或打开一个新任务。

验证安装：

```bash
codex-hermes-bridge doctor
codex mcp list
```

## Skill 人工审批

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

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

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

## 更新与卸载

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

```bash
./scripts/update.sh
```

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

```bash
codex-hermes-bridge doctor
```

卸载桥接层：

```bash
./scripts/uninstall.sh
```

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

进一步阅读：[架构说明](docs/architecture.md)、[兼容性策略](docs/compatibility.md)、
[本机原型迁移说明](docs/migration.md)。