🪨 Cairn

AI Context Continuity Engine

Carry the decisions, evidence and exact values of a long agent session into the next one, locally. Cairn shows how full the context is, keeps a decision and evidence ledger, and hands a faithful 7-bucket brief to the next session, or the next model.

Claude Code · Codex · SQLite ledger · Account mode · No telemetry

Cairn Handoff  ·  Cairn resume  ·  Cairn Help

https://github.com/user-attachments/assets/50dd9db2-8c95-45d8-b830-9d447c129c18

✨ Why Cairn

Long AI sessions lose first the things that are most expensive to miss later: architecture decisions, rationale, discarded paths, exact IDs, code and config blocks. Cairn keeps a local memory alongside the agents for exactly this: no backend, no cloud.

Related MCP server: io.github.oleksiijko/pmb-ai

🧭 How It Works

flowchart LR
    ask(["You: Cairn Handoff"]) --> host["Session model<br/>in Claude Code or Codex"]
    host -->|"7-bucket brief"| handoff["handoff tool"]
    handoff --> check["Verbatim check<br/>missing values reported"]
    check --> ledger[("Local SQLite ledger")]
    resume(["You: Cairn resume"]) --> log["decision_log<br/>view=current"]
    ledger --> log
    log --> next["Next session<br/>or another model"]

The default path is account mode: the host agent writes the handoff brief inside your running Claude or Codex session. Cairn only stores and validates it: no server-side model call, no API keys, no egress through Cairn. If your session model is not the most faithful summarizer (Claude Opus 5.5 on Claude, GPT-6.1 Sol on Codex), the handoff result says so, and you can switch the model (/model) and run Cairn Handoff again. Cairn never does that on its own: re-compacting the session would be a second model call over the whole context.

In the optional modes (sampling, bridge, API) Cairn condenses the source itself: it masks code, IDs and values as [[CAIRN-HOLD-n]], calls the model, restores the blocks byte-exact and checks the brief's quotes against the source.

⚡ Quick Start

git clone https://github.com/CheswickDEV/cairn.git
cd cairn
npm install
node dist/server.js install      # detects Claude Code + Codex, wires up both best-effort

Cairn acts only when you explicitly ask. It does not resume or save at task or session boundaries, on yellow or red zones, or around compaction. One request covers one action; resume never enables a later automatic handoff. Help and passive status displays do not call MCP tools.

Then say it in chat (or use /cairn-handoff, /cairn-resume, /cairn-help in Claude Code; $cairn-handoff, $cairn-resume, $cairn-help in Codex):

To undo: node dist/server.js uninstall

🆕 What's New in 2.0

The binding architecture is in docs/adr/ADR-cairn.md, every change in the CHANGELOG.

📋 The 7-Bucket Brief

Every handoff follows the same format:

DECISIONS · EVIDENCE · OPEN QUESTIONS · CONSTRAINTS · VERBATIM · NEXT STEPS · DISCARDED

The brief keeps what was said apart from what the summarizer concluded (ADR-0013). A shortened, made-up example:

