Cairn Memory

Lightweight cross-session memory for AI agents, with receipts.

Cairn Memory is an open-source memory layer for agents: keep memories in a local
SQLite file, retrieve them across sessions, and inspect the Source Receipts that
explain where they came from. Correct a memory at its current revision or forget
it without letting a later automatic capture silently restore it.

The local developer preview runs without a Cairn account. Its thin MCP server
uses the same public core as the JavaScript API: no separate memory engine per
client. MOC organization, bounded model-guided recall and capture orchestration
are in the core; the five MCP tools provide explicit memory operations, not
automatic transcript capture.

Preview, not a quality guarantee. An installed subprocess has passed a real
model-backed remember → restart → sourced recall → forget loop. The frozen
semantic evaluation still fails source support: an extractor sometimes turns
“uses a language” into “is implemented using it.” All retained results
remain visible. This is synthetic evidence, not a competitor benchmark or a
claim that real users save a measured amount of time.

An explicitly selected experimental extraction profile
passed the frozen synthetic gate after independent agent review. The default
model's failure remains; MCP does not automatically enable the experimental
profile, which is a programmatic adapter option. MCP remember_memory saves
explicit content directly; it does not run that extractor. Those extraction
scores therefore do not certify the MCP recall experience.

Try the local memory layer

Prerequisites: Node >=22.16, npm and tar. Model-free remember/inspect/correct/
forget need no key; semantic recall needs your explicitly supplied OpenAI key
and sends the query and selected memory context to that provider. A real fully
local model path is not yet verified.

git clone https://github.com/Cairn-ink/cairn-memory.git
cd cairn-memory
npm run install:preview -- --directory /absolute/new/cairn-local --owner local-user

Choose a new absolute directory with an existing parent you control. The
installer builds and installs the inspected archive, downloads pinned public npm
dependencies without install scripts, and prints a generic stdio command/args.
Copy that command/args into your client's local MCP configuration; it does not
modify client settings for you. Add --project PROJECT_ID for project scope.

The directory contains app/ (replaceable installation), data/ (persistent
memory location), and installation-receipt.json (artifact hash, local paths,
owner/project and stdio settings). No key is stored. Unlike --check-config, the
receipt intentionally contains local paths and identity: do not post it publicly.
The installer never starts MCP, opens a database or makes model calls. Existing
directories are rejected, including partial installs; see
manual installation, recovery and backup.
The archive is not published to npm; there is no registry npx shortcut yet.
This builds the checked-out source, not the older released hosted-plugin tag.
Record git rev-parse HEAD and keep the build report to identify your preview.

Before configuring a client, check the installed command (substitute your paths):

/absolute/new/cairn-local/app/node_modules/.bin/cairn-memory --help
/absolute/new/cairn-local/app/node_modules/.bin/cairn-memory --check-config --db /absolute/new/cairn-local/data/memory.sqlite --owner local-user

The check makes no model requests and never opens your database. A missing key
is a valid model-free configuration. A present key means only “configured,” not
that credentials, model access or database permissions have been verified.
Starting without --check-config waits for an MCP client; a quiet terminal is normal.

No chat-client setup is needed for a first synthetic check. From this source
checkout, install the isolated SDK client and point the walkthrough at your
installed executable (replace the absolute placeholder path):

npm ci --prefix adapters/mcp
node adapters/mcp/walkthrough.mjs --executable /absolute/new/cairn-local/app/node_modules/.bin/cairn-memory

This default path makes no model calls, even if the parent shell has a key.
It checks persistence, receipts, revision safety and forgetting; recall must
report model_not_configured. To exercise paid semantic recall, explicitly
supply OPENAI_API_KEY through your secret environment and add --with-recall.
The walkthrough does not impose a provider account spending limit.

Start with the first-value guide to distinguish the
no-key installation check from the pending real-model Hermes conversation task,
including the two model credentials and profile/database boundaries.
Try the cross-session walkthrough. See the
tested client matrix
before assuming a named client works: SDK stdio and Hermes MCP discovery have
evidence. The included Hermes native-provider preview
also passed actual MemoryManager two-session sourced recall on Linux CLI;
interactive chat tool selection and remote HTTP connectors remain separate gates.

Local privacy and control

• Memory, receipts and organization persist in your selected SQLite database.
  No Cairn account, hosted service or hidden core telemetry is required.
• MCP does not read transcripts or save whole conversations automatically.
  Receipt text records a tool assertion; it is not proof of authenticated human intent.
• Model processing is cloud processing when configured. Redaction is best-effort,
  not a guarantee that all secrets are removed. Retrieved text is untrusted data,
  never instructions to follow.
• Forgetting prevents active recall and automatic re-admission. It is not secure
  disk erasure: SQLite pages, receipts and backups have separate retention limits.
  Stop all writers before copying the database and sidecars for backup.
• Uninstalling the executable preserves the external database. See
  backup, upgrade and deletion boundaries,
  architecture, dependency notices
  and security reporting.

Existing hosted integration

