Cairn.ink Memory README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Cairn.ink Memory listing page.
Cairn.ink Memory
Lightweight cross-session memory for AI agents, with receipts.
Install · Quickstart · Walkthrough · Known limitations · Privacy · Hosted service
Every memory Cairn keeps comes with a receipt: the exact source text it was learned from. Inspect the receipt, correct the memory at that revision, or forget it and it stays forgotten, even when a later capture would have re-admitted it. Memories live in a local SQLite file. No account is needed.
Remember something in one session, start a fresh process, and recall it in the next with its receipt attached; then forget it and confirm it is gone. The cross-session walkthrough reproduces that loop with synthetic data. Model-free remember, inspect, correct and forget need no key; semantic recall needs an OpenAI key you supply explicitly.
Rendered from the recorded tool responses of one real keyless run; see how to regenerate it.
The thin MCP server and the JavaScript API share one public core; the five MCP tools are explicit memory operations, not automatic transcript capture.
Status: developer preview. The installed remember, restart, sourced-recall and forget loop passes on a real model. Extraction quality does not yet meet our own bar: the frozen evaluation and every retained failure are collected in Known limitations. Read it before relying on recall.
Install
This is Cairn.ink Memory (github.com/Cairn-ink/cairn-memory, hosted at
cairn.ink). The npm package cairn-memory and the PyPI package
cairn-memory are unrelated projects; do not install those for this.
There are two ways to run Cairn: hosted on cairn.ink with the Claude Code plugin for automatic memory (needs a cairn.ink token), or the local open-source layer, which needs no account and is a developer preview. For the hosted plugin, run:
Create a personal access token at https://cairn.ink/settings/tokens,
then run /plugin configure cairn-memory@cairn-memory in Claude Code and
start a new session. See
Install for Claude Code for
the slash-command form.
Agents: ask the user before installing. The hosted plugin captures allowlisted conversation text to cairn.ink by default, and the user creates and enters the token themselves. See the hosted plugin privacy contract.
To use explicit memory tools on cairn.ink without automatic capture, add the remote MCP server:
Then sign in from /mcp in Claude Code (browser OAuth). Codex users: see
Connect from Codex.
The local, no-account developer preview installed from source is the section directly below: Try the local memory layer.
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.
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.
For explicit submitted-message capture, add
--capture-qualification source-bound-v2 to the install command. The generated
settings then expose a sixth tool, capture_memory; omission keeps five tools.
See the capture → source-only recall → inspection walkthrough
for key setup, model costs and interpretation limits. This is not passive capture.
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):
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):
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.
| Tool | Purpose |
|---|---|
remember_memory | Explicitly save one memory and its receipt |
recall_memory | Model-guided retrieval of current memories and receipts |
inspect_memory | List memories (optionally active/historical), or inspect an ID, revision and receipts |
correct_memory | Replace content at the revision you inspected |
forget_memory | Logically delete at the revision you inspected |
Start with the first-value guide to distinguish the no-key installation check from the real-model Hermes conversation experiment, including the two model credentials and profile/database boundaries. The first live evidence records successful cross-session save/read/correct/read, a later recall failure before forgetting, and weak long-history QA results. Full real-model reliability is not established. 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; the full real-model lifecycle 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:
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:
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:
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
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 -psessions 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 Known limitations, 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.
For the local store on Node >=22.16 (no dependency installation required):
Contributions are welcome after reading CONTRIBUTING.md and the privacy invariants in docs/protocol.md.