<div align="center">

🪨 Cairn

AI Context Continuity Engine

A local-private context-handoff tool for long agent sessions. Cairn warns you about context rot, preserves decisions + evidence, and hands a faithful 7-bucket brief to the next session, or the next model.

<br/>

<kbd>MCP stdio</kbd> · <kbd>SQLite Ledger</kbd> · <kbd>Account Mode</kbd> · <kbd>Claude Code</kbd> · <kbd>Codex</kbd> · <kbd>No Telemetry</kbd> · <kbd>Node ≥ 22</kbd>

<br/>

Cairn resume &nbsp;·&nbsp; Cairn Handoff &nbsp;·&nbsp; Cairn Help

v1.4.0 · MIT License

</div>

✨ The Problem

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.

🧭 How It All Fits Together

flowchart LR
    host["Host agent<br/>Claude Code or Codex"]
    handoff["handoff"]
    fv["freezeVerbatim<br/>code, IDs, values"]
    ledger[("Local SQLite ledger")]
    next["Next session<br/>or another model"]
    server["cairn stdio server (MCP)"]
    cs["context_status<br/>green / yellow / red"]

    host -->|"host-produced brief"| handoff --> fv --> ledger
    ledger -->|"decision_log view=current"| next
    host -->|"MCP tools"| server --> cs

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.

⚡ In 30 Seconds

git clone <repo-url> cairn
cd cairn
npm install
node dist/server.js install      # detects Claude Code + Codex, wires up both best-effort

Then just say it in chat:

To undo: node dist/server.js uninstall

🧱 Core Principles

The binding architecture is documented in docs/adr/ADR-cairn.md.

🛠️ The Four MCP Tools

The zones are deliberately simple:

📋 The 7-Bucket Brief

Every handoff follows the same format:

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

Mandatory values, IDs, paths, code fences, and inline code are passed as requiredVerbatim / exactSpans. Cairn masks them with [[CAIRN-HOLD-n]] before any optional condensation and restores them afterward byte-exact. A new handoff supersedes the previous one, so the ledger stays lean and decision_log view=current carries only the most recent brief.

🖥️ 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-5.5
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

<details open> <summary><b>Path A: Self-installer (recommended)</b></summary>

<br/>

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

</details>

<details> <summary><b>Path B: Claude Code plugin</b></summary>

<br/>

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

The plugin ships the MCP server, skill, and hooks. For the full statusline, the self-installer is still the easiest path.

</details>

<details> <summary><b>Path C: Manual (Claude Code / Codex)</b></summary>

<br/>

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 and place the skills under skills/ into ~/.agents/skills/ or ~/.claude/skills/. Ready-made snippets are in integration/.

</details>

⚙️ 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

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

🔐 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

🗂️ Project Structure

src/
  server.ts       MCP server + CLI dispatch
  core/           model profiles, zones, providers, verbatim
  store/          SQLite ledger (append-only)
  tools/          MCP tool implementations
  surface/        Claude/Codex surface logic
  install/        self-installer + shell shortcuts
skills/           agent skills (cairn · resume · handoff · help)
integration/      manual Claude/Codex configuration + snippets
docs/adr/         binding architecture decisions

✅ Status v1.4.0

• MCP core with four tools + SQLite decision/evidence ledger
• Account mode as the default (no egress)
• Claude Code statusline & hooks · Codex ambient zone via rollout reader
• Named trigger skills: Cairn resume · Cairn Handoff · Cairn Help
• Lean ledger: a new handoff supersedes the previous brief
• Strict TypeScript + Vitest
• English-primary, with selectable German for both commands (cairn install --lang de) and runtime output (CAIRN_LANG=de)

Known limits: zone boundaries are provisional; Codex rollout parsing depends on an internal, unversioned Codex format; login detection is best-effort.

📄 License

MIT © 2026 CheswickDEV