agent-coherence 0.8.3

Token optimization layer for multi-agent LangGraph systems — cut shared-artifact token costs via MESI cache coherence, one import change

agent-coherence

The coherence layer for multi-agent systems — vendor-neutral, framework-agnostic.

When two agents share state, one of them is usually reading a stale copy. agent-coherence makes that visible — and serves the fresh version on the next read instead of rebroadcasting the full artifact every turn. Same library, same protocol, across LangGraph, CrewAI, AutoGen, and any custom orchestrator. Same behavior regardless of which model provider (Anthropic, OpenAI, Google, Mistral, open-source) the agents talk to.

pip install "agent-coherence[langgraph]"   # LangGraph drop-in
pip install "agent-coherence[crewai]"      # CrewAI adapter
pip install "agent-coherence[diagnose]"    # ccs-diagnose CLI
pip install "agent-coherence[all]"         # everything

# Before
from langgraph.store.memory import InMemoryStore
store = InMemoryStore()

# After — one import change, no node code changes
from ccs.adapters import CCSStore
store = CCSStore(strategy="lazy")

store.get(), store.put(), store.search() keep working unchanged. Savings show up immediately on any workload where multiple agents read the same artifact more often than they write it.

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.

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%

Measured on real LangGraph graphs; see docs/reproduce.md and the user guide.

---

• 📖 User guide — installation, namespace convention, strategies, observability, telemetry, examples, full API reference
• 🩺 ccs-diagnose CLI — find divergent reads in your existing LangGraph graph without changing any code
• 🔍 Why coherence matters — the gap across LangGraph, CrewAI, AutoGen, and Claude Agent SDK
• 🔐 Security & supply chain — kill switches, hash-pinned install, attestation verification, threat model
• 📜 Changelog — version history
• 📄 Paper on arXiv (2603.15183) — formal protocol, TLA+ verification, simulation results

How it works

Each shared artifact is cached locally per agent and reads serve from the local cache when that copy is fresh. Writes commit to a coordinator, which sends lightweight invalidation signals (~12 tokens) to peers so the next read fetches the new version instead of rebroadcasting the full artifact. Consistency is single-writer-multiple-reader per artifact with bounded staleness — peers re-fetch on next read.

Five synchronization strategies ship out of the box: lazy (default), eager, lease (TTL-based), access_count, and broadcast. Pick the one that matches your workload's read/write ratio and how aggressively cached reads should refresh.

Architecture

• Protocol (ccs.core, ccs.strategies) — coherence state machine and synchronization strategies; no framework dependencies.
• Coordinator (ccs.coordinator) — authority service tracking directory state, publishing invalidations, and reclaiming stale grants (crash recovery).
• Adapters (ccs.adapters) — framework integrations for LangGraph, CrewAI, and AutoGen; ~100 lines each.
• Simulation (ccs.simulation) — deterministic tick-driven engine for scenario benchmarks with failure injection.
• Event bus (ccs.bus) — pluggable transport for invalidation signals; in-memory by default, swap in Redis, Kafka, NATS, or gRPC streams for production.

Protocol safety properties (single-writer, monotonic versioning, crash-recovery sweep invariants) are model-checked with TLA+/TLC. The tla-check CI job runs TLC on every push and PR.

Status

v0.8.2 released — v0.2 strict mode + D v1 LangGraph cycle replay tooling. Consolidated patch release covering both tracks:

• v0.2 strict mode (Python coordinator). Per-artifact strict_mode_paths opt-in via .coherence/strict_mode.yaml, all 4 PreToolUse handlers flip to permissionDecision: "deny" when (strict + tracked + invalidated), TERMINAL_DENIAL_CLASSES structural invariant guarding allow-emission paths, new agent-coherence-migrate-deny console script (STDOUT-only sibling to -migrate-rules with symlink containment), strict-mode telemetry counters + deny-only .coherence/audit.log JSONL surface. Strict mode is Python-coordinator-only; the Node coordinator backend stays warn-mode. Plugin-side broad-beta launch package (Units 8-11) lands separately.
• D v1 LangGraph cycle replay tooling. Adds agent-coherence-replay — pure-inspection replay over captured MESI traces, checking the Core 4 invariants (single-writer, monotonic-version, stale-read, lost-write). New CCSStore.record_to(path) context manager captures a trace from any LangGraph pipeline; record_callbacks(path, accept_unverified=True) is the lower-level seam for direct CrewAI / AutoGen wiring. Five-tier exit-code scheme distinguishes compliance opt-outs from capture bugs from trace errors from CLI internal errors. AMBIGUOUS classification suppresses false positives on same-tick read/commit collisions; --include-ambiguous opts in. New ReplayError exception hierarchy (ReplayConfigurationError for API misuse, ReplayTraceError for trace defects). Quickstart in docs/guide.md §Replay. The validating partner pool (Individual-Bench4448, getstackfax, lastesthero) opens the 30-day per-partner first-touch window now that the v0.8.2 tag has shipped.

v0.8.1 released — single-fix patch: agent-coherence-track / -untrack normalize absolute workspace-relative paths instead of rejecting them.

v0.8.0 released — full Claude Code plugin coordinator (Python backend) plus the ce-review remediation pass. Adds six console scripts (agent-coherence-coordinator, -status, -track, -untrack, -hook-client, -migrate-rules); ships KTD-J telemetry, /status three-tier disclosure, --self-test, and --prepare-for-migration for safe Python↔Node coordinator backend switching. The companion agent-coherence-plugin ships v0.1.1 of the marketplace plugin against this library.

See CHANGELOG.md for the full version history and releases for tagged artifacts. Alpha — APIs may change before v1.0.

Paper

Token Coherence: Adapting MESI Cache Protocols to Minimize Synchronization Overhead in Multi-Agent LLM Systems arXiv:2603.15183

BibTeX

@article{parakhin2026token,
  title   = {Token Coherence: Adapting MESI Cache Protocols to Minimize
             Synchronization Overhead in Multi-Agent LLM Systems},
  author  = {Parakhin, Vladyslav},
  journal = {arXiv preprint arXiv:2603.15183},
  year    = {2026}
}

Community

Questions, war stories, and ideas welcome in Discussions. If you've hit a stale-read bug in a multi-agent workflow, open an issue — I'd like to hear about it.

License

Apache-2.0. See LICENSE.