For agents that share files, plans, and memory
It shows up anywhere two sessions, subagents, or processes share a file, a plan, or a store. One reads v1. Another commits v2. The first writes back, and v2 is gone, with no error raised. agent-coherence denies that stale write — through CoherentVolume for shared files and write_cas for store keys — makes the writer re-read, and hands the loser a typed conflict to retry. On a LangGraph store, drop-in CCSStore covers the read side: a peer's commit invalidates your cached view before you act on it. The lost update never lands silently, sequential or concurrent, on a single host. Drop it into LangGraph, CrewAI, AutoGen, or any custom orchestrator, and it behaves the same across model providers (Anthropic, OpenAI, Google, Mistral, open-source).
Why it reads as a model problem. Your system keeps two records of what happened: the one your infrastructure can verify — which version each agent held, what actually committed — and the one the model narrates, "task complete". They only disagree when something went wrong, and the narrated one is what you read. agent-coherence is the verified record for the state your agents share. It knows which version each agent read, and refuses a write built on a view that already moved.
Three ways in, same protocol underneath.
Python fleets. A drop-in store for LangGraph, adapters for CrewAI and AutoGen, or
CoherentVolumefor plain files shared across processes.Claude Code. The plugin keeps parallel sessions from acting on a
plan.mdorCLAUDE.mdanother session already moved.Any MCP client. The stale-write-guard-fs server exposes guarded reads, writes, and an effect gate as six tools.
$ pip install agent-coherence
Python 3.11+. See the deny happen in 30 seconds — offline, no API keys: python -m examples.coherent_volume.main
If your agents only read from sources you don't control, you need a freshness pipeline. If your agents write to each other's state, you need a coherence protocol. They're different problems — and the wrong tool for one is silent failure in the other.
Read-side freshness
The world writes (commits, Slack, docs, tickets); agents read. You need an index pipeline that keeps the corpus current as sources change — incremental embeddings, knowledge graphs, retrieval.
Write-side coherence
The agents write — they collaborate on shared plans, edit specs, mutate memory, hand off scratchpads. You need a coherence protocol that detects stale reads and enforces single-writer ordering when one agent commits.
Failure modes prevented: stale-read → lost update · silent overwrite · shared memory pollution — and the cascading errors that follow.
Both layers are needed in a real production system. agent-coherence focuses on the write side. And if nothing is actually shared — each agent in its own worktree, per-user namespaces, read-only RAG, an append-only store, or a single writer — you don't need this.
MESI cache coherence — the protocol every modern CPU uses to share memory — adapted for LLM agents sharing artifacts.
Each shared artifact is cached locally per agent. Reads serve from the local cache when valid — no re-broadcast.
Writes commit to a coordinator, which sends ~12-token invalidation signals instead of rebroadcasting the full artifact.
Single-writer-multiple-reader per artifact with bounded staleness. Peers re-fetch on next read, guaranteed.
Five synchronization strategies ship out of the box: lazy (default), eager, lease (TTL-based), access_count, and broadcast — pick the one matching your workload's read/write ratio and staleness tolerance.
Same library, same protocol, same behavior — regardless of orchestrator or model provider.
# LangGraph drop-in — read-side coherence in one import change from langgraph.store.memory import InMemoryStore # before from ccs.adapters import CCSStore # after store = CCSStore(strategy="lazy") graph = builder.compile(store=store)
"Subagent output to a filesystem to minimize the 'game of telephone' [...] implement artifact systems where specialized agents can create outputs that persist independently."
— Anthropic Engineering, multi-agent research system (Appendix, June 2025). CCSStore is exactly that pattern — plus coherence semantics so subagents know when their cached view is stale.
Provider-neutral: same behavior with Anthropic, OpenAI, Google, Mistral, or open-source models. The protocol operates on artifacts, not model responses.
Agents and a pipeline writing the same memory?
See the RAG & shared-memory page →
Building coding sub-agents?
See the recorded planner-executor demo →
Running Claude Code with shared CLAUDE.md / plan.md?
See the agent-coherence plugin →
Agents, sessions, and scripts sharing plain files on disk?
See the coherent workspace →
Reproducible in CI with GenericFakeChatModel — no live LLM API calls. Run them yourself: make benchmark.
| Workload | Agents | Reads : Writes | Hit rate | Savings |
|---|---|---|---|---|
| Planning (read-heavy) | 4 | 12:1 | 75% | 69% |
| Code review (moderate) | 3 | 8:3 | 60% | 47% |
| High-churn (write-heavy) | 4 | 8:4 | 50% | 29% |
AtomicPublish.tla parses and semantically validates but is held out pending a bounded encoding that converges in the CI budgetccs-diagnose — zero-network stale-read detector for existing graphsStaleView, recovered via reacquire()stale-write-guard-fs — a stdio MCP server (pip install "agent-coherence[mcp]") exposing the coordinator to any MCP client over six tools · listed on the MCP Registry as io.github.cohexa-ai/stale-write-guard-fsatomic_publish — a set of files lands all-or-nothing at the coordinator commit (single host; not effect rollback)gate() holds a deploy, PR, or charge when its input moved or the grant it was read under was reclaimed (v0.14.0 pairs the version with the ownership generation) — orders effects, never rolls one backWorkspaceVersioner — checkpoint a mixed file + S3 workspace as a manifest of native version pointers and restore it with per-member honesty (restorable / unpinned / forward-only; artifacts come back, effects don't)Anthropic's engineering team, after shipping their multi-agent Research system to production, named state consistency as one of three challenges blocking async multi-agent execution at scale. agent-coherence is the protocol that addresses it.
Architecturally, this is the layer QuantumBlack/McKinsey describes as agentic shared services — the protocol-first, composable substrate between agent runtimes and enterprise data. agent-coherence is the state-consistency primitive that lives there.
Agentic systems & runtimes
Interfaces & agentic orchestration
Agentic shared servicesagent-coherence is here
In-house systems & external data
Layer naming follows "Creating a future-proof enterprise agentic platform architecture" (QuantumBlack/McKinsey). agent-coherence is composable by design: it slots alongside your existing evaluations, observability, and memory layers — same library across LangGraph, CrewAI, AutoGen, and custom runtimes, vendor-neutral across Anthropic, OpenAI, Google, Mistral, and open-source models. Multi-vendor workflows, minimum lock-in.
The audience signal is consistent: 32% of agent teams cite quality — "hallucinations and consistency of outputs" — as the #1 production blocker. LangChain, State of Agent Engineering 2026.
Common questions about stale-read detection and multi-agent coherence across LangGraph, CrewAI, AutoGen, and custom orchestrators.
When one agent reads an artifact — a plan, a document, a result — that another agent has already updated, the reader gets a stale copy. If the reader then writes back, it overwrites the current version with logic that was based on stale state. MLflow's multi-agent observability team calls this shared memory pollution: one agent's hallucination becomes a "fact" subsequent agents reason from, producing cascading errors that compound across reasoning steps. Trace-only tools can see the calls but not the staleness; agent-coherence detects the exact moment of divergence and denies the stale write before it lands.
Because an agent system keeps two records of what happened. One your infrastructure can verify — which version each agent held, what actually committed, what was refused. One the model narrates — "task complete", "the plan is updated", "I applied the change". They agree right up until an agent acts on a version that moved underneath it, and the narrated record is the one you read. A lost update raises no exception, so the run looks green and the bug gets debugged as a model problem.
agent-coherence is the verified record for the state your agents share: it tracks which version each agent read and refuses a write built on a view that already moved, so the failure surfaces as a typed refusal instead of a silent overwrite. 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.
LangSmith and Braintrust show you what your agents did. agent-coherence shows you when one of them was wrong because it read stale state from another. The difference is structural — we track per-agent ownership of shared artifacts (MESI states), so the tool can flag a read that returned an outdated copy. Trace-only tools cannot detect this because they lack the state model.
No. Drop-in adapters ship for LangGraph (CCSStore), CrewAI, AutoGen, and any custom orchestrator via CoherenceAdapterCore. The protocol operates on artifacts, not model responses, so it works the same with Anthropic, OpenAI, Google, Mistral, AWS Bedrock, Azure OpenAI, and open-source models.
The protocol enforces single-writer ordering. One agent reads, a peer commits a newer version, the first then writes — the stale writer is denied (its cache went INVALID) and must re-read, so the lost update is prevented, not silently applied. On a single host this holds for both sequential and concurrent writers: the concurrent same-key race is resolved by an optimistic commit-CAS plus fencing — the loser gets a typed conflict and retries, never a silent drop. Coordinating writers across multiple hosts is on the roadmap and an active co-design — if that is your shape, open a GitHub Discussion or email us. For workloads where concurrent writes are semantically composable, CRDTs are the right tool — see the Why Coherence Matters doc for the layered model.
69% token reduction on read-heavy workloads (12:1 read/write ratio), 47% on moderate (8:3), 29% on write-heavy (8:4). The lever is invalidation signals (~12 tokens) replacing full-artifact rebroadcasts. Run the benchmarks yourself: pip install "agent-coherence[langgraph,benchmark]" then make benchmark. CI uses GenericFakeChatModel — no live API calls required.
Apache-2.0, on PyPI, alpha (APIs may change before v1.0), safety invariants model-checked with TLA+/TLC across nine specs that run in CI on every push, each carrying a documented mutant that must fail (AtomicPublish.tla parses and semantically validates but is held out pending a bounded encoding that converges in the CI budget), PyPI Trusted Publishers with PEP 740 attestations and CycloneDX SBOM published with every release. The crash-recovery sweep is on by default and reclaims stale grants when agents OOM-kill or livelock. ccs-diagnose runs as a zero-network static analyzer on existing graphs before adoption.
15-minute call. We'll look at your graph and tell you honestly whether this fits — and where it doesn't. (It's cheaper on tokens too.)