Recoverable long-horizon agents.
When an autonomous agent fails at step 47, most frameworks start over. Cairn makes recovery a first-class, measurable property: a durable checkpoint, a protocol that restores situational awareness without replaying every step, and a guarantee that a resumed agent can't duplicate a real-world effect — like re-sending an email or re-opening a pull request.
A cairn is a small stack of stones hikers leave to re-find a route after losing the trail — a minimal, durable marker left on purpose. That's exactly what a checkpoint should be. Cairn's thesis, stated plainly: 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, and Cairn builds one distillation mechanism that serves both.
Cairn is deliberately bring-your-own-model. It doesn't compete with agent frameworks — it complements them. Keep your model, your keys, your tools; Cairn adds the crash-recovery layer on top, either through an opt-in Agent loop that checkpoints every executed step automatically, or through checkpoint()/recover() primitives for a custom loop.
Three pillars carry the recovery guarantee: a typed state, a re-grounding protocol, and an effect-safety ledger.
A durable, typed record — the "cairn" itself — that doubles as the agent's working memory and its recovery checkpoint.
Restores situational awareness after context loss without faithful replay — the agent re-orients rather than re-running from zero.
A write-ahead log of executed effects that guarantees exactly-once execution — a resumed agent can't re-act on the world.
A pluggable environment contract — the bundled Workspace, or your own — that the recovery primitives operate against.
Checkpoints every executed step automatically for teams that don't want to call the primitives by hand.
A bring-your-own-model library, not a new orchestration framework.
Cairn complements LangGraph, OpenHands, and custom harnesses rather than replacing them — the recovery mechanism is the product, not another agent runtime to migrate to.
Rejected —Building a competing, opinionated agent framework.
v1.0 held pending a powered live-LLM study — on purpose.
In-harness results are strong: RGR beats cold restart (recovery tax 1.5 vs. 5.0, all pre-failure work preserved) and the effect-safety ledger yields zero duplicate effects. But the live-model study (M1–M3) ran into free-tier rate limits and came back underpowered — suggestive, not confirmed. Rather than announce an unconfirmed headline claim, the project stays 0.x: no v1.0 tag, no PyPI publish, until a properly powered study exists.
The harness is never hardcoded (ADR-0007).
Model provider, tools, tasks, sandbox, storage, and policies are all injected. The concrete scripted model and task live only in examples/ and tests/ — never inside the library itself.
Documentation-first, Action-Point driven process.
Nothing is considered done until its documentation is updated. Each phase or milestone lands on its own branch and reaches master only through a PR.
- 141 tests passing; public API surface locked by a contract test
- Two offline, API-key-free demos: byom_recovery.py (primitives + Agent loop) and recovery_demo.py (crash mid-task, then recover)
- A separate benchmark suite (recovery_matrix.py) exists specifically for the powered live-LLM study gating v1.0
- 21 documented ADRs and a public claims registry — every headline result is tied to a specific, checkable claim (C1, C3, …)
The project deliberately has not shipped a v1.0 tag or a PyPI release — the in-harness mechanism is proven, but the live-LLM headline claim is honestly marked "suggestive, not confirmed" until a properly powered study exists. That restraint is the point.