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.