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.
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.
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.
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)| 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.
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. |
| P6 — independent conformance | Admission record | Haiku-only clean-room candidate 10 passed the v2 reference matrix (30/30), source audit and real-provider preflight (Stage 6A). A separate sealer (seal 3) and an uninvolved reproducer (reproduction) each obtained 30/30 with verified provider evidence. Admitted 2026-10-19. Candidates 7–9 and seals 1–2 are preserved as failed or spent. One external chain; not 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.
| 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 |
src/cairn/ |
The library: contract (public Protocols), recovery (checkpoint/recover), agent (opt-in loop), worlds/ (Workspace), runtime/, harness/ (loop, distill, reconcile, effects), eval/, tasks/, app |
benchmarks/ |
Runnable studies — recovery matrix, ablation, cross-version, live-pipeline |
examples/, tests/ |
Quickstart + BYOM + recovery demos + the current full suite |
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.