Agent Cairn

Shared, persistent project memory for AI coding agents.

A cairn is a stack of stones that earlier hikers leave so the next one knows the way. Agent Cairn does that for agents: one records what it learned, the next one picks up the trail.

An AI agent that opens your project cold has to read files, guess conventions and ask you to explain things you have explained before, and it does that again on every new session, machine and account. Agent Cairn gives agents a shared memory stored in Neo4j: what the project is, how it is built, the traps that cost time, the decisions made and why. Any agent connecting through MCP starts from a compact, token-budgeted briefing instead of re-reading the repository.

How it works

 Claude Code ──MCP over HTTP + token──►  Agent Cairn server  ──bolt──►  Neo4j
 (any machine,      hooks + CLI            (Docker)                  (graph)
  any account)                                │
                                         dashboard at /ui/

• Agents write the memories. Through MCP tools (cairn_remember, cairn_checkpoint) an agent records what it learns. The server never calls an LLM: no API key, no per-token cost, and it works with any MCP-capable agent.

• Briefings instead of crawling. cairn_briefing assembles the most important memories for a project within a token budget: overview, conventions, gotchas, open threads, recent checkpoints, decisions.

• Memories know when they are stale. Each memory records the commit and files it was written about. If those files have changed, the briefing flags it.

• History is kept. A changed fact supersedes the old one rather than overwriting it, so concurrent agents cannot clobber each other and the reasoning trail survives.

• One memory per project, across machines. A project is identified by an explicit id or by its (normalized, hashed) git remote, so every clone resolves to the same memory.

• You can see everything. A built-in dashboard shows every request as it happens, the memory graph, and lets you manage access.

Related MCP server: DecisionsSearch

Quick start

You need Docker. Everything below runs on your own machine or server.

1. Start the server and a Neo4j to go with it

git clone https://github.com/itsmemac/agentcairn.git && cd agentcairn
cp .env.example .env                       # set NEO4J_PASSWORD
docker compose --profile with-neo4j up -d
docker compose logs cairn               # the first start prints a one-time setup code

Already running Neo4j? Set NEO4J_URI in .env and run docker compose up -d cairn instead.

2. Create your admin account. Open http://localhost:8787/ui/, enter the setup code from the log, choose a username and password.

3. Connect an agent. In the dashboard, create a token (Access → Create token). Then, once per machine:

claude mcp add cairn --scope user -e CAIRN_URL=http://localhost:8787 -e CAIRN_TOKEN=<token> -- npx -y agentcairn mcp

That is the whole install. It works in every folder: the project comes from the folder's git remote (or its .cairn.json), so there is nothing to configure per repository. Start Claude Code in a project and ask it to call cairn_status. The first cairn_briefing of an empty project returns instructions that walk the agent through recording what it learns about the repository.

4. Optional: hooks and an explicit project id. The cairn CLI (npx -y agentcairn) links a folder to a project and installs Claude Code hooks that inject the briefing at session start and remind the agent to checkpoint. See Using it with Claude Code.

The CLI is on npm as agentcairn. Run it with npx -y agentcairn <command>, or npm install -g agentcairn to get the cairn command.

The dashboard

• Live: every request with its payload, latency and the memories it touched; throughput, per-tool latency, clients online.

• Projects and Graph: browse, search and explore memories; follow supersede chains.

• Query: a read-only Cypher console.

• Access: create and revoke tokens, copy ready-made connection commands.

• System: server and Neo4j health, graph size, security and capture settings.

Dark and light themes, phone-friendly. Request payloads are kept in memory only (the last 2,000) and Authorization headers are never recorded.

What agents get

Documentation

• Self-hosting: Docker, TLS, upgrades, backups, troubleshooting

• Unraid: running it on an Unraid server

• Using it with Claude Code: connecting, project identity, hooks

• Configuration: every setting and file

• Architecture: data model, briefings, staleness, security model

• Contributing · Security policy · Changelog

Repository layout

Development

npm install
cp .env.example .env     # point NEO4J_URI at a throwaway Neo4j (see CONTRIBUTING.md)
npm test                 # builds, then runs every package's tests

The integration tests run against a real Neo4j, so use a disposable instance. See CONTRIBUTING.md.

License

MIT