{"id":51525533,"url":"https://github.com/stifler7/cairn","last_synced_at":"2026-07-08T21:01:03.540Z","repository":{"id":364989528,"uuid":"1270025812","full_name":"STiFLeR7/Cairn","owner":"STiFLeR7","description":"Recoverable long-horizon AI agents — a framework-agnostic reference harness + recovery-faithful live benchmark. Thesis: \"Checkpoints Are Compactions\" via Re-grounding Recovery. 0.x: v1.0 held until a powered live-LLM study confirms the claims.","archived":false,"fork":false,"pushed_at":"2026-07-02T06:56:33.000Z","size":468,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-02T07:12:46.810Z","etag":null,"topics":["agent-memory","agent-recovery","agent-runtime","agentic-ai","ai-agents","ai-research","autonomous-agents","benchmark","checkpoint-restart","checkpointing","code-agent","context-management","durable-execution","fault-tolerance","llm","llm-agents","long-horizon-agents","re-grounding","recovery","resilience"],"latest_commit_sha":null,"homepage":"https://github.com/STiFLeR7/Cairn","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/STiFLeR7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":"docs/governance/ap-workflow.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T10:06:24.000Z","updated_at":"2026-07-02T06:56:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/STiFLeR7/Cairn","commit_stats":null,"previous_names":["stifler7/cairn"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/STiFLeR7/Cairn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2FCairn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2FCairn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2FCairn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2FCairn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/STiFLeR7","download_url":"https://codeload.github.com/STiFLeR7/Cairn/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STiFLeR7%2FCairn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35278166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agent-recovery","agent-runtime","agentic-ai","ai-agents","ai-research","autonomous-agents","benchmark","checkpoint-restart","checkpointing","code-agent","context-management","durable-execution","fault-tolerance","llm","llm-agents","long-horizon-agents","re-grounding","recovery","resilience"],"created_at":"2026-07-08T21:01:02.601Z","updated_at":"2026-07-08T21:01:03.526Z","avatar_url":"https://github.com/STiFLeR7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Cairn\n\n**Recoverable long-horizon agents.**\n\n*Agents should survive failure the way good engineers do — by remembering what they were doing,\nchecking what actually happened, and continuing — not by starting over.*\n\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![Status](https://img.shields.io/badge/status-M4%3A%20BYOM%20recovery%20library%20complete-brightgreen.svg)](ROADMAP.md)\n[![Tests](https://img.shields.io/badge/tests-141%20passing-brightgreen.svg)](tests/)\n[![Version](https://img.shields.io/badge/version-0.x%20(v1.0%20held)-orange.svg)](CHANGELOG.md)\n\n\u003c/div\u003e\n\n---\n\n## What is Cairn?\n\nCairn is an open, framework-agnostic **recovery library, reference implementation, and benchmark for\nrecoverable long-horizon agents**. When an autonomous agent fails at step 47, today it usually starts\nover. Cairn makes recovery a first-class, *measurable* property built on three pillars:\n\n- A durable, typed **Continuation State** (a \"cairn\" — a marker dropped on the trail) that doubles\n  as the agent's working memory *and* its recovery checkpoint.\n- A **Re-grounding Recovery (RGR)** protocol that restores situational awareness after context loss\n  *without* faithful replay.\n- **Effect-safety** guarantees that stop a resumed agent from re-acting on the world\n  (re-sending an email, re-opening a PR).\n\n\u003e A cairn is a small stack of stones hikers leave to re-find a route after losing the trail.\n\u003e That is exactly what a checkpoint is: a minimal, durable marker left behind on purpose.\n\n## The thesis\n\n**Checkpoints Are Compactions.** Long-horizon agents already recover from context loss constantly —\nevery time they compact an overflowing context window. A checkpoint is just a compaction you can roll\nback to. Cairn builds *one* distillation mechanism that serves both.\n\n## Add recovery to your own agent (BYOM)\n\nCairn is **bring-your-own-model**: keep your model, keys, and tools; Cairn adds crash-recovery. Bring a\n`World` (the bundled `Workspace`, or your own) and either call the primitives yourself or use the opt-in\n`Agent` loop:\n\n```python\nfrom cairn import Agent, Workspace, FileCheckpointStore, FileEffectLedger\n\nagent = Agent(your_model, Workspace(\"ws\", \"snaps\"),\n              store=FileCheckpointStore(\"ck\"),\n              ledger=FileEffectLedger(\"effects.jsonl\", \"run\"))\n\nrun = agent.run(goal)        # checkpoints every executed step\n# ... process crashes ...\nrun = agent.resume(goal)     # re-grounds from the last checkpoint and continues\nprint(run.resumed, run.recovery_tax, run.finished)\n```\n\nPrefer to keep your own loop? Use the `checkpoint()` / `recover()` primitives directly. Full walkthrough:\nthe **[BYOM guide](docs/guide/recovery-in-your-agent.md)** and the **[public API reference](docs/guide/public-api-reference.md)**.\n\n```bash\npython examples/byom_recovery.py     # primitives + Agent loop + exactly-once effect (offline, mock model)\n```\n\n## What Cairn is — and is not\n\n| Cairn **is** | Cairn **is not** |\n|---|---|\n| A bring-your-own-model recovery library | A production agent framework |\n| A specification (the Continuation State + boundary contract) | A model |\n| A minimal reference implementation | A general workflow orchestrator |\n| A failure-injection benchmark | A hosted service |\n\nCairn **complements** agent frameworks (OpenHands, LangGraph, custom harnesses) rather than replacing them.\n\n## Project status\n\n**Milestone M4 — BYOM Recovery Library: complete \u0026 merged.** Cairn's recovery mechanism now ships as a\nclean, documented public API a developer drops into their own agent — public `checkpoint()`/`recover()`\nprimitives, an opt-in `Agent` loop, pluggable `World`/`CheckpointStore`/`EffectLedger` contracts, a\nrunnable offline example, a guide + API reference, and CI. **141 passing tests.** The public surface is\nlocked by a contract test; the project stays **0.x**.\n\nThe journey so far:\n\n| Stage | What happened | Outcome |\n|---|---|---|\n| **Phases 0–6** | Specify, build, and *measure* recovery in a deterministic reference harness | 🟢 In-harness, **RGR beats cold restart** (recovery tax 1.5 vs 5.0; all pre-failure work preserved) and the **effect-safety WAL yields zero duplicate effects** |\n| **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) |\n| **M4** | Ship the recovery mechanism as a **BYOM library** so anyone can reproduce C1 on their own model | 🟢 **Complete** — mechanism shipped; stays 0.x |\n\n**Honest scope ([ADR-0009](docs/adr/ADR-0009-evaluation-framework.md)).** The in-harness results establish\nthat the *mechanisms* behave as designed and are reproducible. The headline live claim — *RGR beats cold\nrestart on a real model* (C1) — is **suggestive but not yet confirmed**; a **powered** live study on a\npaid/reliable API is the remaining gate. Cairn therefore stays **0.x**: no v1.0 tag, no PyPI publish, and\nno announcement until that evidence exists. See the [Roadmap](ROADMAP.md), the\n[Master Checklist](CHECKLIST.md), and the [claims registry](docs/research/claims-registry.md).\n\n```bash\npython -m pytest -q                  # 141 passing\npython examples/byom_recovery.py     # BYOM: add crash-recovery to YOUR agent (offline, mock model)\npython examples/recovery_demo.py     # crash mid-task, then recover via re-grounding\npython benchmarks/recovery_matrix.py # the baseline × failure-step benchmark (C1, C3)\n```\n\nThe harness is **never hardcoded** (ADR-0007): model provider, tools, tasks, sandbox, storage, and\npolicies are all injected. The concrete task and scripted model live only in\n[`examples/`](examples/) and [`tests/`](tests/), never in the library.\n\n## Repository map\n\n| Path | Purpose |\n|---|---|\n| [`PAPER.md`](PAPER.md) | The research write-up (\"Checkpoints Are Compactions\") |\n| [`REPRODUCE.md`](REPRODUCE.md) | One-command reproduction of the tests, demo, and benchmarks |\n| [`ROADMAP.md`](ROADMAP.md) | The 7-phase spine + post-phase milestones (M1–M4) |\n| [`CHECKLIST.md`](CHECKLIST.md) | Master checklist (always-visible status) |\n| [`CHANGELOG.md`](CHANGELOG.md) | Notable changes (Keep a Changelog) |\n| [`docs/guide/`](docs/guide/) | **Using Cairn** — BYOM recovery guide + public API reference |\n| [`docs/`](docs/) | **Knowledge** — vision, concepts, governance rules, research, design, ADRs |\n| [`docs/design/`](docs/design/) | **Specs** — Continuation State schema, boundary contract, resume protocol, effect-safety |\n| [`project/`](project/) | **Live state** — phases, Action Points, tracking, templates |\n| [`src/cairn/`](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` |\n| [`benchmarks/`](benchmarks/) | Runnable studies — recovery matrix, ablation, cross-version, live-pipeline |\n| [`examples/`](examples/), [`tests/`](tests/) | Quickstart + BYOM + recovery demos + the suite (141 tests) |\n\n## How we work\n\nCairn is **documentation-first**, **Action-Point (AP) driven**, and **phase/milestone-based**. Nothing is\n\"done\" until its documentation is updated; each phase/milestone lands on its own branch and reaches\n`master` only via PR. See [`docs/governance/`](docs/governance/) and [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## License\n\n[Apache-2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstifler7%2Fcairn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstifler7%2Fcairn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstifler7%2Fcairn/lists"}