The released v0.1 Claude Code plugin below is a different installation mode:
it connects to a compatible hosted service, automatically captures allowlisted
conversation text, and has its own telemetry defaults. It has not been migrated
to the local engine. Existing hosted users can keep using these instructions.

The opt-in Hermes memory-provider preview
adds profile-local explicit tools through the installed MCP. Its pinned-host
offline lifecycle tests are not a full chat or semantic-quality certification.

Install for Claude Code (automatic memory)

In Claude Code, run:

/plugin marketplace add Cairn-ink/cairn-memory
/plugin install cairn-memory@cairn-memory

Create a personal access token at https://cairn.ink/settings/tokens, then provide it when Claude Code asks for plugin configuration. Start a new session after installation.

For local development:

git clone https://github.com/Cairn-ink/cairn-memory.git
cd cairn-memory
claude --plugin-dir ./plugins/cairn-memory

Connect from Codex (explicit MCP memory)

Codex v0.1 support uses the hosted MCP tools. Keep the token in your shell or
secret manager, not in a repository or committed config file:

export CAIRN_MCP_TOKEN='your-token-from-cairn.ink'
codex mcp add cairn \
  --url https://cairn.ink/api/mcp \
  --bearer-token-env-var CAIRN_MCP_TOKEN

Restart Codex, then use /mcp or codex mcp list to confirm the connection.
Codex can now explicitly remember, recall, and forget private memory. The v0.1
release does not install automatic Codex lifecycle hooks; that compatibility
layer is next on the roadmap.

Hosted plugin loop

User prompt
  └─ recall relevant personal + project-private memories
       └─ inject a short, explicitly untrusted context block

Assistant turn ends
  └─ hand capture to a detached worker without delaying Claude
       └─ read only new user/assistant transcript text
            └─ redact likely credentials locally
                 └─ send an idempotent capture batch
                      └─ store durable memories with Source Receipts

The bundled MCP connection also exposes explicit remember_memory, recall_memory, and forget_memory tools. Clients without lifecycle hooks can use those tools manually; passive capture is never claimed where the host does not expose a hook.

Hosted plugin privacy contract

• Installation is explicit. Automatic capture begins only after installation and is on by default.
• Only textual user and assistant message blocks are allowlisted.
• Tool-result and tool-use blocks are excluded; the plugin does not read arbitrary project files. Ordinary user/assistant text can still contain pasted file contents, terminal output, paths, or repository names and is eligible for processing.
• Supported credential shapes are replaced with [REDACTED] locally in both capture text and automatic recall queries before transmission. Redaction is best-effort, not a guarantee that every secret is recognized. The hosted service redacts again as defense in depth.
• Automatic recall sends a redacted, bounded version of the current prompt to the configured service. This occurs before capture and is a separate processing path.
• Project scope is a keyed opaque identifier. Its derivation key never leaves the device and is separate from the anonymous telemetry id.
• Automatically inferred memories remain personal or project-private. They cannot publish into a team or community.
• Product telemetry is content-free, defaults on, and can be disabled. Its schema accepts only lifecycle event, client version, platform, and a random installation id.
• Hooks fail open: Cairn outages and timeouts do not block normal Claude Code work.
• Capture workers are detached so headless claude -p sessions cannot cancel them during teardown; the allowlisted handoff is piped directly to the worker and is not written to a queue file.

Use /cairn-memory:pause, /cairn-memory:resume, and /cairn-memory:status to control capture and recall.

Paused text is not automatically backfilled. After resume, each session's first
capture hook skips its current unprocessed history (including any early resumed
text); later complete messages are captured. Requests already started before
pause may finish. See the detailed pause boundaries in the privacy guide.

Read the full privacy and threat model. Security reports belong in the private channel described in SECURITY.md, not a public issue.

What is open

This repository is the source of truth for:

• the Claude Code plugin and marketplace manifest;
• local transcript filtering, redaction, and project identity derivation;
• the public HTTP/MCP wire contract and JSON Schemas;
• a local SQLite core with receipts, namespace isolation, capture orchestration,
  MOC organization, model-guided recall, correction and deletion suppression;
• an optional OpenAI adapter, thin local MCP host and inspected install artifact;
• conformance tests and self-host implementation guidance.

The Cairn.ink hosted extraction service, user database, auth, billing, abuse controls, and production operations live in a separate private repository. See Architecture for the boundary and Self-hosting for what is—and is not—available in v0.1.

Status

The released hosted plugin and local developer preview have different readiness
levels. The local install lifecycle is verified, but source-support quality still
fails; broad promotion is not yet cleared. No first-ten-user result or star
target is presented as achieved. See ROADMAP.md and the
proposed adoption experiment.

Development

The dependency-free plugin runtime and test suite require Node.js 20 or newer. Maintainer-only Claude plugin validation requires Node.js 22 and is isolated under tools/plugin-validation so it is never installed with the plugin.

npm test
npm run validate
npm ci --prefix tools/plugin-validation
npm run validate --prefix tools/plugin-validation

For the local store on Node >=22.16 (no dependency installation required):

npm run test:core
npm run demo:store

Contributions are welcome after reading CONTRIBUTING.md and the privacy invariants in docs/protocol.md.