内容
# 协调内存 MCP
[](https://github.com/yanqiw/comem/actions/workflows/ci.yml)
[](https://pypi.org/project/coordination-memory-mcp/)
[](https://www.python.org/)
[](LICENSE)
<!-- mcp-name: io.github.yanqiw/comem -->
追加只读的**协调内存**，适用于多智能体（和智能体 + 人类）的协作，作为本地 [模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，以 SQLite 为支持 - 加上本地网页管理仪表盘和目标级别的**验收合约**。
它记录 *谁拥有哪个任务*，运行活跃度，人类干预，移交证据和集成者审查决策。只有 **集成者** 才能将工作提升到已接受的账本中，您可以将其导出为持久的，可审计的投影（例如，提交到 Git）。
设计立场：MCP 是 **实时协调层**；持久的已接受事实存在于您投影到的任何地方。它是本地优先（SQLite + stdio），并且它永远不会部署，永远不会读取机密，并且永远不会执行 shell 命令。
## 为什么
当多个智能体（或智能体和人）推动同一工作主体时，会出现两个问题：它们会相互覆盖，并且 "我已经完成" 与 "已被接受" 混淆。协调内存为您提供：
- **具有租约的任务声明**，因此两个参与者不会抢占同一任务。
- **代理报告完成与集成者验收** 之间的明确区分。提案不是事实。
- **集成者拥有的已接受投影**，您在存档之前会审查。
- **验收合约**，使目标级别结果的 "自我认证完成" 在结构上成为不可能。
适用情况：多个智能体在独立的工作树上推进一个工作；需要在某事被视为已接受之前进行审查门控；想要一个可重放的协调决策审计跟踪。
不适用情况：作为您唯一的长期事实来源；作为存储 `.env` 文件、令牌、密码或凭据日志的地方。
## 启动资源
- [90 秒演示脚本](docs/demo-script.md) - 展示租约、移交证据、集成者验收和仪表盘的简短演练。
- [启动帖草稿](docs/launch-post.md) - 用于宣布项目的文件，不将其定位为通用内存或 RAG。
- [开源启动检查清单](docs/oss-launch-checklist.md) - 发布、GitHub 元数据、MCP 注册表和目录提交步骤。
## 安装
需要 Python ≥ 3.11。
使用 [uv](https://github.com/astral-sh/uv) 或 pipx 安装单个 `comem` 命令：
```bash
uv tool install coordination-memory-mcp # 或：pipx install coordination-memory-mcp
comem --help
```
或者在不安装的情况下运行（软件包名称和命令不同，因此请传递 `--from`）：
```bash
uvx --from coordination-memory-mcp comem --help
```
### 从源代码
如果 PyPI 页面还未上线，或者您想运行自己的更改，请直接从检出安装 `comem` 命令：
```bash
git clone https://github.com/yanqiw/comem
cd coordination-memory-mcp
uv tool install . # 或：pipx install .
comem --version
```
这是快照安装 - 重新运行它以应用源代码更改：
```bash
uv tool install . --reinstall # 从当前源代码重建
uv tool install . --editable --reinstall # 或安装可编辑版本：应用更改
uv tool uninstall coordination-memory-mcp # 删除它
```
命令公开了四个子命令：
- `comem serve` - stdio MCP 服务器。
- `comem dashboard` - 本地网页管理控制台。
- `comem init` - 为代码智能体初始化加入文件。
- `comem loop` - 为 Codex 智能体对话运行本地调度程序。
对于本地开发，克隆并运行 `uv sync`，然后在命令前加上 `uv run`。
## 快速入门
### 运行 MCP 服务器
```bash
comem serve
```
这启动了一个 stdio MCP 服务器（通常由 MCP 客户端启动）。它不打开任何 HTTP 端口，也不打印交互式 CLI。
数据库默认为 `./.coordination-memory/coordination.sqlite3`。覆盖它与 `COORDINATION_MEMORY_DB`。当多个智能体/工作树协作时，将所有智能体指向一个绝对路径 **外部** 每个工作树，否则每个工作树都有自己的 SQLite 副本，共享内存分叉：
```bash
COORDINATION_MEMORY_DB=/absolute/path/coordination.sqlite3 \
comem serve
```
不要将 SQLite 数据库提交到 Git。
### 配置 MCP 客户端
客户端配置位置不同，但使用安装的命令，服务器条目应如下所示：
```json
{
"mcpServers": {
"coordination-memory": {
"command": "comem",
"args": ["serve"],
"env": {
"COORDINATION_MEMORY_DB": "/absolute/path/coordination.sqlite3"
}
}
}
}
```
### 设置您的智能体
`comem init` 搭建了加入文件，以便您的代码智能体了解协议，然后打印此 MCP 配置片段：
```bash
comem init # 所有工具，当前目录
comem init --tools claude,cursor --dir ./my-repo
```
它在 `AGENTS.md`（在标记之间幂等）中写入了规范的**协调内存协议**部分和指向它的薄工具适配器：
| 工具 | 编写文件 |
| --- | --- |
| Codex，OpenCode | `AGENTS.md`（直接读取） |
| Claude Code | `.claude/skills/coordination-memory/SKILL.md` |
| Cursor | `.cursor/rules/coordination-memory.mdc` |
| GitHub Copilot | `.github/copilot-instructions.md` |
重新运行 `init` 会更新 `AGENTS.md` 部分（无重复）。在 `AGENTS.md` 中编辑协议；适配器会引用它。
## 本地循环
`comem loop` 是适用于一流 Codex 智能体对话的本地调度程序。初始版本支持 `--adapter fake` 进行确定性测试和 `--adapter codex-app-server` 功能探针，用于未来的本地 Codex 应用程序服务器集成。
干预调度：
```bash
comem loop --team default --adapter fake --dry-run --once
```
伪本地调度：
```bash
comem loop --team default --adapter fake --once
```
循环管理的任务应携带 `metadata.session_bind.target_actor_id`，以便调度程序在任何运行存在之前知道预期的工作者。实际的 Codex 线程绑定在声明/启动后记录在运行中。项目设计和计划上下文必须保留在 Markdown 文件中；任务应通过元数据 `context_refs` 引用这些文件。
## 概念
存储由六个核心表组成：
- **workspace → team → assignment → run → event**，以及 **actors**。
- **任务** 是一项工作单元。声明一个任务会启动一个 **run** 并获得一个租约。**事件** 是追加日志（证据、移交、审查等）。
- 参与者以 **角色** 参与：`integrator`、`agent` 或 `human`。
- 变更写入使用 **乐观并发**：每个都带有当前的 `base_revision` 并增加修订。
智能体可以提交的事件状态：`proposed`、`observed`、`completed_gate_passed`、`completed_gate_failed`。决策状态仅限 **集成者**：`integrator_accepted`、`integrator_rejected`、`needs_fix`。`completed_gate_passed` 不是已接受的事实 - 只有集成者审查决策才能产生已接受状态。
## 工具
**协调**
| 工具 | 角色 | 目的 |
| --- | --- | --- |
| `register_actor` | 任意 | 注册/刷新参与者配置文件 |
| `register_workspace` | 任意 | 创建/刷新工作区记录（幂等） |
| `create_team` | 任意 | 创建/刷新团队（自动创建其工作区） |
| `create_assignment` | 集成者 | 创建任务（可选工作区/团队/路径/标准） |
| `cancel_assignment` / `supersede_assignment` | 集成者 | 取消 / 替换任务（释放租约） |
| `claim_assignment` | 智能体 | 声明租约；记录运行/会话/工作树元数据 |
| `heartbeat_run` | 智能体 | 报告运行活跃度 |
| `request_intervention` / `respond_intervention` | 智能体 / 人类 | 将运行移动到 / 从等待人类通道 |
| `append_event` / `submit_handoff` | 智能体 | 追加证据 / 提交可审查的移交 |
| `list_pending_reviews` | 任意 | 具有无决策的可审查事件 |
| `review_event` / `accept_event` / `reject_event` | 集成者 | 记录审查决策 |
| `get_team_board` / `get_assignment_detail` / `get_run_detail` | 任意 | 读取模型 |
| `get_snapshot` / `export_git_projection` | 集成者 | 已接受的投影（见下文） |
**验收合约**
`create_acceptance_contract`、`add_invariant`、`raise_deviation`、
`bind_assignment_to_contract`、`seal_contract`、`report_verification`、
`evaluate_contract`、`accept_contract`、`reject_contract`、`waive_deviation`、
`reopen_contract`、`get_contract_detail`、`list_contracts`。
变更工具接受 `base_revision` 并拒绝过时的写入。运行/干预工具仅更改本地通道和事件时间线；它们从不执行命令、恢复线程或触摸文件。
## 验收合约（目标级治理）
**验收合约** 是一个一流对象，位于任务之上，定义了 **目标级结果** 的机器可检查的、非自我认证的验收标准。它是一个结构性保护层，其目的是使 "实现者声明完成" 成为不可能。
### 数据模型
| 表 | 角色 |
| --- | --- |
| `acceptance_contracts` | 合约：`goal_statement`、`status`（状态机）、`revision`（乐观并发）、`acceptor_actor_id`（独立验收者）、`max_repair_attempts`/`repair_attempt`（循环边界）、`last_failing_keys_json`（无进展刹车） |
| `contract_invariants` | 每个行一个机器可检查的谓词：`probe_kind`（`command`/`http`/`sql`/`file_assert`/`artifact_present`）、`probe_spec_json`（仅引用 - 无机密）、`is_negative`（拒绝测试）、`is_second_instance`（第二租户/第二实例测试）。冻结后密封。 |
| `contract_verifications` | 追加探针结果：`outcome`（`passed`/`failed`/`error`）、`evidence_json`（日志路径/提交/响应哈希 - 仅引用）。 "通过或不通过" 由最新的探针结果决定；运行者不能凭空标记谓词通过。 |
| `contract_deviations` | 偏差/快捷方式寄存器：`disposition` 是 **必需的**（`acceptable_forever`/`acceptable_this_phase`/`blocker`）。当任何 `blocker` 为 **打开** 时，合约不能达到 `accepted`。 |
### 三个门控
1. **`seal_contract`**（`drafting → criteria_sealed`）- 拒绝密封，除非至少有一个拒绝测试，至少有一个第二实例测试，每个不变式都有探针规范，并且绑定的验收者 **不是** 运行绑定任务的参与者。不变式在密封后冻结；更改它们的唯一方法是 `reopen_contract`（一个大声重置，清除密封和之前的探针结果）。
2. **`evaluate_contract`** - 目标门控和自我修复循环驱动程序。它不需要验收者，因此循环自我驱动。如果所有必需的不变式的最新结果均为 `passed`，并且没有打开的阻塞器 → `awaiting_acceptor`。否则，它会增加尝试次数并为外部调度程序/运行者发出绑定修复任务；由 `max_repair_attempts` 和无进展刹车（失败集必须严格缩小）限制，之后它升级到 `awaiting_human`。绑定运行者不能在其自己的合约上调用 `evaluate`/`accept`。
3. **`accept_contract`**（`awaiting_acceptor → accepted`）- 只有独立的验收者才能签字，证明不变式集充分涵盖目标（绿色已经是客观事实）。`reject_contract`将其发送到 `awaiting_human`。
```
drafting ──seal──▶ criteria_sealed ──(report_verification)──▶ verifying
│
evaluate（目标门控）
┌─────────────────────────────┼──────────────────────────┐
所有必需绿色 部分失败/开放阻塞器 │
│ 进入修复循环（有界）
awaiting_acceptor │
│ repair_attempt > max OR
accept / reject 无进展 → awaiting_human
│
accepted / awaiting_human
```
门控逻辑完全存在于存储层（`store.py`）- 没有提示或客户端可以绕过它。
## 仪表盘（本地管理控制台）
本地、单页管理仪表盘，位于同一 SQLite 内存之上。小型标准库 HTTP 服务器提供 Svelte/Vite 构建的静态 SPA 和 JSON API。读取 API 以 `mode=ro` + `query_only` 打开数据库，并失败而不是创建缺少的数据库。唯一的写入操作是 **存档工作区**，它通过 `POST /api/workspaces/<id>/archive` 将 `workspaces.status` 更新为 `archived`；它永远不会删除任务、运行 shell、部署或推送。
```bash
COORDINATION_MEMORY_DB=/absolute/path/coordination.sqlite3 \
comem dashboard --host 127.0.0.1 --port 8765
```
打开 `http://127.0.0.1:8765/`。它显示了一个以板子为首的 **概览**（任务通道 + 验收合约部分，带有统计条和 "需要关注" / "正在进行" 卡片），一个 **工作区** 管理页面，带有工作区和智能体团队状态计数，工作区详情页面，带有团队和任务，以及合约（门控步进器，不变式，偏差，修复循环/事件时间线，绑定任务），任务或运行 - 每个都带有可读的摘要和折叠的 "原始 JSON" 面板。团队切换器和 5 秒自动刷新（仅概览，暂停时选择文本或隐藏选项卡）位于头部，头部显示构建哈希，以便您可以知道 UI 何时更改。相同的数据以 JSON 形式提供：`/api/workspaces`，`/api/workspaces/<id>`，`POST /api/workspaces/<id>/archive`，`/api/board`，`/api/governance`，`/api/contracts`（+ `/api/contracts/<id>`），`/api/assignments/<id>`，`/api/runs/<id>`，`/api/teams`，`/api/reviews`，`/api/version`。
## 已接受的投影（导出）
`get_snapshot` 返回从存储中导出的已接受读模型 - 只有集成者接受的事件。`export_git_projection` 写入（仅限集成者）到您选择的文件夹：
```json
{ "output_dir": "/tmp/coordination-projection", "actor_role": "integrator" }
```
生成：
```text
/tmp/coordination-projection/coordination-memory/snapshots/accepted-state.json
/tmp/coordination-projection/coordination-memory/events/accepted-events.md
```
在将其提交到任何地方之前，请审查导出。工具只会写入您传递的目录；它永远不会覆盖其他文件。
## 安全边界
- 不读取或提交 `.env` 文件；不存储机密、令牌、密码或私钥。合约 `probe_spec`、验证 `evidence` 和所有元数据 **仅持有引用**（路径、提交、哈希）。
- 不执行部署、shell 命令或版本控制推送。验收合约修复循环仅发出任务记录；执行保留在您自己的（外部授权）调度程序/运行者中。
- 仪表盘读取 API 为只读。仪表盘的唯一写入操作是 **存档工作区**，一个软工作区状态更新；它不删除数据、执行命令、部署或推送。
## 开发
```bash
uv sync
uv run pytest -q
uv run ruff check src tests # 校验
uv run ruff format --check src tests
uv run mypy src # 类型检查
uv run pre-commit install # 可选：运行校验/格式化提交
npm test # 前端单元测试
npm run build # 重建 Svelte 仪表盘静态资产
```
更多文档：[docs/](docs/)（快速入门、概念/治理、工具参考、示例）。查看 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解变更必须保留的不变式，以及 [CHANGELOG.md](CHANGELOG.md) 中的发布说明。
## 许可证
[MIT](LICENSE)。
