Cairntir

Persistent, local-first memory for AI coding agents. Claude Code, Codex,
Cursor, Qwen Code, and other MCP clients share one searchable project history.

Cairntir stores decisions, facts, unfinished work, and outcomes as verbatim
drawers in a SQLite database you own. A budgeted handoff restores complete
drawers across sessions; semantic and file-anchored recall find deeper evidence.

Current release: 1.12.3. See the
release evidence and changelog.
Published downloads are on
PyPI and
GitHub Releases.

Install

pip install --upgrade cairntir
cairntir setup

Python 3.11+ is required. Setup initializes the store and configures supported
hosts it detects. Restart your agent afterward.

cairntir version
cairntir doctor

The diagnostic changes below are unreleased; pip install currently
selects published 1.12.3. That release's doctor/status/version may still run
registration and update callbacks, and status may open the store for writing.
See the change record before treating an installed diagnostic as read-only.

In this candidate, version reports this CLI's version. status and doctor inspect the store
and configuration without registering hosts or checking for updates. A
configured MCP entry does not prove a live connection. Setup's local write/read
check does not prove host delivery or semantic retrieval: require an actual
save receipt, then recover the exact task in a fresh chat using the
verification steps.

The change and adoption record distinguishes candidate,
released, installed and host-verified changes, with remaining checks and rollback
boundaries. Source edits do not update an already-running host.

For one host or project, use cairntir init --host codex; add --user for
user-scope configuration. Cursor's global User Rule requires a manual paste;
setup prints the rule and reports that step.

Follow the getting-started guide for configuration,
verification, recovery, and troubleshooting.

Use

Ask your agent to remember a decision in your project's wing, then start the
next task with cairntir_handoff(wing="myproject"). A wing is a project, a
room is a topic, and a drawer is one verbatim memory.

cairntir handoff myproject
cairntir handoff myproject --task "repair cache invalidation" --budget 8192
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

Handoff returns whole drawers or names those omitted by its character budget.
It includes recent default-layer writes, open predictions, and optional code
anchors. Settlements append observed outcomes without rewriting predictions.

Portable evidence preserves source identities and
relationships across stores. Evaluated procedures
require holdout evidence and local approval; scoped sharing
limits access with owner-issued grants.

Host support

Transcript recovery is opt-in, separately budgeted, read-only, and untrusted.
It reads bounded host-owned transcript tails; it cannot recover text the host
never persisted. Saving a recovered request requires explicit selection with
cairntir recover ... --write N. Memory is not automatically made
authoritative merely because it appeared in a transcript or imported file.

Data and safety

The authoritative store is local SQLite with sqlite-vec. Embeddings run
locally; first use may download the embedding model. Optional update checks
contact PyPI, and explicitly selected LLM adapters can contact their provider.
Cairntir is not a sandbox for the agent using it.

Portable JSONL verifies content hashes and optionally HMAC signatures through
the Python API. The CLI imports as untrusted and does not verify signatures.
Version 1 cannot safely import source-local history references; use a database
backup for linked history. Export/import also enforce the format's external-URL
restriction. See data handling for backup and trust boundaries.

Build and integrate

The MCP server exposes 21 tools over stdio. Stable Python protocols support
custom backends; see the integration guide.

src/cairntir/
├── memory/       # SQLite storage, embeddings, retrieval
├── mcp/          # stdio server and backend
├── reason/       # prediction, experiment, observation
├── recipes/      # composable workflows
└── cli.py        # cairntir setup | init | handoff | recover | recall | replay | hotfix | doctor | export | import
tests/            # unit, integration, contract, property, evaluation
docs/             # guides, architecture, recipes, release evidence

Contributing documents the locked development environment
and required checks. Tests enforce at least 80% coverage of the measured
surface; transport entrypoints are excluded and tested separately. The
LongMemEval subset is a regression gate, not a general benchmark claim.

Documentation

• Getting started
• Concepts and data handling
• Multi-host architecture
• Recipes: CodeGlass, Decision Replay, Signal Reader,
  Bounded Hotfix, and Finalization Mode
• Roadmap
• Security policy · release policy
• Design principles · lineage

Cairntir (CAIRN-teer) combines a cairn, a waypoint of stacked stones, with a
seeing-stone. Maintained by Patrick McGuire. MIT licensed.