Use Postgres for the ledger
Chosen over SQLite for concurrent writers. Revisit if the service stays single-user.
01Local-first memory and reasoning
Memory, with a way back.
Cairntir gives every AI agent on your project the same record: what was decided, what is unfinished, and what actually happened. It lives in a database on your machine.
The sightline
The next session can see the last one.
A cairn marks a path someone has already walked. Cairntir marks your project the same way, so the path is still there between chats, tools and people.
02The problem
A new chat does not inherit the last one.
When a session ends, the reasoning usually ends with it.
Someone has to brief the next agent by hand, and the more agents a team runs, the more often that happens.
What leaves with the window
- 01
The decision
What was chosen, and what it replaced.
- 02
The reason
Why the other options lost.
- 03
The open work
What was started and not finished.
- Wing
- A project.
- Room
- A topic inside that project.
- Drawer
- One memory, stored word for word.
03What it keeps
Whole memories, kept on your machine.
Cairntir stores decisions, facts, unfinished work and outcomes as verbatim drawers in a SQLite database you own. Embeddings run locally. Handoff brings whole drawers into the next session, and recall finds older ones by meaning or by the file you are about to change.
Wing a project · Room a topic inside it · Drawer one memory, word for word
A drawer that does not fit the handoff budget is named, never cut in half.
handoff · wing myproject
i Example records
Cache invalidation is half done
Keys are versioned. Eviction on deploy is not written yet.
Named, not cut. Fetch it whole with cairntir_get.
cairntir recall "why did we choose Postgres?" --wing myproject
04What is different
One history, many agents.
Setup finds and configures the hosts below. Any other MCP client can connect to the same local server. Each one reads the same project history.
- Claude Code
- Cline
- Codex CLI
- Copilot CLI
- Cursor
- Gemini CLI
- OpenCode
- Qwen Code
- Other MCP clients
Writes are explicit.
Nothing becomes memory because it drifted past in a transcript. You, or an agent you asked, decide what is kept.
The past is not rewritten.
A prediction stays as it was written. The observed outcome is appended beside it, so what was expected and what happened remain two facts.
Nothing is cut in half.
Handoff returns whole drawers under a character budget and names the ones that did not fit.
It stays yours.
Local SQLite, local embeddings, MIT license. There is no product telemetry pipeline.
05In the age of the AI workforce
Your agents will change. The record should not.
Teams now run work through several models and tools at once, and replace them as better ones arrive. Each one starts without the history. Cairntir keeps that history in one local store that any of them can read.
Less reconstruction
People stop re-explaining the project to every new session.
Fewer reversed decisions
The reason for a choice travels with it, so it is harder to undo by accident.
A record you own
A local database you can back up, inspect and move.
“On day thirty, opening the project should feel like walking into a lit room.”
The design goal
06Start
Two commands, then restart your agent.
Python 3.11 or newer. Setup creates the local store and configures the supported hosts it finds.
Cursor’s global user rule is a manual paste. Setup prints it for you.
-
Install
pip install --upgrade cairntir cairntir setup -
Check
cairntir doctor -
Use
Ask your agent to remember a decision in your project’s wing. Start the next task with:
cairntir_handoff(wing="myproject")
07Past the last stone
Where the path goes next.
-
Shipped
Verbatim local memory, whole-drawer handoff, semantic and file-anchored recall, prediction settlements, recipes and opt-in verified backups, served through 21 MCP tools.
-
In progress
Resuming an interrupted task from another host, with only a shared wing or task ID.
-
Next
A retrieval preflight, tested against a pre-registered holdout before anything automatic is built.
-
Version two
Reserved for a change in what Cairntir is for: history that becomes the next useful step, a place for people to read and correct it, and routine progress that does not wait for someone to open a chat. The design is approved. None of it is claimed to run today.
-
The Completion Djinn
One part of version two already has a name: the Completion Djinn, also called the Completion Engine. We will describe it when it can be shown working.
08Questions
What people ask first.
What is Cairntir?
Cairntir is open-source, local-first memory for AI coding agents. It runs as an MCP server, stores decisions, facts, unfinished work and outcomes word for word in a SQLite database on your machine, and lets any connected agent recall them or receive them as a handoff at the start of a task.
Does my project memory leave my machine?
The store is a local SQLite database and embeddings run locally; the first use may download the model weights. Optional update checks contact PyPI, and an LLM adapter you explicitly select may contact its provider. There is no product telemetry pipeline.
Which AI tools work with it?
Setup detects and configures Claude Code, Cline, Codex CLI, Copilot CLI, Cursor, Gemini CLI, OpenCode and Qwen Code. Any other MCP client can run the cairntir-mcp stdio command, configured by hand.
How is it different from chat history or a rules file?
Chat history belongs to one tool and one conversation. A rules file is a single document someone has to keep current. Cairntir keeps many separate, timestamped memories that every connected agent can search by meaning or by file, returns them whole, and keeps a prediction apart from what actually happened.
What does it cost?
Nothing. Cairntir is free and open source under the MIT license, and runs on Python 3.11 or newer.
Leave a cairn for the next one.
Install it once. The next session can start from what this one kept, on your machine, in a record you can read.
Built and maintained by Patrick McGuire
McGuire Digital · Development and design
“We are problem solvers.”GitHub profile