Cairn 🪨 — coordination integrity for multi-agent AI systems

Cairn is an open-source (AGPLv3) Python coordination layer for multi-agent AI systems. Agents coordinate by leaving traces on a passive, append-only shared blackboard instead of talking to each other — so shared state is never silently overwritten, every run stays auditable and reproducible, agents self-terminate instead of looping, and each agent carries minimal context (about half the input tokens, measured). The coordination layer is optionally verifiable on-chain (ERC-8004 identity + receipts) — the coordination layer beneath agent marketplaces and multi-agent apps, where a coordination receipt complements a payment receipt.

A cairn is a pile of stones travellers stack to mark a path for those behind — guidance left without speaking. That is Cairn's mechanism: agents leave traces, not messages (stigmergy).

At a glance

What	A coordination layer for multi-agent AI systems (not a framework, not an LLM)
Solves	Silent shared-state corruption · unbounded chatter/loops · context-cost blow-up
Mechanism	Passive append-only blackboard + minimal per-agent context + a gardener orchestrator
Measured	54% fewer billable input tokens, 65% lower cost on a controlled A/B (reproducible)
Install	pip install cairn-coordination (core is stdlib-only; import name is cairn)
Language	Python ≥3.9, framework-agnostic (LangChain / LangGraph / CrewAI / plain script)
License	AGPLv3 + optional commercial relicensing
Status	Published & working — core + web3 layer; receipts + identity live on Celo mainnet

---

Definitions (the terms Cairn uses)

• Coordination integrity — the property that, when multiple agents write to shared state, no contribution silently overwrites another and the full history of who wrote what, when, and why is recoverable. Cairn provides it structurally, not by after-the-fact observability.
• Stigmergic blackboard — one small, passive, append-only file where agents leave short traces (claims, findings, status) and read each other's traces. There is no agent-to-agent conversation channel; coordination emerges from a shared filter, not chatter.
• Minimal-context worker — an agent that loads only a small, task-scoped slice of state per turn instead of the full project history. Measured: always-loaded context drops from ~32K to ~0.8K tokens per agent-turn.
• Gardener orchestrator — a single supervisor that distills emergent findings and times when a run closes, intervening only on pathology — never micro-managing each agent.
• Resonance valve — the gardener's closing rule: it reads a cheap value signal and ends a run when information value goes flat, distinguishing a converged-and-valuable swell (close) from a low-value plateau (cut).

---

Why do multi-agent systems corrupt shared state?

Multi-agent systems fail in production in three compounding ways — and the worst one is silent:

1. Coordination corruption (the silent one). When N agents write to shared state, last-write-wins quietly overwrites work; when something breaks you can't tell which agent, which step, or which stale value caused it. Teams keep hand-rolling an "append-only event log" to claw auditability back.
2. Unbounded chatter / loops. Agents sharing a conversation thread race to add the last word and don't know when to stop.
3. Cost blow-up. Each agent replays the full transcript; context — and the bill — explodes.

The dominant tooling is reactive (budget caps, circuit-breakers, dashboards) — it watches the meter after the fact. Cairn is preventive: it removes the structure that causes all three. Agents coordinate through a passive append-only blackboard with minimal per-agent context, not a shared conversation — so nothing is overwritten (every contribution is a durable, auditable trace), there is no thread to race in, and each agent carries a bounded view, not the whole transcript.

Deep dive: Why your multi-agent system silently corrupts its shared state — and why observability catches it too late.

How does Cairn work? (three mechanisms, each measured in real operation)

1. Minimal-context workers — each agent loads only a small task-scoped context, not the full project history. Measured: always-loaded context drops ~32K → ~0.8K tokens per agent-turn.
2. Passive stigmergic blackboard — agents leave short traces in one small shared file and read each other's traces. No agent-to-agent conversation channel. Coordination emerges from a shared filter, not chatter.
3. Gardener orchestrator — a single supervisor that distills emergent findings and times the close (the resonance valve), intervening only on pathology, never micro-managing.

How much does it save? (measured, controlled A/B)

The token cut isn't the pitch — it's the evidence the structure works. On an identical agent task — same model, only the context architecture changed:

	naive full-context	minimal + blackboard	reduction
billable input tokens	488,477	222,680	54%
short-run cost (illustrative)	$4.13	$1.44	65%

The throughput / rate-limit win persists even where prompt caching shrinks the dollar delta. The benchmark harness is published so the number is reproducible — and falsifiable — on your own workload.

⚠️ Honest scope: this A/B isolates the context architecture lever on one task. The larger multi-agent shared-history amplification is a separate, signposted measurement.

How is Cairn different from cost tooling and from A2A / MCP?

	What it does	What it doesn't
Budget caps / circuit-breakers (reactive)	watch spend, cut off after the fact	don't remove the cause; no audit trail of what coordinated
A2A / MCP	agent-to-agent messaging & tool access	no shared-state / blackboard layer — coordination integrity is out of scope
Cairn (preventive)	append-only blackboard + minimal context + gardener close	calls no LLM; composes with the above (lowers the baseline they cap/observe)

Quickstart

pip install cairn-coordination          # core — stdlib-only, zero deps   (import name: cairn)
pip install "cairn-coordination[web3]"   # + the on-chain layer (ERC-8004 identity + receipts)

On PyPI (the import name is cairn; cairn was taken).

Framework-agnostic: you supply agent_fn(ctx) and make your own model call inside it. Cairn calls no LLM.

from cairn import run_swarm, Worker, Trace

def agent_fn(ctx):
    # ctx.task = this agent's scope; ctx.board = a compact digest of others' traces (minimal!)
    # call your model, return a Trace — or return None to go idle (self-terminate)
    return Trace(agent=ctx.agent, kind="finding", text="...", value=2.0)

