Coordination Memory MCP

<!-- mcp-name: io.github.yanqiw/comem -->

Append-only coordination memory for multi-agent (and agent + human) work, exposed as a local Model Context Protocol (MCP) server backed by SQLite — plus a local web management dashboard and goal-level acceptance contracts.

It records who owns which task, run liveness, human interventions, handoff evidence, and integrator review decisions. Only an integrator can promote work into the accepted ledger, which you can export as a durable, auditable projection (for example, committed into Git).

Design stance: the MCP is the live coordination layer; durable accepted truth lives in whatever you project to. It is local-first (SQLite + stdio), and it never deploys, never reads secrets, and never executes shell commands.

Why

When several agents (or agents and people) push on the same body of work, two things go wrong: they overwrite each other, and "I'm done" gets confused with "this was accepted." Coordination Memory gives you:

• Assignment claims with leases so two actors don't clobber the same task.
• A hard distinction between an agent reporting completed_gate_passed and an integrator deciding integrator_accepted. Proposals are not truth.
• An integrator-owned accepted projection you review before archiving.
• Acceptance contracts that make "self-certified done" structurally impossible for goal-level outcomes (see below).

Good fits: multiple agents on separate worktrees advancing one effort; needing a review gate before something counts as accepted; wanting a replayable audit trail of coordination decisions.

Not a fit: as your only long-term source of truth; as a place to store .env files, tokens, passwords, or credential-bearing logs.

Launch resources

• 90-second demo script — a short walkthrough for showing leases, handoff evidence, integrator acceptance, and the dashboard.
• Launch post draft — copy for announcing the project without positioning it as generic memory or RAG.
• OSS launch checklist — release, GitHub metadata, MCP Registry, and directory-submission steps.

Install

Requires Python ≥ 3.11.

Install the single comem command with uv or pipx after the package is published to PyPI:

uv tool install coordination-memory-mcp   # or: pipx install coordination-memory-mcp
comem --help

Or run it without installing (the package name and command differ, so pass --from):

uvx --from coordination-memory-mcp comem --help

From source

If the PyPI page is not live yet, or you want to run your own changes, install the comem command straight from a checkout:

git clone https://github.com/yanqiw/comem
cd coordination-memory-mcp
uv tool install .                  # or: pipx install .
comem --version

This is a snapshot install — re-run it after editing the source to pick up changes:

uv tool install . --reinstall              # rebuild from current source
uv tool install . --editable --reinstall   # or install editable: changes apply live
uv tool uninstall coordination-memory-mcp  # remove it

The command exposes four subcommands:

• comem serve — the stdio MCP server.
• comem dashboard — the local web management console.
• comem init — scaffold agent-onboarding files into a repo.
• comem loop — run the local-only scheduler for Codex agent conversations.

For local development, clone and uv sync, then prefix commands with uv run.

Quickstart

Run the MCP server

comem serve

This starts a stdio MCP server (normally launched by an MCP client). It opens no HTTP port and prints no interactive CLI.

The database defaults to ./.coordination-memory/coordination.sqlite3. Override it with COORDINATION_MEMORY_DB. When several agents/worktrees collaborate, point all of them at one absolute path outside every worktree, or each worktree gets its own SQLite copy and the shared memory forks:

COORDINATION_MEMORY_DB=/absolute/path/coordination.sqlite3 \
  comem serve

Do not commit the SQLite database to Git.

Configure an MCP client

Client config locations differ, but with the command installed the server entry should look like:

{
  "mcpServers": {
    "coordination-memory": {
      "command": "comem",
      "args": ["serve"],
      "env": {
        "COORDINATION_MEMORY_DB": "/absolute/path/coordination.sqlite3"
      }
    }
  }
}

Set up your agent

comem init scaffolds onboarding files so your coding agents know the protocol, then prints this MCP config snippet:

comem init            # all tools, current directory
comem init --tools claude,cursor --dir ./my-repo

It writes a canonical Coordination Memory protocol section into AGENTS.md (idempotently, between markers) and thin per-tool adapters that point to it:

