cairntir 1.3.0

Host-neutral memory-first reasoning layer for AI coding agents.

Cairntir

One evolving memory for Codex, Cursor, Claude Code, and every MCP agent.

Cairntir is a local-first, open-source memory system for Codex, Cursor, Claude Code, and every other Model Context Protocol client. It kills cross-chat and cross-agent AI amnesia: a lesson written through one host is available to the next. Evidence stays verbatim, while an append-only Discovery Ledger exposes what Cairntir is learning instead of hiding it in an opaque optimization loop.

A stack of stones that sees across time.

Cairntir = cairn (stacked waypoint stones marking a path) + palantír (seeing-stone across time and distance). Pronounced CAIRN-teer.

---

The one-minute pitch

Every time you open a new Claude Code chat, Claude forgets everything from the last one. You explain the same architectural decision again. You re-litigate yesterday's trade-off. You hallucinate a reason for a choice you can't remember making. It's the single biggest productivity tax on working with LLMs day-to-day, and it's fixed by a file.

Cairntir is that file. It's a SQLite database on your hard drive that stores every decision, fact, and hard-won lesson Claude writes down — verbatim, forever, no summarization — and gives it back the next time you open a chat. Every session, in every project, on day 30, walks into a lit room.

It ships as an MCP server, so it works with Claude Code, Claude Desktop, Cursor, Windsurf, and every other MCP-compatible client without modification.

And it is built for a hard monthly ceiling, not an expense account. The design rule is never return a token the model cannot use — because on a $20 plan, context you paid for and can't read is the expensive kind.

---

Install

pip install cairntir           # live on PyPI
cairntir setup                 # initialize the store + Claude Code
cairntir init --host all --user # connect Codex, Cursor, and Claude Code

Restart the configured hosts. Cursor's global MCP entry is installed automatically, but its global User Rule must be pasted into Cursor Settings → Rules → User Rules because Cursor does not publish a file-backed global-rule surface. Project-local Cursor setup is fully automatic: cairntir init --host cursor.

Once installed, Cairntir stays on. Every cairntir CLI invocation silently re-verifies the user-scope MCP registration and re-registers the stable cairntir-mcp launcher if Claude Code can't find it. Moving venvs, upgrading Python, or reinstalling no longer breaks the wiring — pip install cairntir is TRUE, pip uninstall cairntir is FALSE, nothing in between. When a newer release lands on PyPI, the next CLI run and the next MCP tool response prepend a one-line update banner; nothing is interrupted.

Both side effects are opt-out for CI / air-gapped use:

• CAIRNTIR_DISABLE_AUTOREGISTER=1 — skip the silent self-heal MCP registration.
• CAIRNTIR_DISABLE_UPDATE_CHECK=1 — skip the background PyPI version check and never print the update banner.

Not sure about any of those steps? Read docs/cairntir-for-dummies.md — zero-prior-knowledge getting-started guide.

---

Day 30

This is the whole point. It's why it exists.

You open a Claude Code chat in a project you haven't touched in three weeks. Normally this starts with: "OK, remind me — what are we doing here, which database did we pick, why does auth.py have that weird hack in it, and what was blocking the last PR?"

With Cairntir installed:

1. The chat starts. Claude's system prompt tells it to call cairntir_handoff before answering anything.
2. Cairntir composes one brief: the operating protocol, the last few session deltas in full text, open questions, and — if Claude passes the files it's about to touch — the memory anchored to that code.
3. Claude reads them. It now knows you picked Postgres, why you picked it, what the hack in auth.py is protecting, and what's on next session's list.
4. You type your question. The answer comes back with real context — and drawer id citations, so you can click through to the source.

That's walking into a lit room. That's the North Star. Every feature in this repo is measured against whether it makes that experience feel inevitable.

---

The budget is the feature

A memory layer that dumps everything it has is just a slower way to run out of context. Cairntir's read path is built around one rule:

Never return a token the model cannot use.

cairntir_handoff(wing) returns whole drawers under a hard character budget. Nothing is truncated — a drawer either comes back complete or it is listed by id and size so you can fetch exactly the one you want. Truncation is the anti-pattern here: it pays the full token cost and destroys the information.

