Cairn

Recoverable long-horizon agents.

Agents should survive failure the way good engineers do — by remembering what they were doing, checking what actually happened, and continuing — not by starting over.

Website: cairn.stifler.in · Quickstart · Compare

---

What is Cairn?

Cairn is an open, framework-agnostic recovery library, reference implementation, and benchmark for recoverable long-horizon agents. When an autonomous agent fails at step 47, today it usually starts over. Cairn makes recovery a first-class, measurable property built on three pillars:

• A durable, typed Continuation State (a "cairn" — a marker dropped on the trail) that doubles as the agent's working memory and its recovery checkpoint.
• A Re-grounding Recovery (RGR) protocol that restores situational awareness after context loss without faithful replay.
• A narrowly admitted receipt/reconciliation semantics: re-observe before retry, then retry, skip, or escalate from durable evidence. It is not an exactly-once guarantee.

A cairn is a small stack of stones hikers leave to re-find a route after losing the trail. That is exactly what a checkpoint is: a minimal, durable marker left behind on purpose.

The thesis

Checkpoints Are Compactions. Long-horizon agents already recover from context loss constantly — every time they compact an overflowing context window. A checkpoint is just a compaction you can roll back to. Cairn builds one distillation mechanism that serves both.

Add recovery to your own agent (BYOM)

Cairn is bring-your-own-model: keep your model, keys, and tools; Cairn adds crash-recovery. Bring a World (the bundled Workspace, or your own) and either call the primitives yourself or use the opt-in Agent loop:

from cairn import Agent, Workspace, FileCheckpointStore, FileEffectLedger

agent = Agent(your_model, Workspace("ws", "snaps"),
              store=FileCheckpointStore("ck"),
              ledger=FileEffectLedger("effects.jsonl", "run"))

run = agent.run(goal)        # checkpoints every executed step
# ... process crashes ...
run = agent.resume(goal)     # re-grounds from the last checkpoint and continues
print(run.resumed, run.recovery_tax, run.finished)

Prefer to keep your own loop? Use the checkpoint() / recover() primitives directly. Full walkthrough: the BYOM guide and the public API reference.

python examples/byom_recovery.py     # primitives + Agent loop (offline, mock model)

What Cairn is — and is not

Cairn is	Cairn is not
A bring-your-own-model recovery library	A production agent framework
A specification (the Continuation State + boundary contract)	A model
A minimal reference implementation	A general workflow orchestrator
A failure-injection benchmark	A hosted service

Cairn complements agent frameworks (OpenHands, LangGraph, custom harnesses) rather than replacing them.

Project status

Recovery proof ladder P1–P6: complete, narrowly. The existing BYOM library is released as v1.0.0 (2026-10-21). The evidence-backed claims are the three narrow contracts below, not a claim that Cairn makes arbitrary agents reliable or provides exactly-once external effects.

Proof phase	Admitted result	Evidence boundary
P1 — crash/restart	Repository recovery fidelity in the deterministic reference harness	RecoveryBench report
P2 — compaction continuity	Continuation Contract v0	P2.4: 40 eligible U/R/C cells across Claude Code Opus/Sonnet; 20 pre-continuation Sonnet acquisition failures are retained, not counted as recovery successes (verdict)
P3 — external effects	Receipt/Reconciliation Contract v0	One deterministic create-once provider effect: 36 reference and 15 sealed-holdout cells; no duplicate or silent-loss cells. The holdout reused the provider/harness, so this is not independent-provider validation (verdict)
P4 — external host	Claude Code integration proof	One Claude Code host/provider proof. V5 gives the shared-checkpoint/effect reference control; V6 adds a post-compaction causal negative and independently sealed generic U/R/C holdout (admission verdict).
P5 — second host portability	Two-host portability evidence	Claude Code’s admitted P4 evidence and OpenHands SDK 1.42.1’s sealed reference plus independent holdout passed the same host-neutral recovery/effect criteria (verdict). This is deterministic two-host evidence, not universal compatibility or a standard.

