✨ 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

npm install
node dist/server.js install

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

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

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

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

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