Measured against the older session_start, on a real store, 2026-08-02:

wing	session_start	handoff
cairntir	7,737 tok	4,261 tok	−44%
detroit-clone	8,201 tok	3,880 tok	−52%

The saving is the less interesting half. On the cairntir wing, session_start spent its 7,737 tokens on 54 truncated stubs that could not answer anything; handoff spent 4,261 on 9 complete drawers that could, and named the 13 it skipped so you could fetch any of them deliberately. Cheaper and usable is the only version of cheaper worth having.

Those are one store on one day, not a benchmark. session_start grows with the wing, so the gap widens as a project accumulates history — which is exactly when you need the budget. Run cairntir cost on your own store rather than taking these numbers as a promise.

It is deterministic — no ranking, no embedder, pure SQL — so repeat calls are byte-identical and stay friendly to your host's prompt cache.

And you can audit it yourself, which is the point:

cairntir cost myproject

That reports what the tool catalog, session_start, and handoff each cost, plus how much of your corpus exceeds the embedder's input window. Cairntir measures its own overhead rather than asking you to trust it.

---

Why this and not the other ones

	Cairntir	MemPalace	Ad-hoc CLAUDE.md files
Verbatim storage	✅	✅	✅
Wing / room / drawer taxonomy	✅	✅	❌
4-layer retrieval (identity / essential / on-demand / deep)	✅	✅	❌
Semantic search	✅ sqlite-vec	✅	❌
Prediction-bound drawers (claim → predicted → observed → delta → supersedes)	✅	❌	❌
Belief-as-distribution ranking (reinforce / weaken, surprise-weighted)	✅	❌	❌
Portable signed format (content-addressed, HMAC-signed, gossip-able)	✅	❌	❌
Consolidation + forgetting curve (sleep-cycle pass, contradiction detection)	✅	❌	❌
Library seam (Protocol surface + contract test suite for custom backends)	✅	❌	❌
Clean-ports Reason loop (LLM-agnostic, testable without network)	✅	❌	❌
Budgeted handoff (whole drawers under a hard ceiling, never truncated)	✅	❌	❌
Self-measured token cost (cairntir cost audits its own overhead)	✅	❌	❌
MCP server	✅ stdio	✅	❌
One-command install wizard	✅ cairntir setup	❌	N/A

Cairntir borrows MemPalace's taxonomy — credit where due — and layers on the reasoning discipline the round-table of eight thinkers committed to in the v0.2–v1.0 arc. See docs/lineage/mempalace.md for the full "what we kept, what we didn't" breakdown.

---

The six moving parts

1. Drawer — one verbatim memory entry. Content, metadata, retrieval layer, optional prediction fields (claim, predicted_outcome, observed_outcome, delta, supersedes_id), belief mass. Frozen pydantic model.
2. DrawerStore — SQLite + sqlite-vec backend. Forward-only schema migrations (v1 → v6 so far), with explicit embedding identity, immutable provenance, durable workflow receipts, and backup-first migration/reindex. Contract-tested via tests/contract/test_store_contract.py.
3. MCP server — 19 tools over stdio: exact memory, scoped and cross-wing recall, structural recall for a set of changed files, the budgeted handoff brief, session start, timeline, audit, Crucible, Discovery Ledger/calibration, and CodeGlass operations. Runs via python -m cairntir.mcp.server.
4. Three skills — crucible (stress-test assumptions), quality (audit a wing), reason (memory-backed thinking loop with a mandatory predict step). Bundled as markdown, loaded via importlib.resources.
5. Reason loop — ReasonLoop.step() over four Protocol ports (HypothesisProposer, ExperimentRunner, BeliefStore, MemoryGateway). Testable without LLMs, networks, or SQLite. See docs/integration-guide.md.
6. Discovery Ledger — evidence-backed signals move through signal → candidate → corroborated → promoted/rejected/expired as append-only drawers. Repeated Reason episodes can propose calibrated candidates but cannot promote themselves. Active discoveries appear at session start; cairntir learning-log gives the human-readable learning history.

---

Who it's for

