For agents that share files, plans, and memory
Apache-2.0 · Open source · PyPI · v0.12.0It 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).
"This asynchronicity adds challenges in result coordination, state consistency, and error propagation across the subagents."
— Anthropic Engineering, How we built our multi-agent research system (June 2025), on what blocks async multi-agent execution at scale.
Anthropic named the problem. agent-coherence is the protocol that addresses it.
$ pip install "agent-coherence[langgraph]"
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 →
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% |
ccs-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 five 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 has moved — orders effects, never rolls one backAnthropic'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.
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, v0.12.0 (alpha — APIs may change before v1.0), seven safety invariants model-checked with TLA+/TLC across six specs that run in CI on every push, 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.)