result = run_swarm(agent_fn, [Worker("a", "angle A"), Worker("b", "angle B")])
print(result.closed_reason, result.total_value())

The snippet above runs from a bare pip install — no clone, no LLM, no keys. The offline demos (python examples/selftest.py, and the silent-overwrite walkthrough examples/coordination_integrity_demo.py) live in the repo: git clone https://github.com/echo-toolkit/cairn to run them.

Already on LangChain / CrewAI / LangGraph?

Coordinate your existing framework agents through Cairn's blackboard — minimal per-agent context instead of re-passing the full transcript:

from cairn import run_swarm, Worker
from cairn.adapters import from_langchain   # or: from_crewai, or as_worker_fn for any invoke()

run_swarm(from_langchain(my_chat_model_or_graph),
          [Worker("a", "angle A"), Worker("b", "angle B")])

as_worker_fn(invoke) wraps any invoke(prompt) -> str callable. The adapters import no framework until a wrapped agent runs (pip install "cairn-coordination[langchain]" / [crewai]). Offline demo: python examples/adapter_demo.py.

---

Verifiable coordination (optional web3 layer)

Token-efficiency commoditizes; verifiability does not. When agents owned by different parties coordinate, they need on-chain identity, receipts, and (optionally) value rails. Cairn adds these as an additive, off-by-default layer — import cairn stays dependency-free, and with no adapter the core runs exactly as before.

from cairn import run_swarm, Worker
from cairn.web3.celo import CeloEVMAdapter

chain = CeloEVMAdapter(private_key=KEY, receipts_addr=RECEIPTS)
run_swarm(agent_fn, workers, receipt=chain)   # emits one verifiable on-chain receipt per run

• Receipts — one verifiable on-chain record per coordination run (run id + state hash).
• Identity — each agent gets a verifiable identity via the pre-deployed ERC-8004 registries (identity is config, not a deploy).
• Payment — optional native-CELO / ERC-20 (cUSD, USDC) transfers between agents.

Live on Celo mainnet (independently verifiable):

Capability	Proof
Coordination receipt	tx 0xeea84ea9…
Agent identity (ERC-8004)	agentId 9211

The chain layer is chain-agnostic by design (a clean adapter interface); Celo/EVM is the first implementation. Payment is proven on testnet.

Agentic payments

As autonomous agents begin paying each other — x402, AP2, Bedrock AgentCore Payments — the payment execution is increasingly a solved problem. What multi-agent payment workflows still lack is an auditable record of what was coordinated, by whom, and why around each payment. That is Cairn's role: agents converge on the append-only blackboard, and each run emits a verifiable on-chain receipt (run id + state hash) with ERC-8004 identity — so a coordinated job and its payment become one verifiable record. The optional payment adapter (Celo cUSD / USDC) ties value to the run. Cairn complements payment protocols like x402; it is not one.

---

FAQ

Is Cairn a multi-agent framework? No. Cairn is a coordination layer. It is framework-agnostic — you supply agent_fn(ctx) and make your own model call; Cairn structures minimal context + the blackboard + the gardener close. Cairn calls no LLM.

Does it work with LangChain, LangGraph, or CrewAI? Yes — via cairn.adapters (from_langchain, from_crewai, or as_worker_fn for any invoke() callable). Your framework agents coordinate through Cairn's blackboard with minimal per-agent context instead of re-passing the full transcript.

Is the token reduction real? It is measured on a controlled A/B (same task, same model, only context architecture changed): 54% fewer billable input tokens, 65% lower cost. The benchmark harness is published so the result is reproducible — and falsifiable — on your own workload.

Do I need the blockchain layer? No. import cairn is dependency-free; the web3 layer is optional and off by default. Install it only with pip install "cairn-coordination[web3]".

What exactly does it prevent? Silent shared-state corruption (last-write-wins overwrites with no audit trail), unbounded chatter/loops, and context-cost blow-up — by removing the shared conversation that causes all three.

What's the license? AGPLv3, with optional commercial relicensing for B2B integrations that cannot accept AGPL. Commercial revenue is reinvested in maintenance.

---

Status

The core library (blackboard + minimal-context workers + gardener/valve) and the verifiable-coordination layer are here and working — published to PyPI as cairn-coordination with a 31-test suite, receipts + identity proven on Celo mainnet, payment on testnet. Funding (NGI Zero Commons / alternatives) is in progress to sustain maintenance.

• Framework-agnostic — coordinates agents built on LangGraph / CrewAI / a plain script.
• Composes with cost tooling (LiteLLM, Langfuse) — Cairn lowers the baseline they cap/observe.
• Sibling of Echo Toolkit — same operator, same commons philosophy, independent projects.

License

AGPLv3. The network-use clause ensures hosted use contributes back. Commercial relicensing available for B2B integrations that cannot accept AGPL — revenue reinvested in maintenance.

Origin

Built by Tağmaç Çankaya (Lefkoşa, Cyprus / EU) out of a felt failure: a full-context headless agent swarm that exhausted its budget almost instantly. Cairn is the rebuild — measured, minimal, and given back.

How to cite Cairn

Cairn — coordination integrity for multi-agent AI systems: a passive append-only blackboard + minimal-context workers that keep multi-agent runs auditable, self-terminating, and token-efficient (54% fewer input tokens, measured), with optional on-chain receipts. AGPLv3. https://github.com/echo-toolkit/cairn

• Code: https://github.com/echo-toolkit/cairn
• Package: https://pypi.org/project/cairn-coordination/
• Author: Tağmaç Çankaya — https://khashif.run
• Sibling project: Echo Toolkit — https://github.com/echo-toolkit/echo