• Solo developers who work with Claude Code daily and lose an hour every Monday re-explaining Friday's decisions.
• Small teams that want a per-developer memory layer today and a portable, gossip-able shared memory tomorrow (the v0.5 portable format makes team sync a file-copy, no server).
• Tool builders embedding Claude or an MCP client in their own product. Cairntir's v1.0 contract is a stable Protocol surface you can implement a custom backend against — Redis, Postgres, a hosted vector DB, whatever you already run.
• Researchers tracking which hypotheses held, which failed, and by how much. The prediction-bound drawer schema (v0.2) is a log-structured experiment journal; the belief-as-distribution scorer (v0.4) is the scoreboard.
• People building toward post-scarcity manufacturing. Yes, really — see the horizon at the bottom of this README.

---

Compatible with

Cairntir is an MCP server. Anything that speaks Model Context Protocol can talk to it unchanged:

• Codex, Cursor, and Claude Code (first-class hosts sharing one store)
• Claude Desktop
• Cursor
• Windsurf
• Zed (MCP client support rolling out)
• Any other MCP-compatible client

Pairs naturally with:

• Git hooks — auto-capture commit messages as drawers via the daemon's spool directory.
• Obsidian / Anthropicer — project the learning log and verified CodeGlass walkthroughs one-way with cairntir obsidian-project; SQLite stays authoritative and human notes are preserved.
• Linear / GitHub issues — daemon picks up mentions and cross-references to drawer ids.
• VS Code — decision-marker extension (planned, not shipped) writes to the spool as you type.

---

Recipes — protocols built on the three skills

Cairntir's core surface is three skills (crucible / quality / reason) and a memory layer. Recipes chain those primitives into repeatable protocols for specific use cases without expanding the skill set. They live under docs/recipes/.

Signal Reader — structural analysis of AI news

Read under the news cycle. Split the headline story from the structural story, name the constraint that actually moved, project gains and losses, stress-test through Crucible, write the result as a prediction-bound drawer in a signals wing. Every committed read carries a falsifiable claim; the belief-as-distribution scorer tracks your calibration across months.

Nate-style one-shot structural reads produce analysis. Cairntir's version produces compounding analysis — three months of committed reads tell you which constraint categories you read well and which you consistently miss.

Recipe: docs/recipes/signal-reader/ Worked example: march-2026.md — five structural reads run through the full protocol, formatted as prediction-bound drawers ready for cairntir_remember. Trigger: "signal-read this", "what's the structural story?", "run the fog protocol".

Decision Replay — close the loop on a past call

cairntir replay <id> walks the supersedes chain from a decision, pulls the leaf's claim and predicted outcome, asks what actually happened, and writes the result back onto the chain as a new prediction-bound drawer with a Crucible marker. It is how a guess from three months ago becomes a scored one.

Recipe: docs/recipes/decision-replay/

CodeGlass — turn unfamiliar code into durable understanding

Evidence-cited five-part walkthroughs, immediate and delayed teach-back, and retention tracking, so reading a codebase produces something that survives the session. Built for people who ship useful software without formal CS training.

Recipe: docs/recipes/codeglass/

More recipes will land as patterns prove themselves. The governance rule is firm: three skills, unbounded recipes, never a fourth core primitive.

---

Example: what lives in a Cairntir database

cairntir recall "database decisions" --wing myapp

#12  [essential]  we picked Postgres over SQLite for the live tier
                  reason: SQLite couldn't handle the concurrent-write
                  pattern we measured in load testing on 2026-01-15
                  cited by: #47 #91 #103

#47  [on_demand]  followup: connection pooling broke at 500qps
                  observed_outcome: pgbouncer in transaction mode fixed it
                  supersedes: #18 (wrong prediction about prepared statements)

#91  [on_demand]  migration 0042 was safe because rows < 50M
                  claim: ALTER TABLE ... ADD COLUMN NOT NULL is safe
                    at this scale
                  predicted_outcome: no downtime
                  observed_outcome: no downtime, 3s lock window

#103 [deep]       original pre-Postgres analysis from 2025-12
                  (demoted by the forgetting curve)

Every one of those is the literal text Claude wrote during a session you had weeks ago. Nothing is summarized or interpreted. If you want to know why you made a decision, the decision is right there, timestamped, citable, and searchable.

