369×fewer tokens
An agent asks about src/cairn/router.py before editing it.
Source: the Impact page's context-served log.
v0.3.1 · Open source · Apache-2.0 · runs on your machine
Coding agents start every session lost. Cairn marks the trail.
Cairn is institutional memory for coding agents. It gives Claude Code, Codex, Gemini, Cursor, Copilot and more what a senior engineer carries in their head: who calls this code, why it is shaped this way, what broke last spring, what the team agreed and what the last agent did.
$ uv tool install --python 3.12 cairn-brain$ cd your-repo && cairn# Cairn brief: cairn Map 873 files, 16,822 nodes hubs: QueryExecutor, EntityNode, GraphDriver Specs 001-cairn-core · 75/75 tasks done Timeline 3 fixes in router.py this week Memory [gotcha] Memory seeding gets the deep tier's wall-clock cap [decision] 12 core tools by default [convention] Every model call goes through cairn.router Sessions last: "launch video v2 shipped" Drift 49 open findings · run cairn drift Before editing: call cairn_context.
1,882 tokensto start a session that knows what 18 million tokens of past work found
Wires itself into
- Claude Code
- Codex
- Gemini CLI
- Cursor
- OpenCode
- Cline
- Copilot CLI
- Antigravity
Three films · narrated · captioned
See it before you install it.
Each film is recorded on Cairn's own repository and its real interface. Start with the one-minute version.
The session tax
Every new session, your agent pays again to rediscover your repository.
Agents are capable but amnesiac. The context a teammate picks up over months is gone when the session ends, so they burn tokens re-reading and still miss what was never in the files.
What it costs
Agent without memory
Agent with Cairn
Re-reading the same files
144,228 tokens
Opens 33 files to understand router.py before it writes a line. Next session, it does it again.
391 tokens
Asks cairn_context and gets the dependents, co-changing files and owning task in one pack.
Missing the caller three hops away
Breaks a dependent
Changes a signature. Grep found the direct callers; the 137 dependents in 40 files did not fit in context.
Risk: HIGH, before the edit
cairn impact walks the code graph built from Tree-sitter ASTs and lists the tests likely to break.
Re-applying the fix you reverted
Repeats history
Proposes the change the team rolled back last spring. The reason lives in a commit message nobody will read.
Warned with the commit
The timeline carries fixes, reverts and co-change patterns, and surfaces them as historical warnings.
Ignoring what the team agreed
Fails review
The convention was settled in a pull request thread. The agent never saw it and the reviewer explains it again.
Knows the convention
Memory is seeded from ADRs, style docs and git history, and grows each time someone runs cairn remember.
Losing yesterday's session
"What were we doing?"
A new chat starts blank. You paste the plan back in, or the agent re-derives it from the diff.
Picks up where it stopped
Sessions are captured and summarised. The next one starts with a brief of what earlier agents did and learned.
Receipts, not claims
Cairn measures what it saves you, on every call.
Each context pack an agent receives is logged with its own size and the size of the files behind it. These numbers come from running Cairn on its own repository. The bars are drawn to scale.
An agent asks about
9,575×smaller start
454 captured agent sessions, condensed into what the next one needs to know.
Source: the Sessions page. 17,761,951 tokens kept out of future sessions.
Run
cairn recap to see the receipt for your own repository.
Every model call is in cairn models --ledger.
New in 0.3 · October 2026
Your agent keeps its place and gets smarter every session.
None of these needs a model call. Each one is on by default and can be turned off.
Survives compaction
When Claude Code compacts, a resume snapshot under 2 KB hands back the last request, files changed, open tasks, decisions and rejected approaches.
Remembers what failed
Refused tool calls, error-then-fix pairs, retry loops and your corrections are recorded as their own observations, so the next agent finds them.
Old advice sinks
A memory no agent has used in 90 days is marked stale and ranks lower. Nothing is deleted, and conventions and decisions never age.
Pass work between agents
Build a resume briefing from a captured session and start Claude, Codex, Gemini, OpenCode, Cline or Cursor on it.
93–96% cheaper notes
Session notes cost far fewer model tokens on the new default fast model. Overview shows tokens measured and dollars estimated from your own ledger.
Every agent, once
Wire Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Copilot CLI and Antigravity at user level. Repositories without Cairn get a one-line offer.
Five layers, one stack
A cairn is a stack of stones that tells the next traveller where the path goes.
Cairn stacks five kinds of knowledge about your repository. Each answers one question an agent should ask before it touches code. Pick a stone.
A graph of files, symbols, calls and imports from Tree-sitter ASTs (25 grammars built in), plus docs, schemas and rationale comments. It is how Cairn knows the caller three hops away.
cairn trace path · cairn hubs · cairn areas
A spec-driven workflow of constitution, spec, plan and tasks, traced to the files that implement them. Drift checks find closed tasks whose code moved on.
cairn specs · cairn drift
Git history read for meaning: fixes, reverts, files that change together. With a model, facts with validity windows, like "true from March until the May refactor".
cairn timeline · cairn why <file>
Conventions, decisions, gotchas and preferences from people, agents and the repository itself. New memories update, merge with or retire the ones they overlap.
cairn remember "…" --kind convention · cairn recall
Prompts, files read and changed, and commands from every captured agent session, turned into observations and summaries the next session starts with.
cairn sessions search <query>
Setup takes one command
Install it once. Every commit and session after that adds a stone.
1 · Run
cairn
It sets the repository up without asking questions.
It adds the spec workflow, wires every agent it detects to the Cairn MCP server, installs git hooks and runs the first sync.
$ cairn ✓ agents Claude Code, Codex, Gemini ✓ hooks post-commit, post-merge … ✓ sync 873 files mapped → page http://127.0.0.1:4747
2 · Agents ask first
Before an edit, the agent asks Cairn instead of reading the tree.
Sessions open with a short brief. Before touching a file, the agent calls cairn_context, cairn_impact or cairn_why over MCP.
agent → cairn_impact router.py HIGH 137 dependents · 40 files 3 past fixes · 5 co-change owner: T006 (FR-017) 391 tokens served
3 · It compounds
Each commit re-syncs in the background. Each session leaves notes.
A commit never waits on Cairn. Captured sessions become observations, so next week's agent knows what this week's agent learned.
$ git commit -m "fix: lock on Windows" [cairn] re-sync queued (background) + timeline fix recorded + memory 1 gotcha reconciled + sessions summary written
The question to ask before every edit
One call. Every layer. A risk level.
This is real output from Cairn's own repository. None of it needs a model: it is all built from the code graph, git history, specs and memory.
- Dependents and tests from the code graph, each marked EXTRACTED or INFERRED.
- Historical warnings: past fixes and reverts on these lines.
- Intent: the requirement and the task that produced the file.
- Memory: the convention a reviewer would otherwise repeat.
- Agent sessions that touched it recently.
Impact: src/cairn/router.py HIGH 137 dependents in 40 other files; 3 past fix/reverts; 5 files usually change with it Dependents (+64 more) • Cairn.__init__() core.py:208 calls Router • make_router() recall/worker.py:81 • semantic() drift.py:92 calls Budget • run() sync.py:142 calls Budget Changes together • engines/__init__.py 2 commits (100%) • store.py 2 commits (67%) Historical warnings • 973abd33 fix: Windows worker-lock detection • f3ea2a9e fix: read and write text as UTF-8 Intent • FR-017 route every model call through one layer • T006 model router with tiers and ledger (done) Memory • [convention] Every model call goes through cairn.router with a task name in TASK_TIER
Where it fits
Rules files, chat memory and code search each hold one piece.
Cairn connects them, keeps them current from git, and hands the agent only the part it needs for the task in front of it.
| The agent knows… | Rules file (AGENTS.md) | Chat or vector memory | Code search index | Cairn |
|---|---|---|---|---|
| Who calls this code, across files | — | — | ~Text matches | ✓Call and import graph |
| What the code was meant to do | ~If someone wrote it down | — | — | ✓Specs traced to files |
| Past fixes and reverts | — | — | — | ✓From git history |
| Team conventions | ✓Kept by hand | ~Per user | — | ✓Seeded and reconciled |
| What earlier agent sessions did | — | ~Chat snippets | — | ✓Observations and summaries |
| Stays current without upkeep | — | ~ | ✓ | ✓Git hooks re-sync |
| Works with no API key | ✓ | ~Varies | ~Varies | ✓Deterministic core |
Built to be trusted
Your code stays yours. Your plan stays yours.
Deterministic first
Useful with no model at all.
Impact, why, drift, the map and seeded memory are built from ASTs and git. Evidence is tagged EXTRACTED or INFERRED so the agent knows what to trust.
Local
Nothing to host.
Python 3.11–3.13 and git. No Docker, no database server. Without a model, nothing leaves your machine.
Your models
Uses what you already have.
An Anthropic or OpenAI-compatible key, a local endpoint, or your signed-in Claude Code plan. Each job goes to the cheapest tier that does it well.
Accountable
Every call in a ledger.
Model spend is capped per sync and recorded. cairn uninstall removes everything setup added.
For teams
One memory for the whole team's agents.
The same server serves a team. A convention one developer records reaches every agent on every laptop the next time it asks.
- Sign-in, roles and API tokensOwners, members and read-only access per project.
- Git projects that re-sync on pushThe server clones the repository and keeps the map current.
- Shared sessions with attributionSee which teammate's agent did what, and when.
- An audit logWho asked, who remembered, who changed what.
$ cairn team init --email [email protected] $ cairn serve --team $ cairn project add https://github.com/acme/api.git $ cairn team invite [email protected] --role member # on each laptop $ cairn agents connect --server https://cairn.acme.dev
Does my code get sent anywhere?
Not without a model. The map, impact, why, drift and seeded memory are computed locally. If Cairn finds a model, it calls the provider you configured, or your signed-in Claude Code CLI, and records every call in the ledger.
Which agents does it work with?
Claude Code, Codex, Gemini CLI, Cursor, OpenCode and GitHub Copilot get the MCP server and a session-start brief. Claude Code also gets session capture hooks, a status line, slash commands and sub-agents. Other agents can turn on capture with cairn sessions integrate install <agent>.
Do I need an API key?
No. The core is deterministic. A model adds summaries, timeline facts with validity windows, narrated answers and semantic drift checks, and Cairn can use your Claude Code plan for those with no key.
What does the model work cost?
Each sync's timeline work is capped at 150,000 tokens by default. Change it with [deep] budget_tokens, or turn it off. Small jobs go to the fast tier; only synthesis uses the deep one. Since 0.3, session notes cost 93–96% less per tool event, and Overview shows your spend from the ledger.
Will it slow down my commits?
No. Git hooks queue a background re-sync and return straight away.
How do I remove it?
Run cairn uninstall. It removes the hooks, agent wiring and files that setup added.
Leave a marker for the next agent.
Two commands. Your next session starts with what the last hundred learned.
$ uv tool install --python 3.12 cairn-brain