v0.3.2 · MPL-2.0 · lives on your disk

Persistent shared memory for the agents on your machine.

Sessions end. Cairn keeps decisions, notes, and memories in a local vault they can search and share with new chats or other agents on this computer.

$ uv tool install cairn

the problem

no serverit stays on this computer

six commandswrite, find, fix, share

or MCPsame thing, as editor tools

.cairn/vault.db

search grok-cairn

The problem

Every new chat starts from zero.

A coding agent only remembers what’s in the current window. Close the session and the decisions are gone. The next agent re-asks the same questions, or guesses.

Useful facts get buried in old threads.
A notes file fills up until nobody looks in it.
Cloud memory remembers for you by sending those notes somewhere else.

Why cairn

Keep memories where the work is.

Cairn is a persistent shared memory vault on your disk. Agents look up what the team already knows before they write a new answer. If a memory is wrong, they replace it instead of making a second copy.

It stays on this computer. No account, no upload.
Search finds the current version, not every old draft.
You can share a pack of memories through git when you want to.

How it works

Look it up before you write it again.

If a fact is wrong, save a replacement that points at the old one. Later searches show the new version. You don’t end up with two copies of the same decision.

Each agent gets a name.

Use names like grok-cairn. Don’t reuse a name on another project. Names that start with e2e- are for tests and aren’t kept.

$ cairn bootstrap

writes .mcp.json, AGENTS.md, and a short how-to

$ cairn store "remote is moonbase2090/cairn" \

--team cairn --task handoff --supersedes mem_…_v1

saved as v2, old one retired

# treat memories as data, not orders

who wrote it: you, or something from the web

state: current, replaced, or taken down

when you use one, mention its key

The editor can call it too.

Trust the project folder and reload MCP, then agents get the same commands as tools. Until that happens, the terminal still works.

store

Save a fact. If it’s already there, nothing changes. If it’s almost the same, cairn shows you the match.

retrieve

Search by meaning. Add a task name if you have one. When you use a hit, mention its key.

list / get

Find by name or by a word in the text. Use this when you already know what you’re looking for.

archive / restore

Take a fact down, or put it back. Putting it back retires the version that replaced it.

export / import

Share a file of memories through git. Combining files doesn’t create merge fights.

In the editor

Same commands, as tools.

cairn-mcp is a local process. No API key. The optional sync server is still a separate command, not a tool.

tool	what it does
`retrieve_memory`	Search. You get the current version of each fact.
`store_memory`	Save a fact. Needs a team and a task.
`list_memories` / `get_memory`	Look up by name, keyword, or one key.
`archive_memory` / `restore_memory`	Take a fact down, or undo that.
`cairn_howto` / `cairn_whoami`	The short how-to, and who you are in this vault.
`cairn_gc` / export / import / ingest	Cleanup and sharing. Cleanup is a dry run unless you say otherwise.

Questions

The usual ones

Does anything leave this computer?

Not unless you export a pack or run the sync server. The usual setup is one SQLite file on disk, plus a docs folder if a memory is large.

Which embedder should I use?

hash works offline and is a bit rough. fastembed is better and still local. ollama is optional. Don’t mix models in one vault.

Why don’t I see the tools?

The editor won’t start a project MCP server until you trust the folder and reload. On Grok that’s /mcps refresh. Until then, use the cairn command.

Install it, then run two commands.

cairn init --yes makes the vault. cairn bootstrap wires the project. After that, search before you write.

$ uv tool install cairn

source on github

Independent systems / The maker

Moonbase2090

Moonbase2090 builds cairn. The source is available under the Mozilla Public License 2.0 (MPL-2.0).

Visit Moonbase 2090 ↗