Cairn.ink Memory

Cross-session AI memory you can inspect, correct and forget.

Try local (no account) · Hosted setup · Walkthrough · Verified capabilities · Known limitations · Privacy

Keep a project decision across sessions, with the source text attached. Cairn's open-source memory layer stores memories in your own SQLite file and exposes them through MCP or JavaScript. No Cairn account is needed for local use.

• Inspect the source. Read the source text stored with a memory. A receipt does not guarantee correct interpretation.
• Correct what changed. Update the revision you inspected.
• Forget what should go. Remove a memory from active recall. Deletion and backup boundaries apply.

For example, save “The Harbor prototype uses SQLite,” open a fresh session, and look up that decision with its source. Change it when the decision changes. Walk through the example →

Developer preview. Installed persistence and a narrow real-model memory loop have retained evidence. Default extraction still fails our source-support bar; see known limitations. Save, inspect, correct and forget work without a model key. Semantic recall requires your OpenAI key and sends selected context to that provider.

The demo below records the model-free loop: save, restart, inspect, correct and forget. Its recall step reports model_not_configured.

Recorded responses and regeneration instructions · Watch the 36-second model-free demo (MP4) · Verified capabilities and client support

Install

Choose the mode that fits your workflow:

• Local preview: your SQLite database, explicit MCP memory tools, no Cairn account. Start here to try the open-source memory layer. Semantic recall uses your OpenAI key.
• Hosted integration: memory on cairn.ink, with automatic capture and recall through the Claude Code plugin. Requires a Cairn account, token and compatible service. Explicit hosted MCP is also available.

Try the local memory layer

Prerequisites: Git, Node >=22.16, npm and tar. Recorded installation tests cover Linux x64; other platforms are unverified. Install from this repository: the unscoped npm and PyPI packages named cairn-memory are unrelated projects. The local archive is not published to npm yet.

1. Install into a new directory. Replace the path below with a new absolute directory beneath an existing parent you control.

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

The installer builds this checkout and downloads pinned public npm dependencies without install scripts. It creates app/, data/ and a private installation-receipt.json containing the executable path and MCP settings. It makes no model calls. Keep the receipt private: it contains local paths and identity. Installation details, recovery and backup

2. Run the model-free check. From the source checkout, use the same installation path. No chat-client setup or model key is needed.

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

Expect status: "passed". The check uses a fresh synthetic database and verifies the five tools, receipts, process-restart persistence, correction and forgetting. It strips the model key from the child process; model_not_configured is the expected recall result. Steps and expected results

3. Connect a client. Copy stdio.command and stdio.args from your private installation receipt into the client's local MCP configuration. Keep the same database, owner and project across sessions. See the tested client matrix.

For semantic recall, explicitly supply OPENAI_API_KEY through the MCP process's secret environment. The walkthrough's optional --with-recall path sends synthetic context to OpenAI and incurs model charges; it has no built-in dollar cap. A fully local model path is not yet verified.

For the Hermes native provider, follow its separate setup guide. It uses a profile-local database and owner, plus CAIRN_MEMORY_OPENAI_API_KEY, rather than the generic MCP settings above.

The default local server exposes explicit tools. For opt-in submitted-message capture, project scope and configuration checks, see the installed preview guide. The full evidence and limitations cover extraction failures, long-history retrieval and the boundaries of individual client tests.

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 exact normalized re-admission; paraphrases can still be admitted as new memories. 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 hosted plugin connects to cairn.ink, automatically captures allowlisted conversation text and has its own telemetry defaults. Its service has not been migrated to the local engine.

The v0.2.0 prerelease changes the hosted protocol. Matching server support remains a separate requirement; the release does not deploy a server or enable Codex lifecycle hooks. See release and client compatibility before upgrading.

Install for Claude Code (automatic memory)

From your terminal, run:

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

Or use the slash-command form inside Claude Code:

/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 run /plugin configure cairn-memory@cairn-memory in Claude Code and enter it there. Start a new session after installation.

Agents: ask the user before installing. The hosted plugin captures allowlisted conversation text by default, and the user creates and enters the token themselves. See the hosted plugin privacy contract.

For local development:

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

Hosted explicit MCP for Claude Code

For explicit memory tools without automatic capture, add the remote MCP server:

claude mcp add --transport http --scope user cairn https://cairn.ink/api/mcp

Then sign in from /mcp in Claude Code using browser OAuth.

Connect from Codex (explicit MCP memory)

Codex connects through 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. The hosted tools support explicit remember, recall and forget operations. Automatic Codex lifecycle integration remains under development; the Codex building blocks are disabled by default.

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.
• Prompt recall sends the host conversation id when it matches the 1–200 character ASCII allowlist (A–Z, a–z, 0–9, ., _, :, -). Trusted hooks supply it, never model text; the server stores only an owner-scoped SHA-256 hash. An older strict server gets one exact-schema retry without the optional field.
• 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 and Self-hosting for the public service boundary.

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 Known limitations, ROADMAP.md and the proposed adoption experiment.

Star the repository to follow the local preview and upcoming integrations.

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.