# 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.

## 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](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.

```sh
uv tool install cairn-vault
cairn init
cairn status
```

Ingesting a local path requires an explicit authorization classification:

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

Install the optional vector profile with:

```sh
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:

```sh
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:

```sh
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:

```sh
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](SECURITY.md). Cairn is
licensed under the [MIT License](LICENSE). Runtime and optional artifact
licenses are listed in
[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).