cairn-coordination 0.2.0

Token-efficient, verifiable multi-agent AI coordination — passive stigmergic blackboard + minimal per-agent context, with an optional on-chain (ERC-8004 identity + coordination receipts) layer.

Cairn 🪨

A free AGPLv3 coordination layer that lets multiple AI agents work together without burning the token budget — by coordinating through a passive shared blackboard and minimal per-agent context, instead of conversation. Optionally, it makes that coordination verifiable on-chain.

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.

---

The problem

Multi-agent AI systems fail in production mostly on cost: agents talk to each other in unbounded loops, each carrying the others' full transcripts, until the context — and the bill — explodes. The dominant tooling is reactive (budget caps, circuit-breakers, observability dashboards): it watches the meter and pulls the plug after the fact. It does not change the architecture that generates the spend.

Cairn is preventive — it removes the structure that causes the explosion.

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 (claims, findings, status) 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 (a resonance valve), intervening only on pathology, never micro-managing.

Measured result (dogfooded, controlled A/B)

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.

Quickstart

pip install "git+https://github.com/echo-toolkit/cairn"            # core — stdlib-only, zero deps
pip install "cairn[web3] @ git+https://github.com/echo-toolkit/cairn"   # + the on-chain layer

(PyPI release — pip install cairn — coming.)

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())

python examples/selftest.py runs an offline, dependency-free demo of the whole loop.

---

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.

---

Status

The core library (blackboard + minimal-context workers + gardener/valve) and the verifiable-coordination layer are here and working — 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.