---

Project structure

cairntir/
├── src/cairntir/
│   ├── __init__.py         # v1.0 public protocol surface — the stable seam
│   ├── contracts.py        # Store protocol every backend must satisfy
│   ├── impl/               # Concrete impls — reserved right to change
│   ├── memory/             # DrawerStore, belief scorer, consolidate, embeddings
│   ├── reason/             # ReasonLoop + four Protocol ports
│   ├── mcp/                # Host-neutral MCP stdio server
│   ├── portable.py         # Signed envelope format (v0.5)
│   ├── skills/             # crucible.md, quality.md, reason.md
│   ├── handoff.py          # Budgeted brief composition — whole drawers only
│   ├── cost.py             # What Cairntir's own read path costs
│   ├── daemon/             # Auto-capture spool watcher
│   └── cli.py              # cairntir setup | init | handoff | cost | recall | recall-for-change | anchor | replay | calibration | doctor | status | export | import | migrate
├── scripts/
│   ├── check_release_tags.py         # A changelog entry is not a release
│   └── check_landed_commitments.py   # A plan that promises something must deliver it
├── tests/
│   ├── unit/               # The bulk of the suite
│   ├── contract/           # Store contract suite — every impl must pass
│   ├── property/           # Hypothesis-driven invariants
│   ├── integration/        # MCP backend + daemon
│   └── eval/               # LongMemEval R@5 subset (fail-on-regression CI gate)
└── docs/
    ├── cairntir-for-dummies.md     # Zero-knowledge getting-started guide
    ├── conception.md               # Origin story + ethos + horizon
    ├── concept.md                  # What Cairntir is (the three ingredients)
    ├── manifesto.md                # Why Cairntir exists
    ├── integration-guide.md        # How to embed Cairntir in your own tool
    ├── deprecation-policy.md       # What "stable" means at v1.0
    ├── release-cadence.md          # Commit vs. merge vs. tag, and how a version is chosen
    ├── landed-commitments.md       # How CI verifies a plan actually shipped
    ├── roadmap.md                  # v0.2 → v1.0 arc + beyond
    └── lineage/                    # What we kept from BrainStormer + MemPalace

---

Conception — the 30-second version

Cairntir is the distillation of two predecessors:

• MemPalace — brilliant wing/room/drawer taxonomy, 96.6% LongMemEval R@5, but no reasoning layer. We borrowed the concepts, not the code.
• BrainStormer — the author's prior attempt. Great vocabulary (Crucible, Quality, ETHOS), terrible runtime (224 silent except: pass blocks, "architecture of a learning system, runtime of a static scaffolder"). Preserved as read-only lineage; reimplemented from scratch.

On 2026-04-08, a round table of eight thinkers — Karpathy, LeCun, Sutskever, Hinton, Fuller, Peter Joseph, Alan Watts, Uncle Bob — reviewed the long-road plan and converged on five themes that are now the committed v0.2 → v1.0 arc:

1. Prediction-bound drawers — every drawer carries claim, predicted_outcome, observed_outcome, delta. The gradient when there are no weights.
2. Consolidation + forgetting — verbatim is the floor, not the ceiling. Sleep-cycle pass, replay-weighted demotion, contradiction detection.
3. Surprise as the load-bearing field — store what the system did not expect. Reconstruction error is the learning signal.
4. Portable signed format = anti-capture — format is the product, not the implementation. Content-addressed, HMAC-signed, gossip-importable. A SaaS can be captured. A file on a USB stick cannot.
5. Cut Team Memory as a feature — replicable beats shared. Team capability falls out of the portable format for free.

Full story: docs/conception.md.

---

Standing on other people's work

Cairntir borrows concepts, never code. Every source gets a lineage doc naming the author, what we kept, and — the part that actually matters — what we dropped and why. The doc lands before the feature it credits, so it is structurally impossible to ship first and credit afterward. We never reuse anyone's benchmark numbers as our own, and every lineage doc says plainly when the other project is the better fit.