DECISIONS
- Rate-limit counters move to Redis: "Counters go to Redis, not in memory." (Mara)
EVIDENCE
- Load test: p95 at 140 ms with the Redis backend (msg#41).
OPEN QUESTIONS
- Shard Redis once traffic doubles? Deferred, not discarded.
CONSTRAINTS
- "No request may wait longer than 200 ms for the limiter."
VERBATIM
- `rate_limit: { backend: redis, burst: 200 }`
NEXT STEPS
- Measure counter consistency during a Redis failover.
- Check the config draft against the Redis decision (derived)
DISCARDED
- Memcached: no atomic counters across nodes.

• Double quotes go only around exact words from the conversation; a decision or constraint a person set appears that way, in their own words.

• A measured value is evidence, not a target. A deferred option stays open instead of discarded.

• The summarizer marks its own inference with (derived).

In the optional modes Cairn masks code fences, inline code and the values passed as exactSpans before the model call and restores them byte-exact afterwards (a marker the model drops stays dropped). Values passed as requiredVerbatim are checked in every mode: the result lists any that are missing from the brief. A new handoff supersedes the previous one, so the ledger stays lean and decision_log view=current carries only the most recent brief, without evidence. The held blocks are stored as evidence; decision_log view=all with withEvidence returns them byte-exact.

In the optional modes Cairn checks each quote of three or more words against the source: in one piece, at word boundaries, without a dropped negation. A quote it cannot find is listed in the result and noted at the end of the stored brief. On resume, an unquoted or derived constraint is checked against the code, or the user is asked, before it stops or redirects the next step.

📊 Measured, Not Assumed

Which model Cairn recommends, and how its prompt reads, comes from runs with the real models through the claude and codex CLIs. ADR-0012 and ADR-0013 document each run with its numbers and limits.

The calibration pipeline

1. Five golden probes with ground truth; code and IDs are masked as [[CAIRN-HOLD-n]].

2. Each of the seven pool models compacts every probe at effort high; the blocks are restored byte-exact.

3. Six foreign reviewers judge each brief, no model reviews itself. The score covers recall, hallucination, supersession and verbatim.

4. Two runs are pooled and each reviewer's leniency is taken out.

5. That gives the fidelity per model in the profiles, and the selection works from it: top band, cheapest, zone floor.

Fidelity per model

Selection takes the models within 0.02 of the best one in the ecosystem the brief is written in (the host's; in bridge and API mode the CLI's or the endpoint's) and picks the cheapest of them that clears the zone's floor: Claude Opus 5.5 ($4/$20 per MTok) over Fable 5.1 ($10/$50), GPT-6.1 Sol ($2/$10) over GPT-6 Astra ($10/$50). If that model misses the floor, the next band model that clears it is selected, and verbatim remains only when no band model clears it. Zones raise the floor (yellow +0.05, red +0.10); at 0.84 both picks clear even the red zone, so the selection names a model instead of falling back to verbatim. Without Opus 5.5 a Claude host gets Haiku 5.5 in green and yellow and Fable 5.1 in red. Compare fidelity within one ecosystem: GPT reviewers rate GPT briefs about 0.02 higher than Claude briefs, and the correction does not remove that.

Golden set of 2026-10-12, two runs at effort high, pooled, each reviewer's leniency taken out by a least-squares fit (ADR-0012). In every golden brief all seven models kept every verbatim marker and every key fact (five of them only inside the verbatim blocks), so the deterministic key-fact check does not tell the models apart; the reviewers' scores do.

Grounded briefs

The first measurement of the 2.0 prompt looked worse, because the reviewers saw only the ground truth: a true detail or a quote that the ground truth does not list read as invented, and 596 of 630 reviews took points off without naming anything. Now the reviewers of the golden set see the source and name each item they score as invented. Re-scored that way on 2026-10-15, the same stored briefs give the 2.0 prompt the higher score: 20 briefs higher, 4 lower, 11 equal (sign test p ≈ 0.002), with recall and verbatim held. Much of the gain comes from two kinds of mistakes the 2.0 prompt makes less often: next steps the source does not name, and masked content called a placeholder (ADR-0013 has the breakdown). In an end-to-end handoff, neither Opus 5.5 nor GPT-6.1 Sol wrote the invented lines the old prompt had produced.

Each brief is scored by 6 reviewers. 2.0 prompt: 35 briefs. Prompt before 2.0: two golden runs of 35 briefs, pooled (they differ by 0.0026 when re-scored).

Every real run for 2.0

A call is one CLI run (claude -p or codex exec). The Codex window check and the 2026-10-13 handoff are counted from the rollouts and briefs ADR-0012 and ADR-0013 describe; the calibration of 1.x is not included.

🧪 Tests

• Strict TypeScript and Vitest, all offline: model calls go through injectable seams, so the tests never reach a provider.

• Recall key matching (242 tests) holds the deterministic key-fact check to 133 paraphrases and look-alikes from three review rounds, in German and English.

• Grounded briefs: the quote check is tested on negations, clause ends, nested quotes and escaped text, with time limits on inputs of up to about 2 MB.

• Calibration without a model call: npm run calibrate -- --dry-run --golden runs the whole pipeline on a fixture compactor and a heuristic reviewer and prints how many calls a live run would make.

Areas: vitest run at v2.0.0. Growth: vitest list at each commit on main up to the tag.

🧱 Core Principles

🛠️ The Four MCP Tools

The zones are deliberately simple:

Claude Code shows the zone in its statusline, from the status JSON it passes on stdin; Codex through the shell commands below. Neither needs an MCP call; context_status returns the zone on request.

🖥️ Codex Ambient Zone & Shell Commands

Codex has no statusline API. Cairn reads the local rollout files read-only and shows the zone ambiently, in the terminal or window title:

cairn status      # one line, e.g.  🟢 21% ctx · gpt-6.1-sol
cairn window      # live zone strip as a second pane (Windows Terminal / tmux / iTerm2)
cairn tab         # zone in the terminal/tab title · 'cairn stop' ends it
cairn list        # most recently active Codex sessions (pin with --session <uuid>)

Details and tmux/zellij snippets: integration/codex/ambient-zone.md.

📦 Installation

Detects Claude Code and Codex best-effort and installs only what makes sense on your system. Existing configuration is augmented via marked blocks or merged JSON sections, no foreign project files are rewritten.

npm install
node dist/server.js install

What install sets up:

• The language in ~/.cairn/config.json: --lang en|de, else a prompt, else en.

• Claude Code (~/.claude exists or claude is on PATH): the Cairn statusline in settings.json (old Cairn hooks removed, foreign hooks kept), the four skills cairn, cairn-handoff, cairn-resume, cairn-help, and claude mcp add cairn --scope user with CAIRN_DB. Without claude on PATH the command is printed.

• Codex (~/.codex exists or codex is on PATH): [mcp_servers.cairn] in config.toml, a marked Cairn block in AGENTS.md, the same four skills in ~/.agents/skills.

• Shell profiles (PowerShell, .zshrc, .bashrc): cairn window, tab, stop, status, list.

If neither host is found, nothing else is installed.

node dist/server.js uninstall removes Cairn's statusline and old hooks, the four skills, the MCP registration, the [mcp_servers.cairn] and AGENTS.md blocks and the shell shortcuts. The language setting and the ledger stay.

/plugin marketplace add /ABSOLUTE/PATH/cairn
/plugin install cairn@cairn

The plugin ships the MCP server and explicitly invoked skills, with no automatic hooks. For the full statusline, the self-installer is still the easiest path.

Claude Code:

claude mcp add cairn -- node /ABSOLUTE/PATH/cairn/dist/server.js

or as .mcp.json:

{
  "mcpServers": {
    "cairn": {
      "type": "stdio",
      "command": "node",
      "args": ["/ABSOLUTE/PATH/cairn/dist/server.js"],
      "env": { "CAIRN_DB": "${HOME}/.cairn/cairn.sqlite" }
    }
  }
}

Codex in ~/.codex/config.toml:

[mcp_servers.cairn]
command = "node"
args = ["/ABSOLUTE/PATH/cairn/dist/server.js"]
startup_timeout_sec = 30
tool_timeout_sec = 60

Then append integration/codex/AGENTS.cairn.md to ~/.codex/AGENTS.md. Copy .agents/skills/ into ~/.agents/skills/ for Codex (including agents/openai.yaml), or skills/ into ~/.claude/skills/ for Claude Code. Ready-made snippets are in integration/.

Updating an existing installation

After updating your checkout (git pull), run npm install and node dist/server.js install, then restart Claude Code / Codex. This refreshes the marked Cairn block in AGENTS.md and the skills, including Codex's allow_implicit_invocation: false policy. Claude skills use disable-model-invocation: true. The installer removes old Cairn SessionStart/PreCompact commands while retaining foreign hooks. Legacy hook executables are silent no-ops after the build, even before reinstallation. The existing ledger is retained. For manually copied project instructions/skills, replace the old Cairn block/copies too; old guidance otherwise remains active in that project.

⚙️ Configuration

Language: Cairn is English by default. German is selectable at install via cairn install --lang de (an interactive Language / Sprache? [en]/de prompt appears when no flag is given), and per-session via the CAIRN_LANG=en|de env var (the env var overrides the install choice).

Condensation Modes

In every mode the handoff result also names the most faithful summarizer (Claude Opus 5.5 or GPT-6.1 Sol, in the ecosystem the brief is written in) unless it wrote the brief or already is the model Cairn asked for, and, after your session model or an endpoint's model, how to switch to it. A gemini endpoint gets no recommendation (details in ADR-0012).

The bridge runs claude -p or codex exec in a neutral working directory and keeps no session: claude without tools, MCP tools, CLAUDE.md or user hooks, codex in a read-only sandbox with its config.toml ignored. In API mode the key is read from the environment at call time.

Without explicit configuration, Cairn refuses all non-account paths.

🧮 Model Coverage

Cairn reads each model's context window from its profile and caps it with the window the host reports (min(model_max, surface_cap)). For a model it does not know, the host-reported window is used as is.

These decorations resolve to the base entry: [1m], @effort, provider and region prefixes (anthropic., us./eu./global./us-gov.anthropic., openai/), dated snapshots, and suffixes after a -, . or : separator such as -codex. The longest known id wins, so gpt-5.5-pro stays GPT-5.5 Pro.

🔐 Data & Privacy

• Ledger: ~/.cairn/cairn.sqlite (or CAIRN_DB)

• Append-only: decisions are superseded, not deleted

• stdout stays reserved for MCP

• No backend, no telemetry, no cloud sync

• Default account mode needs no API keys and makes no model call in the server

🧑‍💻 Development

npm run typecheck    # tsc --noEmit, strict
npm test             # vitest
npm run build        # tsc -> dist/
npm run dev          # MCP stdio server locally

Calibration (see ADR-0012):

npm run calibrate -- --dry-run --golden               # whole pipeline offline, prints the live call count
npm run calibrate -- --real --golden                  # all seven pool models at effort high, on your accounts
npm run calibrate -- --pool <artifacts>               # pool golden runs, no model call
npm run calibrate -- --real --rereview <artifact>     # score a golden run's stored briefs again

Cairn cannot override a Claude Code effort cap (maxEffortLevel in your user or managed settings, an Enterprise role cap) or a managed env setting, so make sure none of them sets less than high before a live run.

🗂️ Project Structure

src/
  server.ts       MCP server + CLI dispatch
  core/           model profiles, selection, zones, providers, bridge, verbatim, quote check
  tools/          MCP tool implementations (handoff, decision_log, context_status, host_status)
  store/          SQLite ledger (append-only)
  surface/        Claude statusline, Codex rollout reader
  install/        self-installer + shell shortcuts
  i18n/           English and German message catalog
  calibration/    golden set, reviewers, scoring, calibration CLI
  bin/            statusline and Codex helpers, legacy hook no-ops
skills/           Claude Code skills (cairn · resume · handoff · help)
.agents/skills/   the same skills for Codex
integration/      manual Claude/Codex configuration + snippets
docs/adr/         binding architecture decisions
docs/calibration/ calibration probe and ground truth

⚠️ Known Limits

• Zone boundaries are provisional.

• Codex rollout parsing depends on an internal, unversioned Codex format.

• Login detection is best-effort.

• Account mode has no source to check quotes against: the session model writes the brief.

📄 License

MIT © 2026 CheswickDEV