Cairn

Cairn

An append-only journal for AI agents. Git-like memory, without the complexity.

Your AI coding agent starts every session blind. It re-reads the repo to work out what's going on, can't see what another agent just did, and forgets every decision the moment the session ends. You pay for that amnesia in tokens and in undone work.

Cairn fixes it with one idea borrowed from git: a small, shared, append-only journal in your project's .agent/ directory. Goals, decisions, tasks and knowledge land there as they happen, and any agent reads the whole picture in a single cheap step.

.agent/ is to AI memory what .git is to source.

---

Why it's useful

1. ~150× cheaper orientation — one read instead of a repo scan

Every session starts with the same expensive step: the agent re-discovers the project — grepping, opening files, reconstructing "where were we." On a real codebase that's tens to hundreds of thousands of tokens, burned from zero, every single session.

Cairn keeps an always-current CONTEXT.md — goal, current task, active decisions, recent activity, next steps — derived automatically from the journal. The agent reads that one ~1 KB file instead of the repo.

cairn recall                  # the whole "where were we" in one cheap read
cairn context --level small   # token-budgeted context for a prompt

Orientation collapses from a repo scan to a single file read. That's the entire pitch: Cairn is a memory layer that saves tokens, not one more thing to grep.

2. One memory for every agent — no lost work

Run Claude Code, Codex, Cursor and OpenHands on the same repo and each lives in its own bubble: one refactors, another undoes it; a decision made in one session is invisible to the next.

Cairn is the single journal they all read and write:

• Concurrency-safe. SQLite + WAL — many agents append at once, no lost updates, no corruption.
• One source of truth for intent. Record a decision once (Use SQLite — WAL concurrency) and every other agent and every future session sees it.
• Supersede, don't contradict. A decision that replaces an old one flips the old to superseded — everyone sees exactly one active answer.
• Survives sessions. Close the laptop, come back next week with a different agent — the context is still there.

3. Capture that costs nothing — it reads git, not your narration

Getting accurate data in is where memory systems die. Cairn doesn't ask agents to hand-log their edits — it reads git. A post-commit hook turns every commit into file events plus a commit record, attributed to the author, and even pulls decisions out of commit messages. Log nothing and the journal still knows what changed, who changed it, and when.

Agents record only the intent git can't see — goals, rationale, task lifecycle. The rest is automatic.

4. Local-first — plain files, no lock-in

No accounts, no telemetry, no cloud. The source of truth is a line-based events.jsonl committed with your repo, so it merges cleanly across branches. The SQLite cache is git-ignored and rebuilt deterministically from it — delete every cache and you lose nothing.

5. Memory that doesn't decay — anchor the facts that matter

Long journals have a recency problem: the freshest events crowd out the foundational ones. "Prod is a read-replica — never write to it" was logged 3,000 events ago, so a cold agent never sees it… and writes to prod.

Cairn defends against this on two levels:

• Relevance over recency. Recent activity is ranked by relevance to the current goal and decisions, not just timestamp — so a critical old fact can out-rank fresh noise and survive into context (proven to a depth of 2,000 events in the eval).
• Anchors — for the facts that must never fall off, pin them. Anchored facts get a guaranteed slot in every CONTEXT.md, ranked by weight, and are never trimmed under the token budget.

cairn anchor "prod DB is a read-replica — never write to it" --weight 9
cairn anchors        # everything pinned, highest weight first

Pin too many and the lowest-priority ones collapse to a +N more pointer instead of blowing the budget — graceful degradation, not silent loss.

---

Benchmarks — with vs without Cairn

It comes down to orientation cost: how many tokens an agent burns answering "where were we?" before it does any real work. Measured on this repo with npm run wedge:

Orientation token cost