Cohexa-ai/agent-coherence

**agent-coherence stops one agent from silently clobbering another's work on a shared plan.md, store key, or memory.json — a vendor-neutral MESI + optimistic-concurrency coordinator for agent state on a single host, with the safety invariants machine-checked in TLA+.**
Two agents share an artifact — a plan.md, a store key, a memory.json. One reads it and works; meanwhile a peer commits a newer version; the first writes back anyway. Last write wins, the peer's work is silently gone, nothing errors, and every downstream decision builds on the wrong version.
**Why it goes unnoticed.** An agent system keeps two records of what happened: the one your infrastructure can verify — which version each agent held, what actually committed, what was refused — and the one the model narrates, *"task complete", "the plan is updated"*. They agree until an agent acts on a version that moved underneath it, and the narrated record is the one you read. That is why a lost update looks like a clean run and gets debugged as a model problem. agent-coherence is the verified record for the state your agents share. (It does not verify what an agent did in the outside world — a sent email, a fired webhook — that stays your outbox and idempotency layer's job.) agent-coherence turns that silent clobber into a loud, typed refusal: MESI-style ownership and invalidation over shared artifacts, optimistic commit-CAS for concurrent writers, and a read-generation fence for crash-reclaimed ones — a stale write is denied or returned as a retryable conflict, never silently applied. Same library, same protocol, across LangGraph, CrewAI, AutoGen, the OpenAI Agents SDK, plain files shared across processes (CoherentVolume), any MCP client (the stale-write-guard-fs server, via the mcp extra), and any custom orchestrator. Same behavior regardless of which model provider (Anthropic, OpenAI, Google, Mistral, open-source) the agents talk to.
mcp-name: io.github.cohexa-ai/stale-write-guard-fs
store.get(), store.put(), store.search() keep working unchanged. CCSStore adds **read-side** coherence: a peer's commit invalidates your cached view, so your next read is a fresh miss. It does **not** deny a stale write-back — put is not version-CAS; for write-side lost-update prevention, route writes through CoherentVolume or write_cas (below).
> The one-import swap assumes your store namespaces carry the agent identity in namespace[0] — a (user_id, "memories") shape would merge users onto one shared artifact. See the namespace convention.
agent-coherence-replay — invariant-replay for any CoherenceAdapterCore-mediated agent system. LangGraph capture verified in v1 via CCSStore.record_to(path); CrewAI / AutoGen wired through the same seam but unverified — file an issue if it breaks.
What it guarantees
Each row is a safety invariant model-checked with TLA+/TLC. make tla-check runs all nine specs. CI runs them as three parallel jobs on every pull request that changes a TLA+ input (the specs and their configs, the Makefile, the workflows, and the scripts that decide and judge the run), and on every run outside a pull request. Every spec carries a documented mutant that must fail — the invariants are load-bearing, not decorative.
| The silent failure | What happens instead | Mechanism | Invariant |
|---|---|---|---|
| **Stale-read overwrite** — an agent acts on an old snapshot and writes over a newer version (two sessions, one plan.md) | the write is **denied fail-closed**; the writer must reacquire() and read the current version | MESI single-writer ownership + invalidation | SingleWriter, MonotonicVersion |
| **Concurrent lost update** — two writers hit the same key and both "succeed" | exactly one wins; the loser gets a **typed conflict + bounded retry**, never a silent drop | optimistic commit-CAS (write_cas) | NoLostUpdate |
| **Reclaim-zombie write** — a stalled writer is reclaimed by crash recovery, wakes later, and lands its stale commit; the version never moved, so a version check passes | the commit is **rejected** with a typed stale_read_generation conflict | read-generation fence — reclamation bumps the artifact's ownership epoch, checked atomically at commit | NoStaleApply |
| **Zombie revoke** — an invalidation is minted, and by the time it is applied the agent it names has been reclaimed, re-acquired and re-read; applying it now revokes a grant issued *after* the signal, and the target's version never moved, so a version check sees nothing | the invalidation is **dropped as obsolete** — the target is not behind what it announces, so the grant survives | a peer-issued revoke is pinned to the target's last observed version, and every revoke-class ending of a write claim — a sweep reclaim or a release — moves the ownership epoch (a peer's write-*acquire* moves neither comparand; the effect gate fences that by grant state instead) | NoZombieRevoke, NoSilentRevoke |