Source	What Cairntir took	Status
MemPalace by @milla-jovovich	Wing / room / drawer taxonomy, 4-layer retrieval, verbatim storage	Shipped — lineage
BrainStormer (the author's own prior attempt)	Reasoning vocabulary — Crucible, Quality, ETHOS	Shipped — lineage
mattpocock/skills by @mattpocock	The premise that a shared project vocabulary is a first-class artifact	Scoped, not built — lineage
code-review-graph by @tirth8205	Structural recall — memory reachable by what you're changing, not only what you asked	Shipped in 1.2.0 — lineage

On the two current sources, plainly:

mattpocock/skills is the better tool for most people right now. If you want engineering practices your agent will actually follow — test-first discipline, structured debugging, real code review, triage — install his, not ours. Cairntir has no equivalent and isn't building one. The two compose rather than compete: his skills make an agent better within a session, and none of them — none of anyone's — remember anything after that session ends. That gap is the layer Cairntir works on.

code-review-graph is the better tool whenever the question is about your code rather than about your collaboration. What a change breaks, which modules cluster, where the architectural bridges are, risk-scored PR comments — Cairntir answers none of that and isn't going to. It runs happily as a second MCP server alongside Cairntir; that's a supported setup, not a fallback. Cairntir reads what you said about your code, never the code itself.

---

The horizon

This section is mythos, not a commitment. But every contributor deserves to know what Cairntir is ultimately pointed at.

AI + grand-scale 3D printing + post-scarcity tooling.

AI can model anything. Tomorrow, AI will print anything — not just at desktop scale, but at construction scale. Construction-scale 3D printing already exists (WinSun, ICON, Apis Cor). The bottleneck is no longer atoms or machines. The bottleneck is knowledge that compounds across iterations.

Every time a printer runs, it produces data: which temperature worked, which infill density failed, which nozzle wore out after how many meters, which grain orientation was load-bearing. Today, almost all of that data is lost. The next print starts from the same ignorance as the last.

Cairntir is a memory layer that does not care what kind of thing is being remembered. Today it remembers code decisions. Tomorrow, with a Blender MCP plugin or a printer-control adapter, it can remember print parameters and outcomes — per-material rooms, per-iteration drawers, contradiction detection over 20 failed attempts that identifies the one variable nobody was tracking. The MCP surface is already generic. The memory layer does not need to know.

"I'm going to take my chances with the best outcome for earthlings, the environment, and tech, all in one go. And if it doesn't, then I'll still die knowing that I tried." — Patrick McGuire, 2026-04-08

Cairntir is that bet made small. If the bet is wrong, it's still a useful tool that kills a real annoyance for solo developers. That's already enough. If the bet is right, it's an early load-bearing beam in a much larger structure.

Either way, we build.

---

Links

• Why I built this (blog post): docs/blog/amnesia-problem.md
• Getting started (plain English): docs/cairntir-for-dummies.md
• Origin story + ethos: docs/conception.md
• Integration guide (embedding Cairntir in your tool): docs/integration-guide.md
• v1.0 deprecation policy: docs/deprecation-policy.md
• Roadmap: docs/roadmap.md
• Manifesto (the why): docs/manifesto.md
• Ethos: ETHOS.md
• Changelog: CHANGELOG.md

---

Contributing

Read CONTRIBUTING.md and ETHOS.md before opening a PR. The short version:

• Comprehension before code. Read the two manifestos and the roadmap first.
• Small commits, conventional format. feat:, fix:, docs:, chore:, test:, refactor:.
• Every exception is typed and surfaced. No silent except: pass. Ever. CI will fail you.
• Quality has no shortcuts. ruff + mypy --strict + pytest must all be green.
• Never import from BrainStormer or MemPalace. Lineage is reference material, not source. We reimplement.

License

MIT. See LICENSE.

---

_{Keywords for people who found this by searching: Claude Code memory, persistent context for Claude, kill AI amnesia, Claude Code MCP server, cross-session memory, Claude Desktop memory, Cursor MCP memory, Model Context Protocol Python, sqlite-vec memory, Anthropic Claude memory layer, verbatim memory for LLMs, LongMemEval, prediction-bound memory, belief-as-distribution retrieval, content-addressed memory, signed memory format, local-first AI memory, open-source Claude memory, MCP Python server template, how to make Claude remember between sessions.}