Cairn Remembers

Cairn

[License: BUSL-1.1] [Python 3.11+] [PyPI] [Patent pending] [Local-first]

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.

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 installpip 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/cairncd 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 = 30tool_timeout_sec = 120default_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).

Applies to every AI above:

• Wiring is one-time. New chats just remember — you never activate per chat. orient reads memory; it never switches anything on. Scope varies by wire: Claude Code hooks are machine-wide (or one project via cairn connect); Desktop/Cursor and Codex live in each app's own config, per account.
• Only NEW chats pick up new wiring — finish wiring, then open a fresh chat. (Long-lived MCP clients re-read the tools only on a full restart.)
• Privacy controls: skip one chat — CAIRN_CAPTURE=0 in that shell (PowerShell $env:CAIRN_CAPTURE="0" · cmd set CAIRN_CAPTURE=0 · bash export CAIRN_CAPTURE=0) · pause everywhere: cairn capture off / on · secrets scrubbed before write (append-only, fail-closed).
• Undo: cairn disconnect [--global] · cairn codex-hook uninstall · re-run cairn setup to review.

What you get

• One vault, every model. Any agent that speaks MCP or can run cairn reads and writes the same memory — so one agent builds on what another wrote, even across rival vendors.
• Keep your place across a usage cap. Hit a limit on one model, continue on another, and point it at where you left off — the trail is in the vault, not in one model's context.
• Captured as you work — decisions, dead ends, tool calls, and turns become searchable nodes, from the moment you wire it.
• Nothing worth keeping disappears. Every captured turn stores its complete text: search results are gists — an index — cairn read <id> prints any node in full, and MCP cairn_read pulls it whole with a raised max_chars.
• A local maintenance pass you run — cairn sleep, nightly by habit or on your own scheduler (it doesn't schedule itself): embed → consolidate → prune → rebuild the graph → compile, all on your machine. One exception to "no network": the very first embed downloads the ~80 MB model, once.
• A map of your thinking — the dashboard galaxy (cairn dashboard → http://127.0.0.1:7331), plus a human-readable Hub / Book / Index.
• Backfill — distill old conversations into sharp, connected claim nodes.

Advanced install

# Linux / WSL: install the CPU-only PyTorch first, or pip pulls a ~4.6 GB CUDA# stack you don't need. (Want a GPU build? Install your torch first, then run the# line below — it's preserved.) macOS: skip this line — its default wheel is CPU/MPS.pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -e ".[all]"      # package + embedder + dashboard

pip install -e ".[embeddings]"   # no dashboardpip install -e ".[dashboard]"    # no embedder

python3 -m venv .venv && source .venv/bin/activate && ./install.sh

Multiple accounts

One login per AI? Skip this — it just works. Each AI signs in with its own account, and Cairn files that AI's work under its own galaxy automatically — Claude and GPT never mix, with zero setup.

Read on only if you run two accounts of the same AI (two Claude logins, two ChatGPT/Codex logins — say, personal and company). Galaxies are keyed to each login's stable id and never merge — but with two same-AI logins on one machine, Cairn can't always prove which one is active. The rule that keeps it clean:

Declare, don't detect: set CAIRN_ACCOUNT per account, up front.

# Claude Code — launch each account with its label:export CAIRN_ACCOUNT=work && claude        # bash/zsh (or set it in that profile)#   PowerShell: $env:CAIRN_ACCOUNT="work"; claude# Codex — put it in that account's ~/.codex/config.toml:#   [mcp_servers.cairn]  env = { CAIRN_ACCOUNT = "work" }# Importing old history? Always pass the flag:cairn import <export> --source=claude --account=work

Name and manage them anytime:

cairn account                          # list galaxies + node countscairn account rename <key> "Company"   # display label only — never merges or deletescairn account doctor                   # read-only check — prints the exact fix command per mismatchcairn account fix-session <session-id> <slug>   # re-file ONE named session (backed up, then locked)cairn account fix-session <slug>                # same, for the current session only

Honest limits — so you're never surprised:

• Claude Desktop proves the active account per session automatically. Claude Code CLI and Codex can't — they follow the machine's current login file, so an account switch mid-stream can label sessions with the previous account, silently. CAIRN_ACCOUNT is the guarantee; detection is not.
• account doctor verifies what's provable (Claude Desktop sessions); it can't audit pure-CLI or Codex history.
• Append-only applies here too: renames change display labels only; nothing merges, nothing deletes.

What to back up

One folder: your vault at ~/.cairn/ (that's cairn.db — your actual memories). Back that up. Everything else is replaceable — the code lives here on GitHub, and reinstalling never touches your vault.

Common commands

orient · note · fetch · wander · query · read (any node in full) · dashboard · doctor · setup · connect / disconnect / capture · account · backfill · sleep (the maintenance cycle — you run it) · edges · book · import

Full reference with every option: QUICKSTART.md.

License

Free for personal and non-commercial use under the Business Source License 1.1 — read it, run it, modify it, self-host it. Commercial or business use requires a commercial license — email [email protected]. Source-available (not OSI "open source"); each release converts to the permissive MIT License on the Change Date in its LICENSE.

Patent pending — a U.S. provisional patent application covering Cairn's core mechanisms was filed 2026-07-07. Cairn Remembers™ is a trademark of James Wescott Maitland IV.

Knowledge is a trail, not a destination.