Tool	File written
Codex, OpenCode	AGENTS.md (read directly)
Claude Code	.claude/skills/coordination-memory/SKILL.md
Cursor	.cursor/rules/coordination-memory.mdc
GitHub Copilot	.github/copilot-instructions.md

Re-running init updates the AGENTS.md section in place (no duplication). Edit the protocol once in AGENTS.md; the adapters defer to it.

Local loop

comem loop is the local-only scheduler for first-class Codex agent conversations. The initial release supports --adapter fake for deterministic testing and a guarded --adapter codex-app-server capability probe for future local Codex app-server integration.

Dry-run scheduling:

comem loop --team default --adapter fake --dry-run --once

Fake local dispatch:

comem loop --team default --adapter fake --once

Loop-managed assignments should carry metadata.session_bind.target_actor_id so the scheduler knows the intended worker before any run exists. The actual Codex thread binding is recorded on the run after claim/start. Project design and plan context must remain in Markdown files; assignments should reference those files through metadata context_refs.

Concepts

The store is six core tables:

• workspace → team → assignment → run → event, plus actors.
• An assignment is a unit of work. Claiming one starts a run and takes a lease. Events are the append-only log (evidence, handoffs, reviews, …).
• Actors act in a role: integrator, agent, or human.
• Mutating writes use optimistic concurrency: each carries the current base_revision and bumps the revision.

Event statuses an agent may submit: proposed, observed, completed_gate_passed, completed_gate_failed. Decision statuses are integrator-only: integrator_accepted, integrator_rejected, needs_fix. completed_gate_passed is not accepted truth — only an integrator review decision produces accepted state.

Tools

Coordination

Tool	Role	Purpose
register_actor	any	register/refresh an actor profile
register_workspace	any	create/refresh a workspace record (idempotent)
create_team	any	create/refresh a team (auto-creates its workspace)
create_assignment	integrator	create a task (optional workspace/team/paths/criteria)
cancel_assignment / supersede_assignment	integrator	void / retire a task (releases any lease)
claim_assignment	agent	claim a lease; records run/session/worktree metadata
heartbeat_run	agent	report run liveness
request_intervention / respond_intervention	agent / human	move a run to/from an awaiting-human lane
append_event / submit_handoff	agent	append evidence / submit a reviewable handoff
list_pending_reviews	any	reviewable events with no decision yet
review_event / accept_event / reject_event	integrator	record a review decision
get_team_board / get_assignment_detail / get_run_detail	any	read models
get_snapshot / export_git_projection	integrator	accepted projection (see below)

Acceptance contracts

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.

Mutating tools take a base_revision and reject stale writes. Run/intervention tools only change local lanes and the event timeline; they never execute commands, resume threads, or touch files.

Acceptance contracts (goal-level governance)

An acceptance contract is a first-class object that sits above assignments and defines machine-checkable, non-self-certifiable acceptance criteria for a goal-level outcome. It is a structural protection layer whose purpose is to make "the implementer declares it done" impossible.

Data model

Table	Role
acceptance_contracts	the contract: goal_statement, status (state machine), revision (optimistic concurrency), acceptor_actor_id (independent acceptor), max_repair_attempts/repair_attempt (loop bounds), last_failing_keys_json (no-progress brake)
contract_invariants	one machine-checkable predicate per row: probe_kind (command/http/sql/file_assert/artifact_present), probe_spec_json (references only — no secrets), is_negative (a deny test), is_second_instance (a second-tenant/second-instance test). Frozen after seal.
contract_verifications	append-only probe results: outcome (passed/failed/error), evidence_json (log path / commit / response hash — references only). "Pass or not" is decided by the latest probe result; a runner cannot mark a predicate passed by fiat.
contract_deviations	a deviation/shortcut register: disposition is required (acceptable_forever/acceptable_this_phase/blocker). While any blocker is open, the contract cannot reach accepted.

Three gates

