Cairn

One local brain for every AI agent. Cairn is a self-hosted, MIT-licensed personal context layer. It keeps facts and their evidence in one local SQLite vault, then serves a client-specific slice over the Model Context Protocol (MCP).

v0.1 scope: a single-user local service, evidence-backed ingestion and retrieval, per-client lenses and capability tokens, and the first complete MCP surface. macOS is the first-class platform; the core test matrix also covers Linux.

Why it exists

AI tools usually start cold and do not share decisions, preferences, or project state. Copying ever-larger instruction files between them is brittle: context gets truncated, facts go stale, and sensitive material is easy to overshare. Cairn makes shared context an inspectable local service with explicit authorization boundaries.

Related MCP server: Memclaw

What v0.1 provides

• Evidence-backed facts. A fact cannot be stored without an evidence excerpt, and every source is tagged with realm, tier, confidentiality, account, and source application.

• One liveness definition. Current, superseded, dormant, retracted, future, and expired records are distinguished in the database; serving reads only from the live projection.

• Ranked retrieval. Keyword retrieval is the no-download default. Optional vector search and reranking are lazy extras.

• Per-client lenses. A lens limits tiers, realms, confidential material, accounts, and source applications. Owner commands can preview the live per-tier blast radius before granting access.

• Per-client capability tokens. Tokens bind a client to its lens and allowed verbs. Rotation revokes old credentials and atomically rewrites receipt-managed mounts.

• Durable writes and jobs. Proposals pass through the common secret scanner. Expensive agentic queries persist before their job identifier is returned and recover after interruption.

• Local lifecycle tools. Cairn installs receipt-managed client mounts, starts one locked writer daemon, supports offline ingestion and search, and preserves the vault on uninstall.

• Owner dashboard. Eleven server-rendered screens expose the daily queue, evidence ledger, contradictions, sync, exact serving simulation, lenses, sources, history, graph, and extraction routing without sending vault data to a third-party frontend.

MCP surface

Every read tool requires an explicit scope; a missing scope is an error. Model-visible reads are annotated read-only and closed-world.

• Fast reads: whoami, query, and get_fact

• Durable synthesis: agentic_query and agentic_query_read

• Proposal write path: propose

• Export presets: export_list, export_read, and export_create_from_text

manage_fact is an action-enum administration endpoint rather than a raw database update. Administrative and connector-configuration endpoints are available to the owner REST surface but are deliberately absent from the model tool list.

Privacy boundary

Cairn's privacy claim is tier-scoped, not “nothing ever leaves the machine.”

• mind and privileged input is rejected by the hosted extraction dispatcher. Extraction routes are recorded, and the release gate checks for zero hosted extraction egress for those tiers.

• The default serving lens also denies mind and privileged. An owner can grant either tier only through a protected lens with an explicit confirmation.

• identity, profile, and environment extraction may be routed locally or to a hosted provider according to the owner's tier policy.

• Serving data to an authorized client is itself a disclosure. Once delivered, that client's storage and network behavior are outside Cairn's control. Do not grant a protected lens to a client whose downstream handling you do not trust.

Lens checks provide payload secrecy: denied records are not returned, and a denied fact identifier has the same response payload as a nonexistent one. Hidden rows can still affect shared keyword statistics and response timing. Per-lens retrieval statistics that remove those aggregate side channels are not part of v0.1; the administrative blast-radius preview remains available.

Cairn's daemon is the supported security boundary. A process running as the vault owner that opens the SQLite file directly can read rows without lens checks and can bypass daemon authorization, audit, and connection setup. Version 0.1 relies on OS file permissions and full-disk protection; it does not add application-level vault encryption. See THREAT_MODEL.md for the complete boundary.

Install

The default install is keyword-only, so first value requires no model download. Python 3.12 or newer and uv are required.

uv tool install cairn-vault
cairn init
cairn status

Ingesting a local path requires an explicit authorization classification:

cairn ingest ./notes \
  --realm personal \
  --tier profile \
  --no-confidential
cairn search "orbit"

Install the optional vector profile with:

uv tool install 'cairn-vault[vector]'

The distribution name is cairn-vault; the installed command is cairn. Unrelated projects already use the shorter registry name.

Dashboard

The dashboard is an optional install, so the core package remains the keyword-only CLI:

uv tool install 'cairn-vault[web]'
cairn-dashboard

Open http://127.0.0.1:8788. The unlock form checks the owner capability token locally, keeps it out of URLs, and exchanges it for an HTTP-only, same-site session. The dashboard itself talks to the daemon at 127.0.0.1:8787 with the owner token; neither service exposes a non-loopback bind option.

All browser dependencies are vendored with SHA-384 integrity metadata. The interface deliberately uses the operating system's high-quality grotesk, monospace, and serif stacks instead of downloading fonts, so every screen boots with no external network access. The graph is the only client-rendered data view; all lists and its accessible entity index are server-rendered.

To capture the exact 66-screen visual matrix while the dashboard is running:

python -m cairn.web.screenshot_gate \
  --base-url http://127.0.0.1:8788 \
  --artifacts output/playwright \
  --token-client adapter

The gate uses Chromium when Playwright can launch it. Otherwise it saves the same 66 authenticated server renders as HTML and runs the structural, integrity, CSP, external-request, and palette checks.

Administration

Lens commands return JSON, including the current per-tier blast radius:

cairn lens list
cairn lens create codex-safe \
  --client codex \
  --tier identity,profile \
  --realm personal,professional \
  --no-confidential
cairn lens show codex-safe
cairn lens revoke codex-safe

Adding mind or privileged requires the explicit --confirm-protected flag; the safe default lens is immutable. Rotate all client capabilities with cairn rotate-tokens; its receipt reports the exact mount files rewritten. cairn conformance reports each required engine separately. Real engine launches occur only when CAIRN_CONFORMANCE_LIVE=1; otherwise the command returns not run, never a pass.

What other products do better

Hosted memory products generally offer more connectors, browser and mobile access, managed backups, and less setup. Team knowledge products provide multi-user permissions, collaboration, enterprise identity integration, and more polished administration. Dedicated vector services can outperform Cairn's single-file design at very large corpus sizes. Cairn v0.1 instead prioritizes a single owner, local inspectability, portable data, and explicit per-client disclosure.

Platform and limits

• macOS is first-class; some local source connectors are platform-specific.

• Linux exercises the core keyword and vector profiles in CI.

• Windows is not supported in v0.1.

• The service is single-writer and single-owner. Multi-writer synchronization and multi-user authorization are out of scope.

• A localhost service cannot directly serve remote-only clients without a trusted local bridge.

Security and license

Report vulnerabilities as described in SECURITY.md. Cairn is licensed under the MIT License. Runtime and optional artifact licenses are listed in THIRD_PARTY_LICENSES.md.