SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentsagent-coherence

agent-coherence

Coherence guard for shared files: when two agents write the same file, the stale writer is denied instead of overwriting, then reacquires and retries.

Open website

About this tool

Purpose

agent-coherence is a coordination layer for multi-agent collaboration. The core problem it solves is "lost updates under shared state": when multiple agents share the same artifact (such as plan.md, a store key, or memory.json), one agent writes back based on an old version, silently overwriting a newer version that another agent has already committed. This kind of problem usually does not raise an error, and the model will even narrate it as "task completed" or "plan updated," causing downstream decisions to be based on the wrong version, and it is often misdiagnosed as a model problem.

This library turns this kind of silent overwrite into an explicit, retryable typed rejection: stale writes are denied or return a retryable conflict instead of being silently applied.

Main Capabilities

  • MESI-style ownership and invalidation: Performs ownership and invalidation management for shared artifacts, combined with optimistic-commit commit-CAS to handle concurrent writers.
  • Read-generation fence: Used for post-crash reclamation scenarios. Reclaiming a stalled grant increments the artifact's ownership epoch, so that a reclaimed writer will be rejected at commit time even if the version has not changed.
  • Two write disciplines: The pessimistic approach (acquire EXCLUSIVE and then commit; if the view is stale it is rejected and reacquire() is required) and the optimistic approach (write_cas: read, compute, commit-CAS; the losing competitor receives a typed conflict and bounded retries).
  • Five synchronization strategies: lazy (default), eager, lease (TTL-based), access_count, broadcast, chosen according to the read/write ratio and refresh aggressiveness.
  • Read-side consistency: CCSStore serves as a replacement for langgraph.store. A peer commit invalidates the user's cached view, and the next read re-fetches it. It does not reject stale write-backs (put is not a version CAS); write-side lost-update protection must be routed through CoherentVolume or write_cas.
  • Framework adapters: ccs.adapters provides integrations for LangGraph, CrewAI, and AutoGen (about 100 lines each), as well as an experimental OpenAI Agents SDK adapter.
  • CoherentVolume : Data-plane device (out-of-process coordinator client), bringing the same guarantees to ordinary files on disk without a framework; interacts with the local coordinator via SQLite-WAL, and the coordinator stores only MESI state, content hashes, and versions.
  • MCP server: stale-write-guard-fs, as a stdio server, exposes the same guarantees to any MCP client through ten swg_* tools.
  • Other components: effect order gate gate(), multi-artifact snapshot sessions (tear-free reads), atomic multi-file publish atomic_publish, directed authorization handoff, ccs-diagnose CLI, conflict outcome counters, Claude Code plugin, external edit guard, etc.
  • Formal verification: nine TLA+/TLC specifications run in CI, and each specification has a mutant that must fail, ensuring the invariants are not decorative.

Usage

  • Import as a library: use modules such as ccs.core (protocol), ccs.coordinator (coordinator), ccs.strategies (synchronization strategies), and ccs.adapters (framework adaptation). The protocol and coordinator do not depend on a framework.
  • The store API (store.get(), store.put(), store.search()) can continue to be used; CCSStore adds read-side consistency.
  • Single-import replacement assumes the store namespace carries agent identity in namespace[0] (for example, a (user_id, "memories") shape will merge users onto the same shared artifact).
  • Event bus: currently provides an in-memory/in-process InMemoryEventBus; network-oriented multi-host transports (Redis, Kafka, NATS, gRPC) are on the roadmap and will be advanced as needed.
  • Runnable demo: python -m examples.coherent_volume.main, offline, no keys required, first reproduces the lost update from the documentation, then shows how to prevent it.
  • Cost reproduction: python tools/run_cost_sweep.py; the preregistered metrics and conclusions are in benchmarks/cost_preregistration.md (PASS at n=50, crossover point r≈0.31), v0.9.3 released.
  • TLA check: make tla-check runs all nine specifications.

Applicable scenarios

  • Collaboration scenarios where multiple agents share the same file, storage key, or memory (plan.md, store key, memory.json).
  • RAG corpora and agent memory: both are shared mutable state; two agents read the same record v1, one writes v2, and if the other still writes back based on v1 it will overwrite v2. CCSStore keeps readers up to date (read-side consistency), and write-side protection is provided via CoherentVolume or write_cas.
  • Scenarios where ordinary files are shared across processes (CoherentVolume).
  • Scenarios where any MCP client needs stale-write protection (stale-write-guard-fs).
  • Scenarios requiring invariant replay for any agent system mediated by CoherenceAdapterCore (agent-coherence-replay; LangGraph collection has been verified in v1 via CCSStore.record_to(path); CrewAI/AutoGen are connected to the same seam but unverified).
  • Scenarios requiring capabilities such as atomic multi-file publishing, consistent snapshots of multiple artifacts, effect ordering gates, and directed authorization handoff.

Limitations

  • Guarantees hold only for writes that go through the coordinator, and are limited to a single coordinator and a single host.
  • There is a public gap (#248): when the peer's write_cas_at has committed but the bytes have not yet landed on disk, an ordinary write() may be lost; the specific conditions involve the write volume not holding an active view of that file, having read only within the window, or a running write_cas / write_cas_at ending with ViewWedged.
  • Cross-host fencing is on the roadmap, advanced on demand, and not yet provided.
  • Edits that bypass the coordinator (a human in an editor, formatters, regeneration scripts) are caught by content hash checks at the read()/write() boundary; the bulk CAS path boundary is narrower.
  • Automatically watching for changes from external sources that do not go through the coordinator (manual file edits, out-of-band reindexing) belongs to the source-watcher scenario, is on the roadmap, advanced on demand, and is currently not provided.
  • It does not verify that the agentbehaves in the external world (such as sending emails or triggering webhooks); that is the responsibility of the outbox and idempotency layers.
  • Single-import replacement has namespace convention requirements.
  • Some capabilities such as the effect gate gate() are exposed via MCP (swg_gate) and HTTP (POST /hooks/effect-fence), and are provided only by the Python coordinator.
  • The pre-registered benchmark metric re-fetches-avoided is a proxy metric and a pattern map, not a token/dollar bill.
  • Some unverified capabilities (such as CrewAI / AutoGen replay) are explicitly marked as unverified.

Information not provided

  • Specific charging methods and prices are not provided in the materials.
  • Specific installation commands (pip/uv, etc.) are not given as a complete list in the materials.
  • The list of compatible model providers only mentions Anthropic, OpenAI, Google, Mistral, and that open-source models are provider-agnostic; a complete support matrix is not listed.
  • Platform limitations (operating systems, etc.) are not explicitly stated in the materials.

Related tools

Browse category