Cairntir

Persistent memory for AI coding agents — one local memory shared by Claude Code, OpenAI Codex, Cursor, Qwen Code, and every MCP client.

Cairntir is an open-source, local-first memory MCP server. It preserves project decisions, facts, outcomes, and unfinished work across chats and across coding agents, so a new session can recover the real context instead of asking you to explain the project again.

Release candidate: Cairntir 1.9.0 · Changelog · Acceptance record

Latest published: Cairntir 1.8.0 · PyPI

Why Cairntir exists

AI coding assistants start each session cold. They forget architectural decisions, repeat failed approaches, and lose the reason behind unusual code. Static instruction files help with rules, but they are not searchable project memory and they do not record what happened.

Cairntir gives coding agents durable, cross-session memory in a SQLite database you own. Writes remain verbatim. Every memory carries provenance. Retrieval is budgeted so the agent receives complete evidence it can use, not a flood of truncated context.

The result is simple: reopen a project weeks later and walk into a lit room.

Install

pip install --upgrade cairntir
cairntir setup

Restart the configured agents, then verify the installation:

cairntir version
cairntir doctor

cairntir setup creates the local store, detects installed hosts, and connects every supported agent it can find. Missing CLIs are skipped rather than treated as failures. For one host or one project, use:

cairntir init --host codex
cairntir init --host all --user

New to MCP or terminal tools? Start with the plain-English setup guide.

What changed in 1.9.0

Cairntir 1.9.0 makes repair and learning evidence fail closed:

• Bounded hotfix ledgers preserve cited recommendations, exact authority, one-attempt execution receipts, independent verification, rollback, and a terminal result without giving Cairntir execution power.
• Reason-loop boundary validation rejects blank, cross-scope, mismatched, incomplete, or falsely idempotent adapter output before it can become evidence.
• Verdict and surprise stay independent. Explicit delta survives through Outcome, replay, recipes, adapters, and all shipped CLI reasoning paths.
• Discovery uses exact evidence pairs. Only uniquely bound predictions and observations in the same room count toward a human-reviewed candidate.

Read the complete 1.9.0 changelog and release acceptance record.

How persistent memory works

1. Write. cairntir_remember stores a verbatim drawer with its project, topic, retrieval layer, source host, model, trust level, and optional code anchors.
2. Store. One local SQLite + sqlite-vec database remains authoritative. The schema migrates forward with backup-first safety.
3. Read. cairntir_handoff(wing) returns whole relevant drawers under a hard character budget. Semantic and structural recall handle deeper search.
4. Close. Prediction-bound drawers record claim → expected outcome → actual outcome → surprise. Settlements append evidence instead of rewriting history.

Nothing is silently summarized at write time. A drawer is returned whole or named for deliberate retrieval; it is never cut in half to fill a context window.

Cross-session and cross-agent memory

Cursor is a first-class configured host. Transcript recovery remains unsupported there because Cursor does not publish a stable transcript schema; Cairntir reports that limit instead of guessing at private data.

Core capabilities

Common commands

cairntir handoff myproject
cairntir recall "why did we choose Postgres?" --wing myproject
cairntir recall-for-change src/auth.py
cairntir recover --host codex --wing myproject
cairntir cost myproject
cairntir calibration --wing myproject
cairntir hotfix status --wing myproject --case-id hf-abc123
cairntir export memories.jsonl

For recovered transcript text, storage requires explicit consent:

cairntir recover --host codex --wing myproject --write 1

Context-budget evidence

On one real store measured 2026-08-02, the deterministic handoff used 44–52% fewer tokens than the older session-start path while returning complete drawers instead of truncated stubs:

These are dated measurements of two stores, not a universal benchmark. Run cairntir cost yourproject to measure your own corpus. CI separately enforces a LongMemEval R@5 regression floor; Cairntir does not reuse another project's benchmark as its own.

MCP server and library surface

The MCP server exposes 21 tools over stdio for exact memory, handoff, semantic and structural recall, audit, reasoning, calibration, discovery, and bounded hotfix records. Tool builders can use the stable Python Protocol surface with a custom backend; see the integration guide.

cairntir/
├── src/cairntir/
│   ├── contracts.py      # stable Store protocol
│   ├── memory/           # SQLite, sqlite-vec, belief scoring, consolidation
│   ├── mcp/              # host-neutral stdio server
│   ├── hotfix.py         # bounded append-only repair ledger
│   ├── reason/           # testable reasoning loop and ports
│   └── cli.py            # cairntir setup | init | handoff | recover | recall | replay | hotfix | doctor | export | import
├── tests/                # unit, contract, property, integration, evaluation
├── docs/                 # guides, architecture, recipes, release evidence
└── plans/                # live plans and dated decision history

Recipes

Recipes combine memory and the three core reasoning skills without expanding the primitive skill set:

• Finalization Mode — finish a roadmap against frozen acceptance criteria and bounded repair rounds.
• Bounded Hotfix — compare cited repair paths, bind one attempt to exact authority, independently verify it, and stop.
• CodeGlass — turn unfamiliar code into durable, evidence-cited understanding.
• Decision Replay — revisit a past prediction and record what reality taught you.
• Signal Reader — convert AI news analysis into falsifiable, longitudinal evidence.

Cairntir compared with static memory files

Rules files remain useful for instructions. Cairntir complements them with searchable evidence and history; it does not replace project policy.

Documentation

• Changelog
• Cairntir 1.9.0 release acceptance
• Cairntir 1.8.0 published evidence
• How to use Cairntir
• Plain-English setup
• Integration guide
• Architecture and concepts
• Roadmap
• Origin, lineage, and long-term vision
• Release and deprecation policy

Name and principles

Cairntir combines cairn, a stack of stones marking a path, with palantír, a seeing-stone across time and distance. Pronounced CAIRN-teer.

The project is MIT-licensed, local-first, append-only where history matters, and built without telemetry. Read ETHOS.md and CONTRIBUTING.md before contributing.

A stack of stones that sees across time.