Cairn

You can run Cairn as an MCP server to store, recall, and explore memories with a flexible, pluggable backend. It provides a REST API and a web dashboard, and captures memories from both humans and agents across sessions for fast, contextual recall and analysis.

How to use

To use Cairn as your MCP server, run the provided HTTP endpoint to access the REST API and connect your MCP client. You can also run Cairn locally via a standard input/output (stdio) transport to connect directly from a client inside the same environment. Use the REST API for multi-client access over the network, and leverage the web dashboard for a visual, searchable memory graph, timelines, and thinking trees.

How to install

Prerequisites: you need Docker and Docker Compose installed on your machine. You also need a suitable LLM backend configuration if you plan to enable enrichment and narrative synthesis.

Step 1: Bring up Cairn with Docker Compose.

curl -O https://raw.githubusercontent.com/jasondostal/cairn-mcp/main/docker-compose.yml
docker compose up -d

This starts three containers: a Cairn MCP server with REST API on port 8000, a web dashboard on port 3000, and a PostgreSQL 16 database with pgvector. Migrations run automatically and the stack is ready in under a minute.

Configuration and startup details

Cairn is configured via environment variables in the container definitions. For a local development setup, you can rely on Ollama as the default LLM backend, or switch to Bedrock, Gemini, or an OpenAI-compatible backend. The default database password is a development credential in the example setup, which you should replace for any network-exposed deployment.

The three containers expose the following endpoints by default: MCP server and REST API at port 8000, web dashboard at port 3000, and the database exposes PostgreSQL features with pgvector support.

Security and authentication

If you want API access control, enable authentication by setting CAIRN_AUTH_ENABLED to true and provide CAIRN_API_KEY. The API routes will then require the configured API key in the request headers. For local development, you can keep authentication disabled, but for production deployments, enable it to protect your data.

Additional notes

The MCP server exposes a REST API at /api and a set of endpoints for memory management, search, clustering, and workflow tooling. It also offers a browser bookmarklet for quick capture and a web dashboard for interactive exploration of memories, clusters, and narratives.

Troubleshooting

If you encounter connection issues, verify that the Cairn containers are up and healthy. Check that port mappings align with your host, and confirm that the REST API is reachable at http://localhost:8000/mcp when using the HTTP transport. If you use stdio transport, ensure the MCP client can execute the provided stdio command against the Cairn container.

Available tools

store

Persist a memory with auto-enrichment, relationship extraction, and rule conflict detection

search

Hybrid semantic search with query expansion and optional confidence gating

recall

Expand memory IDs to full content with cluster context

modify

Update, soft-delete, reactivate, or move memories between projects

rules

Behavioral guardrails — global or per-project

insights

HDBSCAN clustering with LLM-generated pattern summaries

projects

Documents and cross-project linking

tasks

Task lifecycle — create, complete, list, link to memories

think

Structured reasoning sequences with branching

status

System health and capability reporting

synthesize

Synthesize session memories into narratives

consolidate

Find duplicates and propose merges or promotions

cairns

Session markers to walk the memory trail