P2 requires a fresh process without the original transcript and is conditioned on acquiring a clean, verified checkpoint. P3 requires re-observation before a retry and admits only the decision semantics proven for its reference effect: absent → retry; matching present → skip; unknown, mismatch, and never-retry → escalate. Neither contract establishes broad live-model performance, a framework API, or general external-effect delivery. P4 admits one host integration only; it does not expand either v0 contract. P5 adds only deterministic two-host portability evidence; it does not establish universal compatibility, a host-native Cairn integration, exactly-once delivery, or an ecosystem standard. P6 adds evidence that the Recovery Conformance Kit v2 semantics can be implemented independently: a Haiku-only clean-room host (candidate 10) passed Stage 6A, and a separate sealer and an uninvolved reproducer each obtained 30/30 on a post-freeze real-provider holdout. Candidates 7–9 and two spent seals are preserved as failed or spent. P6 is one passing external chain; it is not an ecosystem standard, universal compatibility, or exactly-once delivery.

The journey so far:

Stage	What happened	Outcome
Legacy phases 0–6	Specify, build, and measure recovery in a deterministic reference harness	🟢 Historical mechanism and benchmark work; see the proof ladder above for the currently admitted P1–P4 boundaries
M1–M3	Run the benchmark against real LLMs to confirm the headline claim (C1)	🟢 Live pipeline works; RGR looks strong — but NO-GO for v1.0: evidence is suggestive, not confirmed (free-tier rate limits + underpowered runs)
M4	Ship the recovery mechanism as a BYOM library so anyone can reproduce C1 on their own model	🟢 Complete — mechanism shipped; stays 0.x
M5	Pre-registered, capability-matched live study on two subscription-CLI models to decide v1.0	🟢 Complete — GO for v1.0 (C1 capability-matched + C3 supported on Claude and Codex; awaiting owner approval to release)

Honest scope (ADR-0009). The legacy live C1 claim remains suggestive rather than confirmed; M5's pre-registered study returned GO for v1.0 (awaiting owner approval to release) on a deliberately narrow basis: one chain task, two competent models, C2/C4/C5 reference-only, a harness-injected C3 effect (see the claims registry, 2026-10-21). P1–P6 establish narrowly scoped recovery semantics, one external-host integration proof, two-host portability and one independent implementation in the recorded reference and sealed-holdout experiments; they do not by themselves establish broad live performance. See the Roadmap, Master Checklist, and claims registry.

python -m pytest -q                  # current full suite
python examples/byom_recovery.py     # BYOM: add crash-recovery to YOUR agent (offline, mock model)
python examples/recovery_demo.py     # crash mid-task, then recover via re-grounding
python benchmarks/recovery_matrix.py # the baseline × failure-step benchmark (C1, C3)

The harness is never hardcoded (ADR-0007): model provider, tools, tasks, sandbox, storage, and policies are all injected. The concrete task and scripted model live only in examples/ and tests/, never in the library.

Repository map

Path	Purpose
PAPER.md	The research write-up ("Checkpoints Are Compactions")
REPRODUCE.md	One-command reproduction of the tests, demo, and benchmarks
ROADMAP.md	The 7-phase spine + post-phase milestones (M1–M4)
CHECKLIST.md	Master checklist (always-visible status)
CHANGELOG.md	Notable changes (Keep a Changelog)
docs/guide/	Using Cairn — BYOM recovery guide + public API reference
docs/	Knowledge — vision, concepts, governance rules, research, design, ADRs
docs/design/	Specs and admitted contracts — state/boundary/resume designs plus Continuation Contract v0 and Receipt/Reconciliation Contract v0
project/	Live state — phases, Action Points, tracking, templates

How we work

Cairn is documentation-first, Action-Point (AP) driven, and phase/milestone-based. Nothing is "done" until its documentation is updated; each phase/milestone lands on its own branch and reaches master only via PR. See docs/governance/ and CONTRIBUTING.md.

License

Apache-2.0.