Cairn

Build knowledge. Leave signals. — Tools for modern explorers.

Local-first episodic memory for AI agents — and for you.

A cairn is a stack of stones that marks a trail. This one marks the trail of your thinking: every decision, dead end, and reason becomes a node you — and any model — can find again, across sessions and across model generations.

• Local-first — everything lives in one SQLite file at ~/.cairn/. No cloud, no account, no telemetry.
• Model-agnostic — any agent that runs a shell command or speaks MCP: Claude, GPT/Codex, Gemini, local models.
• Append-only — memories are voided, never deleted. The record is the record.
• Yours — Cairn sends nothing off your machine. Your chat still goes to whatever model you chose, exactly as it would without Cairn — use a local model and nothing leaves at all.

Two ways in:

• 🧑 A person setting this up? Keep reading — Quick start takes about 5 minutes. Every option and fix: QUICKSTART.md.
• 🤖 An AI agent installing Cairn for someone? → SETUP_FOR_AGENTS.md is written for you (install, consent, attribution).

See inside Cairn

Keep the decisions, reasons and unfinished work you want to return to. Cairn stores them in a local vault that you and your connected AI tools can read and add to. Each AI keeps its own memory and context. These demos show the optional dashboard for exploring the record.

Hub	Projects	Connections
Pick up unfinished work.	Keep related work together.	Explore linked memories.

Explore all five demos and descriptions.

• Hub — 9 seconds
• Projects — 18 seconds
• Index — 6 seconds
• Live Feed — 14 seconds
• Connections — 8 seconds

Recorded in a local installation. Private text uses examples; controls and source attribution are retained. The filmed installation has not been verified against every control in release 0.3.3. Demo descriptions and recording notes.

Contents

• Quick start
• Wire up your AI
• What you get
• Advanced install
• Multiple accounts
• What to back up
• Common commands
• License

Quick start

Two places, never mixed up: 🖥️ Your terminal (PowerShell / Terminal) — every command on this page runs here, on your computer. Wiring is always a terminal command or a config-file edit — an AI can run those terminal steps for you (that's the fastest path below), but wiring is never something you paste into the chat box. 💬 The AI chat — where memory shows up, and where you test the wiring by asking the AI to use it.

Fastest — let your AI do it

Open Claude Code, Codex, or Cursor and paste:

Install and set up Cairn for me from https://github.com/CairnRemembers/cairn

Your AI runs the terminal steps and asks before switching memory on — one yes/no per AI on your machine, default No. Nothing records without your yes. (Using Codex? There's one extra paste after that — see Wire up your AI.)

Or do it yourself

1 — Install 🖥️ (installs software only — records nothing, the vault starts empty)

⚠️ Installing [all] on Linux / WSL? Run pip install torch --index-url https://download.pytorch.org/whl/cpu first, or pip pulls a multi-GB CUDA torch stack you don't need. Windows and macOS torch wheels are already CPU-only.

pip install cairn-remembers            # base install
pip install "cairn-remembers[all]"     # + embedder + dashboard

From source

Still the richer path — the installer handles the CPU-torch step for you:

Get the code 🖥️

git clone https://github.com/CairnRemembers/cairn
cd cairn

Run the installer 🖥️

# Windows:      .\install.ps1      (blocked? powershell -ExecutionPolicy Bypass -File .\install.ps1)
# macOS/Linux:  ./install.sh

The installer finds Python 3.11+, installs everything (first run downloads PyTorch — the lean CPU build on Linux/Windows, a few minutes), and checks itself.

2 — Wire up your AI. This is where memory actually turns on, and each AI needs different wiring — a y in setup finishes the job for Claude Code, but not for Codex or Claude Desktop. Find your AI below and follow it to its ✅.

Wire up your AI

Cairn has two separate wires, and knowing the difference prevents every common surprise:

• Capture — your chats get remembered automatically (writes to the vault).
• Tools — the AI can search and note your vault from inside the chat (reads + on-demand writes).

Some AIs need one wire, some need both. Don't stop at the first ✓ — follow your AI to its ✅ line.

Claude Code — one command

🖥️ In the terminal:

python -X utf8 -m cairn setup        # answer y for Claude Code

That wires capture: every new Claude Code chat auto-orients (you'll see the banner), records as you work, and compiles when it ends. Machine-wide, one-time, reversible (cairn disconnect --global). Prefer one project only? Run cairn connect inside that repo instead (global and per-project are mutually exclusive — doctor flags it).

✅ Done when: a new chat opens with a "CAIRN — inherited context" banner, and 🖥️ python -X utf8 -m cairn doctor shows ✓ capture.

Optional — native tools: Claude Code can already read the vault by running cairn commands in its shell. For native cairn_* tools instead, register the MCP server user-wide, pointing at the Python that can import cairn (a bare python that can't is the #1 failure — prove the path first, QUICKSTART §6a):

claude mcp add --scope user cairn -- <full-path-to-python> -X utf8 -m cairn mcp

💬 Proof: ask the chat to "call cairn_orient". (doctor can't see this wire — the ask is the test.)

OpenAI Codex — three pieces, each does a different job

1. Capture 🖥️ — python -X utf8 -m cairn setup → y for Codex (= codex-hook install). Captures turns live as Codex fires notify (deduped by turn id). For a comprehensive sweep of everything on disk, run 🖥️ python -X utf8 -m cairn import codex-sessions --apply anytime.
2. Tools 📄 — add to ~/.codex/config.toml, then fully restart Codex (full §6 walk-through):

[mcp_servers.cairn]
command = "<full-path-to-python>"
args = ["-X", "utf8", "-m", "cairn", "mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "approve"

3. Habit 📄 — create ~/.codex/AGENTS.md and paste the memory protocol from QUICKSTART §6c so Codex orients, fetches, and notes unprompted. (Needs piece 2 — the protocol calls those tools.)

✅ Done when: 🖥️ python -X utf8 -m cairn codex-hook status prints INSTALLED, and 💬 a Codex chat answers "call cairn_orient" with a digest (with piece 3, its first reply starts [cairn: oriented — N]). ⚠️ Honest note: cairn doctor structurally detects Codex MCP registration (the [mcp_servers.cairn] block), but it does not prove the server launches or that the notify hook captures — the checks above are the real proof of those.

Claude Desktop / Cursor — one paste

📄 Add to claude_desktop_config.json (or Cursor's MCP settings), then restart the app:

{
  "mcpServers": {
    "cairn": { "command": "python", "args": ["-X", "utf8", "-m", "cairn", "mcp"] }
  }
}

That's the tools wire — search, fetch, wander, note from inside the chat. These surfaces have no ambient capture; what you ask the AI to cairn_note is what lands. (If the app can't find Python, use the full path of the Python that installed Cairn.)

✅ Done when: doctor shows ✓ MCP — registered in Claude Desktop config (Desktop), or 💬 the "call cairn_orient" smoke test answers (Cursor).