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 memory: what was decided, what’s still open, and what actually happened. All of it stays 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 trail is still there between chats, tools and teammates.
02The problem
A new chat doesn’t inherit the last one.
When a session ends, its reasoning ends with it.
So someone briefs the next agent by hand. The more agents your team runs, the more hours that costs.
What’s lost when the window closes
- 01
The decision
What was chosen, and what it replaced.
- 02
The reason
Why the other options lost.
- 03
The open work
What’s half done and still waiting.
- 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 saves decisions, facts, open work and outcomes word for word, in a local database you own. Every new session starts with a handoff of what matters, and recall finds anything older by meaning, or by the file you’re about to change.
Wing a project · Room a topic inside it · Drawer one memory, word for word
Nothing is ever trimmed. A memory too long for the handoff is listed by name, ready to open in full.
handoff · wing myproject
Example
Cache invalidation is half done
Keys are versioned. Eviction on deploy is not written yet.
Too long for this handoff, so it’s listed instead. Open it in full with cairntir_get.
cairntir recall "why did we choose Postgres?" --wing myproject
04What makes it different
One history, many agents.
Setup detects and connects the tools below. Any other MCP client can plug in too, and every one of them reads the same project history.
- Claude Code
- Cline
- Codex CLI
- Copilot CLI
- Cursor
- Gemini CLI
- OpenCode
- Qwen Code
- Other MCP clients
You decide what’s kept.
Nothing is saved just because it scrolled past in a chat. You, or an agent you ask, choose what becomes memory.
History stays honest.
What you expected and what actually happened are kept side by side. Neither ever overwrites the other.
Nothing gets trimmed.
Handoffs deliver complete memories, never fragments. Anything that doesn’t fit is listed, ready to open.
It stays yours.
Local storage, local search, open source. No telemetry, no account, no cloud.
05In the age of the AI workforce
Your agents will change. The record should not.
Teams now run several models and tools at once, and swap them out as better ones arrive. Each new one starts cold. Cairntir keeps your project’s history in one place that every agent can read, whichever one you use next.
Less re-explaining
Stop briefing every new session from scratch.
Decisions that stick
The reason behind each choice travels with it, so nobody undoes it 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.”
What we’re building toward
06Start
Two commands, then restart your agent.
Needs Python 3.11 or newer. Setup creates your local memory and connects every supported tool it finds.
Using Cursor? Setup prints one short rule for you to paste into its settings.
-
Install
pip install --upgrade cairntir cairntir setup -
Check
cairntir doctor -
Use
Ask your agent to remember a decision. Start your next task with:
cairntir_handoff(wing="myproject")
07Past the last stone
Where the path goes next.
-
Available now
Word-for-word local memory, handoffs that brief every new session, recall by meaning or by file, reusable recipes and verified backups.
-
In progress
Start a task in one tool and finish it in another, right where you left off.
-
Next
Recall that brings the right memory forward before you ask for it.
-
Version two
A bigger step for Cairntir: project history that turns into the next useful action, a shared space where your team can read and refine what’s remembered, and routine progress that keeps moving without waiting for a prompt.
-
The Completion Djinn
The engine at the heart of version two, built to carry work from remembered to finished. More soon.
08Questions
What people ask first.
What is Cairntir?
Cairntir is free, open-source memory for AI coding agents. It runs on your machine as an MCP server, saves your project’s decisions, facts, open work and outcomes word for word, and hands them to any connected agent when it starts a task or needs to look something up.
Does my project memory leave my machine?
No. Your memory lives in a local database, and search runs locally too. The first run downloads a small search model; after that, the only network calls are optional update checks and any AI provider you choose to connect. There’s no telemetry.
Which AI tools work with it?
Setup connects Claude Code, Cline, Codex CLI, Copilot CLI, Cursor, Gemini CLI, OpenCode and Qwen Code automatically. Any other MCP client can connect with the cairntir-mcp command.
How is it different from chat history or a rules file?
Chat history is locked inside one tool and one conversation. A rules file is a single document someone has to keep up to date. Cairntir keeps separate, dated memories that every agent can search by meaning or by file, delivers them in full, and keeps what you expected apart from what actually happened.
What does it cost?
Nothing. Cairntir is free and open source under the MIT license.
Leave a cairn for the next one.
Install it once, and every new session can pick up where the last one left off.
Built and maintained by Patrick McGuire
McGuire Digital · Development and design
“We are problem solvers.”GitHub profile