1. seal_contract (drafting → criteria_sealed) — refuses to seal unless there is at least one deny test, at least one second-instance test, every invariant has a probe spec, and the bound acceptor is not an actor that ran a bound assignment. Invariants freeze after seal; the only way to change them is reopen_contract (a loud reset that clears the seal and prior probe results).
2. evaluate_contract — the objective gate and self-healing loop driver. It needs no acceptor, so the loop self-drives. If every required invariant's latest result is passed and no blocker is open → awaiting_acceptor. Otherwise it bumps the attempt and emits a bound repair assignment for an external scheduler/runner to pick up; bounded by max_repair_attempts and a no-progress brake (failing set must strictly shrink), after which it escalates to awaiting_human. A bound runner cannot call evaluate/accept on its own contract.
3. accept_contract (awaiting_acceptor → accepted) — only the independent acceptor may sign off, certifying the invariant set adequately covers the goal (green is already objective fact). reject_contract sends it to awaiting_human.

drafting ──seal──▶ criteria_sealed ──(report_verification)──▶ verifying
                                                                  │
                                                          evaluate (objective gate)
                                    ┌─────────────────────────────┼──────────────────────────┐
                             all required green             some failed / open blocker
                             AND no open blocker                       │
                                    │                       enter repair loop (bounded)
                            awaiting_acceptor                          │
                                    │                         repair_attempt > max OR
                              accept / reject                   no-progress → awaiting_human
                                    │
                             accepted / awaiting_human

The gate logic lives entirely in the store layer (store.py) — there is no prompt or client that can bypass it.

Dashboard (local management console)

A local, single-page management dashboard over the same SQLite memory. A small stdlib HTTP server serves the Svelte/Vite-built static SPA plus JSON APIs. Read APIs open the DB with mode=ro + query_only and fail rather than creating a missing DB. The only write action is Archive workspace, which soft-updates workspaces.status to archived through POST /api/workspaces/<id>/archive; it never deletes tasks, runs shell, deploys, or pushes.

COORDINATION_MEMORY_DB=/absolute/path/coordination.sqlite3 \
  comem dashboard --host 127.0.0.1 --port 8765

Open http://127.0.0.1:8765/. It shows a board-first Overview (assignment lanes + an Acceptance Contracts section with a stat strip and "needs attention" / "in flight" cards), a Workspaces management page with workspace and agent-team status counts, workspace detail pages with teams and assignments, and drill-downs for a contract (gate stepper, invariants, deviations, repair-loop/event timeline, bound assignments), an assignment, or a run — each a readable summary plus a collapsed "Raw JSON" panel. A team switcher and a 5s auto-refresh (overview only, paused while you select text or the tab is hidden) live in the header, and the header shows a build hash so you can tell when the UI changed. The same data is available as 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.

Accepted projection (export)

get_snapshot returns the accepted read model derived from the store — only events an integrator accepted. export_git_projection writes (integrator-only) to a directory you choose:

{ "output_dir": "/tmp/coordination-projection", "actor_role": "integrator" }

produces:

/tmp/coordination-projection/coordination-memory/snapshots/accepted-state.json
/tmp/coordination-projection/coordination-memory/events/accepted-events.md

Review the export before committing it anywhere. The tool writes only to the directory you pass; it never overwrites other files.

Security boundaries

• Does not read or commit .env files; does not store secrets, tokens, passwords, or private keys. Contract probe_spec, verification evidence, and all metadata hold references only (paths, commits, hashes).
• Does not execute deployments, shell commands, or version-control pushes. The acceptance-contract repair loop only emits an assignment record; execution stays in your own (externally authorized) scheduler/runner.
• Dashboard read APIs are read-only. The dashboard's only write action is Archive workspace, a soft workspace status update; it does not delete data, execute commands, deploy, or push.

Development

uv sync
uv run pytest -q
uv run ruff check src tests        # lint
uv run ruff format --check src tests
uv run mypy src                    # type check
uv run pre-commit install          # optional: run lint/format on commit
npm test                           # frontend unit tests
npm run build                      # rebuild Svelte dashboard static assets

More docs: docs/ (quickstart, concepts/governance, tool reference, examples). See CONTRIBUTING.md for the invariants a change must preserve, and CHANGELOG.md for release notes.

License

MIT.