Cairn

What is Cairn?

Cairn is a self-hosted memory and orchestration layer for AI agents and humans. It persists memories across sessions and projects, using PostgreSQL 16 with pgvector for hybrid search and optionally Neo4j for a knowledge graph. It is built for systems-oriented, t-shaped engineers who need a memory that works across everything.

How to use Cairn?

Deploy with a single command: curl -O https://raw.githubusercontent.com/jasondostal/cairn-mcp/main/docker-compose.yml && docker compose up -d. Then add the MCP server to your IDE config (e.g., Claude Code, Cursor) with { "mcpServers": { "cairn": { "type": "http", "url": "http://localhost:8000/mcp" } } }. Use tools like store, search, recall, orient, work_items, code_index, and arch_check to save and retrieve memories, manage work, and analyze code.

Key features of Cairn

• Persistent memory across sessions and projects
• Hybrid search (vector + keyword + recency + tags) via Reciprocal Rank Fusion
• Optional knowledge graph in Neo4j for entity and fact connections
• Hierarchical work items with dependency tracking and gates
• Web dashboard with analytics, chat, and graph exploration
• Code intelligence with tree-sitter (Python, TypeScript/TSX) and architecture enforcement
• Session capture hooks for IDE tool call logging

Use cases of Cairn

• Remembering a design decision made in a late-night session and retrieving it the next morning
• Searching across weeks of work to find a buried issue or configuration detail
• Coordinating multiple agents with task dispatch, dependencies, and human-in-the-loop gates
• Indexing a codebase to answer structural questions like blast radius or dependency impact
• Enforcing architecture boundary rules across projects via YAML definitions

FAQ from Cairn

Do I need an LLM to use Cairn?

No. Store, search, recall, and rules work without an LLM. You only lose auto-enrichment (summaries, tags, importance), knowledge extraction, and chat. When needed, Cairn supports Ollama, AWS Bedrock, Google Gemini, and any OpenAI-compatible backend.

How is data stored and where does it live?

Memories and embeddings are stored in PostgreSQL 16 with pgvector. The optional knowledge graph lives in Neo4j 5. Both run as containers alongside the Cairn server and UI. All data is self-hosted; no external services are required.

What authentication and transport options are available?

Cairn exposes an MCP server (HTTP on port 8000) and a REST API on the same port. API key authentication can be enabled via the CAIRN_AUTH_ENABLED and CAIRN_API_KEY environment variables. Client configuration expects an HTTP MCP URL.

How does Cairn perform on memory benchmarks?

On the LoCoMo long-conversation memory benchmark (1,986 questions), Cairn scores 81.6% with Llama-3.3-70B, compared to a human baseline of 87.9%, Letta/MemGPT at 74.0%, and Mem0 at 66.9%.

What are the system requirements and dependencies?

Cairn runs in four Docker containers: the server, a web UI, a PostgreSQL 16 database with pgvector, and an optional Neo4j 5 knowledge graph. For LLM enrichment, a local Ollama installation or cloud provider credentials are required. A GPU is not needed for the default local embedding model (MiniLM, 384-dim).