v1-preview.4 (opt-in preview)

This is a preview. It is not an npm release and is not merged to main.

It is cut from release/v1-preview at 70db0fa4: integration b096e043 (ef38da4a plus a wording fix in the role guide), plus the integration guide. It stacks on the unmerged local V1 chain (#453–#469, feat/local-v1-closeout) and on draft PR #470. Every feature is opt-in: without the flags below, behaviour does not change.

Integration guide: docs/v1-preview-integration.md

Changes since v1-preview.3

All three additions are experimental: their names and shapes may change before they become stable.

• Role profiles and task receipts.
  • Enable with --role-profiles local-v1, together with --method-packages local-v1 --context-read context-read-v1.
  • Agents publish profiles directly, guarded by a dual CAS (expectedCurrentRelease, expectedRegistryRevision).
  • read_role_task_context has five modes: now, then, refresh, compare and file.
  • Reads return a compact task-receipt-v1 receipt. The caller keeps it; a lost receipt cannot be recovered. The default budget is 4,000 tokens.
  • Guide: role profiles.
• Optional context sources.
  • Enable with --context-read-sources relations-one-hop-v1,moc-v1.
  • One-hop typed relations are capped at 4/2/8.
  • MOC title ranking uses the fixed preset rrf-k60-d12-moc-v1.
  • Callers can narrow sources per call, and source diagnostics stay in _meta.
• Card current dependencies.
  • Enable with --private-card-current-dependencies local-v1.
  • A Card can declare the method version it describes. Approval goes through the terminal (review-card --dependencies); the MCP tools always return approval_required.
  • Every current read compares the declaration with what is adopted now. A stale Card shows needs-review with reason codes, and is left out of current evidence, candidates, assembly, relations, MOC and role guidance.
  • Stores without declarations behave exactly as before.
  • Guide: Card current dependencies.
• Upgrade warning.
  • Opting into role profiles or Card dependencies migrates the store one way to schema v32 or v33.
  • .3 binaries refuse such stores; in the smoke test this surfaced as a generic Internal server error at initialize, with the store left intact.
  • To roll back a binary, keep a backup taken before the upgrade.

The interfaces marked stable in .3 (find_memory_candidates, evidence fetch including compact refs, read_memory_context representation-v2, method packages) are unchanged.

Verification

• CI matrix: the CI-equivalent matrix (every ci.yml job plus the role-tokenizer step and both measure:* gates) passed 104/104 at ef38da4a on Node 22.16.0 and 24.15.0.
• Release-commit checks: at 70db0fa4, validate and test:artifact (259/259) pass on both runtimes.
• Reviews: contract §17 v0.11.1, §18 v0.12.2 and §19 v0.13.2 each passed non-author audits. Every implementation passed dual non-author review: U5c-1 and U5c-2 after their fix rounds, and U5c-3 after two fix rounds.
• Installed-tarball smoke (Node 22.16.0):
  • Configuration: --check-config accepts all U5c flags without opening a database, and refuses --context-read-sources without --context-read.
  • Defaults: with no flags, the tool list is byte-identical to .3 (5 tools). With every flag on there are 40.
  • Role profiles:
    • Publishing a role profile works.
    • A stale CAS returns revision_conflict, and an exact action replay is inert.
    • After a second release, then with the old receipt returns the same receipt labelled newer-release-available.
    • refresh issues a new receipt for release 2.
  • Context sources: read_memory_context reports both sources under _meta with the preset rrf-k60-d12-moc-v1, and sources:[] disables them for that call.
  • Card dependencies: both dependency tools return approval_required.
  • Schema: the store is at v33.
• Evidence: all evidence is synthetic and offline.

Install

sha256sum -c cairn-memory-local-preview-0.0.0-preview.1.tgz.sha256
npm init -y && npm install --ignore-scripts ./cairn-memory-local-preview-0.0.0-preview.1.tgz
./node_modules/.bin/cairn-memory --help

Node 22.16 or later is required. The private package version stays 0.0.0-preview.1; the tag identifies the cut.

Known limitations

• MOC at scale: with default caps, MOC ranking degrades at around 10,000 Memories (work_limit, zero MOC candidates).
• Receipts: there is no engine-side receipt lookup or revocation. Receipts authenticate identities, and every call still needs host authorization.
• Han queries: a one-character Han query embedded in a longer run does not match.
• Scope: the build is local only, with no hosted support. Deletion is logical, not physical erasure.
• Contention: a continuously writing process can starve readers, which then receive a retryable storage_busy (contract §16).

🤖 Generated with Claude Code

v1-preview.3 (opt-in preview)

This is a preview. It is not an npm release and is not merged to main.

It is cut from release/v1-preview at 7197d800, which is integration b18dabe0 plus the guide. It stacks on the unmerged local V1 chain (#453–#469, feat/local-v1-closeout) and on draft PRs #470 and #471. Every feature is opt-in: without the flags below, behaviour does not change.

Integration guide: docs/v1-preview-integration.md

Changes since v1-preview.2

• read_memory_context is now a stable preview interface (representation-v2).
  • Breaking change from the experimental .2 output: representation-v1 is removed, and there is no selector to bring it back.
  • The metered model-facing text is only {framing, items}.
  • The snapshot moved to _meta['ink.cairn/context-read-snapshot']. Version, policy and counter moved to diagnostics.
  • Default metadata is omitted, and a receipt identical to the body is written as sameAsBody. Receipts are never dropped.
• Overhead is about 3× smaller. On a small synthetic store, the envelope is about 43 tokens, the first item about 83 and each further item about 82, down from about 250. A one-item read went from 488 to 126 tokens.
• Compact refs.
  • Format: {ns, type, id, rev[, bodyRev], f}. fetch_memory_candidate_evidence accepts them unchanged, and f is an 8-character fence fingerprint.
  • Stale evidence is never served silently. Copy errors and same-revision receipt changes return snapshot_stale; re-run read_memory_context. Changed revisions return revision_conflict.
  • The guide documents the guarantee difference between compact-ref fetch and snapshot fetch, including the MOC parent-move case.
• New non-default policy: rank-first-first-source-v1. rank-first-whole-v1 remains the default.

find_memory_candidates, full-ref evidence fetch and the method packages are unchanged. Assets stay experimental.

Verification

• CI matrix: the CI-equivalent matrix (every ci.yml job) at 7a3ad58e passed 100/100 on Node 22.16.0 and 24.15.0. b18dabe0 differs from it only by removing a worker report.
• Release-commit checks: at b18dabe0 and 7197d800, validate, the import guards and test:artifact (253/253) pass on both runtimes.
• Reviews: the contract (§15.8 v0.10.4) passed four non-author audit rounds, and the implementation passed dual non-author review after two fix rounds.
• Installed-tarball smoke: two memories fit in a 256-token budget (242 tokens used; before this change, none fit). The snapshot is only in _meta. A compact-ref fetch returns ok. A one-character f error returns snapshot_stale. A missing f is refused. After correct_memory, the old ref returns revision_conflict and a fresh read returns revision 2.
• Evidence: all evidence is synthetic and offline.

Install

sha256sum -c cairn-memory-local-preview-0.0.0-preview.1.tgz.sha256
npm init -y && npm install --ignore-scripts ./cairn-memory-local-preview-0.0.0-preview.1.tgz
./node_modules/.bin/cairn-memory --help

Node 22.16 or later is required. The private package version stays 0.0.0-preview.1; the tag identifies the cut.

Known limitations

• Token figures come from a small synthetic store. They are not frozen constants or budget recommendations.
• A one-character Han query embedded in a longer run does not match (中 does not match 中文).
• The build is local only, with no hosted support. Deletion is logical, not physical erasure.
• A continuously writing process can starve readers, which then receive a retryable storage_busy (contract §16).

🤖 Generated with Claude Code

v1-preview.2 (opt-in preview)

This is a preview. It is not an npm release and it is not merged to main.

It is cut from release/v1-preview at 4e53d1dc, which is integration 0a38a991 plus the guide. It stacks on the unmerged local V1 chain (#453–#469, feat/local-v1-closeout) and the draft PRs #470 and #471. Everything is opt-in: without the flags below, behaviour does not change.

Integration guide: docs/v1-preview-integration.md

What changed since v1-preview.1

• Experimental: read_memory_context (budgeted context assembly).
  • It returns one metered text block of whole evidence units (memory bodies and source excerpts) that fits a token budget. The default budget is 1,500 tokens and the range is 64–4,000.
  • The token counter is the local o200k_base and needs no key.
  • Diagnostics are under _meta['ink.cairn/context-read-diagnostics'].
  • Two policies are available: rank-first-whole-v1 (the default; the HR-2 synthetic study kept it) and coverage-first-v1.
  • To enable it, pass --context-read context-read-v1. Programmatic use goes through core.contextRead(...).
• This tool is experimental, outside the versioning promise. Each item currently costs about 250 tokens of overhead, measured on a small synthetic store. Small budgets (under about 512 tokens) may therefore return zero items, and diagnostics report them as oversized. A later preview ships representation-v2, which takes the snapshot out of the metered text and compacts refs and metadata. Its output format will change.
• find_memory_candidates, fetch_memory_candidate_evidence and the method packages are unchanged and stay stable. Assets stay experimental.

Verification

• CI-equivalent matrix (every ci.yml job) at 0a38a991 on Node 22.16.0 and 24.15.0: 100/100 jobs exit 0.
• At 4e53d1dc: validate and test:artifact pass, 253/253 on both runtimes.
• Reviews: U5b passed dual non-author review at aeae00e8. The merge resolution at 0a38a991 passed a non-author review.
• Installed-tarball smoke: the MCP server started with --assets local-v1 --context-read context-read-v1 lists 13 tools. A stored memory is returned by read_memory_context: 1 item, 490 of 1,500 tokens used.
• Evidence is synthetic and offline.

Install

sha256sum -c cairn-memory-local-preview-0.0.0-preview.1.tgz.sha256
npm init -y && npm install --ignore-scripts ./cairn-memory-local-preview-0.0.0-preview.1.tgz
./node_modules/.bin/cairn-memory --help

Node >= 22.16 is required. The private package version stays 0.0.0-preview.1; the tag identifies the cut.

Known limitations

• The representation overhead of read_memory_context is described above.
• A query of one Han character embedded in a longer run is not matched (中 does not match 中文).
• This build runs locally only, with no hosted support. Deletion is logical, not physical erasure.
• A writer that never pauses can starve readers, which then get a retryable storage_busy (contract §16).

🤖 Generated with Claude Code

v1-preview.1 (opt-in preview)

This is a preview. It is not an npm release and is not merged to main.

The build is cut from release/v1-preview at 924d7658, which is integration ce472f25 plus the guide. It stacks on the unmerged local V1 chain (#453–#469, feat/local-v1-closeout) and on the draft PRs #470 and #471. Everything is opt-in, so without the flags below behaviour is unchanged.

Integration guide: docs/v1-preview-integration.md

Changes since v1-preview.0

• Assets can now be used together with context retrieval. The v1-preview.0 known issue is fixed: assets and contextRead work in one handle, and all eight asset/context/method combinations are tested.
• Experimental asset CLI and MCP.
  • Commands: cairn-memory assets import|derive|delete|export. Mutations require typed approval in a real terminal. An export receipt does not contain the destination path.
  • MCP: --assets local-v1 with five read-only tools (list_assets, list_asset_versions, get_asset_version, list_asset_derivatives, read_asset_derivative).
  • Experimental binary method attachments: methods import --attachments local-v1.
  • Assets remain experimental and are outside the versioning promise.
• Schema hardening (v31, 72 objects).
  • Tombstones cannot be resurrected through INSERT OR REPLACE, hidden-rowid or replacement updates.
  • Trigger-set validation is complete.
  • Premature-artifact detection is case-normalized.
  • Snapshot prototype rules are enforced.
• Documented limitation (contract §16). A process that writes continuously, with no pauses, can starve readers; they then receive a retryable storage_busy. Paced workloads meet every contention gate.

The stable preview interfaces are unchanged: context-read-v1 and the method packages.

Verification

• CI-equivalent matrix (every ci.yml job) at ce472f25 on Node 22.16.0 and 24.15.0: 100/100 exit 0.
• At 924d7658: validate and test:artifact pass, 250/250 on both runtimes.
• Installed-tarball smoke: MCP started with --assets local-v1 --context-read context-read-v1 lists 12 tools, and list_assets returns ok.
• Review: every change passed dual non-author review (U4a-1, U4a-2, U4b).
• Evidence: synthetic and offline, plus one earlier live embedding request.

Install

sha256sum -c cairn-memory-local-preview-0.0.0-preview.1.tgz.sha256
npm init -y && npm install --ignore-scripts ./cairn-memory-local-preview-0.0.0-preview.1.tgz
./node_modules/.bin/cairn-memory --help

This requires Node >= 22.16. The private package version stays 0.0.0-preview.1; the tag identifies this cut.

Known limitations

• A one-character Han query embedded in a longer run is not matched (中 does not match 中文).
• The build is local only, with no hosted support. Deletion is logical; it does not physically erase data.
• Continuous writers can starve readers, as described above. Moving to WAL mode is a separate, later decision.

🤖 Generated with Claude Code

v1-preview.0 (opt-in preview)

Preview — not an npm release, and not merged to main. This build is cut from release/v1-preview (80daca28). It stacks on the unmerged local V1 chain (#453–#469, feat/local-v1-closeout) and on draft PRs #470 and #471. Everything is opt-in: without the flags below, behaviour is unchanged.

Integration guide: docs/v1-preview-integration.md

Stable preview interfaces

• Context retrieval (context-read-v1):
  • lexical retrieval with Han-bigram BM25, plus optional OpenAI embeddings (text-embedding-3-small by default), fused with frozen RRF presets;
  • core API: findCandidates, fetchCandidateEvidence (canonical refetch) and refreshContextIndex;
  • MCP: --context-read context-read-v1, with the tools find_memory_candidates and fetch_memory_candidate_evidence;
  • CLI: cairn-memory context refresh;
  • semantic search is off unless requested; a key alone enables nothing; paid calls are budgeted.
• Method packages (method-packages-local-v1):
  • immutable versions, adoption, resolution and pins;
  • cairn-memory methods import|adopt|disable with real-terminal approval;
  • nine read-only MCP tools.

Experimental

• The assets core API (assets-local-v1). There is no CLI or MCP in this build. Known issue: it cannot be configured together with contextRead in one handle.

Fixes in this cut

• The OpenAI adapter now renormalizes provider vectors. Real embeddings, with L2 norms near 1.000225, previously failed validation. This was verified with one live request.

Verification

• CI-equivalent matrix (every ci.yml job) on Node 22.16.0 and 24.15.0 at the base 389512d, with targeted reruns at 80daca28.
• Load-induced timeouts were rerun in isolation and passed.
• Evidence is synthetic and offline, plus one live embedding request.

Install

sha256sum -c cairn-memory-local-preview-0.0.0-preview.1.tgz.sha256
npm init -y && npm install --ignore-scripts ./cairn-memory-local-preview-0.0.0-preview.1.tgz
./node_modules/.bin/cairn-memory --help

Node >= 22.16 is required.

Known limitations

• A one-character Han query embedded in a longer run is not matched (中 does not match 中文).
• The build is local-only: no hosted support, and deletion is logical rather than physical erasure.

🤖 Generated with Claude Code

Cairn Memory v0.3.1

0.3.1 — 2026-10-06

Plugin and marketplace 0.3.1. Protocol stays 0.3.0.

credential/control review corrections

• Restore the frozen shared cursor helper and its parity hash; read Claude-only
  skill-turn metadata in the hook without changing shared cursor semantics.
• Clear old auth verdicts on SessionStart and distinguish server busy/error
  replies from an unreachable service. Invalid endpoints use a fixed diagnostic
  and clear old auth too; token rotation adds no auth probe.
• Give pause/resume the same substituted plugin-data directory as status. Empty
  or unsubstituted plugin-data arguments retain the legacy fallback. Resume also
  resets the same observed endpoint quota gate that status displays.
• Match meta skill directories inside the exact installed plugin root and match
  complete control output lines. Project/marketplace names and appended prose
  do not withhold ordinary answers. Token leak checks use Node fs only.

exclude Cairn's own skill turns from automatic capture

• Withhold Cairn Memory skill invocation records and all answers until the next
  submitted user prompt, using Claude Code command/skill markers. Keep only a
  content-free boolean in the capture cursor across hook processes and retries.
• Also withhold whole assistant status/pause/resume output lines when the
  invocation marker is absent. Ordinary mentions remain conversation.
• Preserve 0.1.0 batch boundaries, message identities and capture event IDs.

truthful Claude Code credential status

• Read hook-written credential observations when the status skill's Bash command
  cannot see Claude Code's sensitive plugin options. Pass the substituted plugin
  data path so status uses the same profile and binding as the hooks.
• Distinguish configured/verified, rejected, unreachable, not yet observed, and
  hook-confirmed missing credentials. Record only configuration presence,
  endpoint and timestamps with a bounded auth outcome; never retain a token,
  token hash/prefix, response body or error text.
• Observe existing authenticated recall/capture requests without extra calls.
  SessionStart's unauthenticated telemetry never verifies a credential.

Cairn Memory v0.2.0

Breaking hosted protocol release (CX-4):

• Accept the truthful client: "codex" capture discriminator alongside unchanged
  0.1 Claude requests. Codex sending still requires verified hosted 0.2.0 support.
• Publish strict HTTP 429 quota_reached alternatives on recall and capture,
  with an optional finite UTC RFC 3339 reset and no success fields. Today's hosted
  quota bodies require H5 adaptation before deployment conformance.
• Publish H4b v1 session-start switches, groups, complete provenance, per-group
  truncation and the combined budget; publish shared hosted pause state,
  generation and resume-barrier semantics. Lifecycle consumption remains CX-5's.
• Upgraded Claude and the shared hosted transport retain pending capture state,
  persist operation-scoped refusals across clients/restarts. State locks never
  span network I/O; normal retries survive interrupted hooks, and resumed probes
  restore their refusal after owner death or deadline expiry.
  Status shows the validated reset or “reset unknown”; explicit quota resume
  permits one attempt per eligible operation and repairs corrupt state.
  Unrecognized 429 is unavailable with a persisted per-operation cooldown:
  validated Retry-After capped at 24 hours, otherwise five minutes; cooldowns
  expire automatically and resume clears them.
  Capture processing accepts HTTP 200 and 202 without advancing the cursor.
  Existing Claude payload bytes, frozen batches and event IDs remain unchanged
  under the explicit D1 quota/concurrency exception.

No hosted/server implementation or hook enablement is included.

Cairn Memory v0.1.0 — Public Alpha

Cairn Memory is a lightweight, private cross-session memory layer for AI
coding agents, with a Source Receipt for every stored memory.

What ships

• Automatic recall and capture hooks for Claude Code.
• Explicit remember_memory, recall_memory, and forget_memory tools over
  remote MCP for Codex and other compatible clients.
• Personal and project-private scopes with opaque project identifiers.
• Local transcript allowlisting and credential redaction before upload.
• Idempotent hosted capture, provenance, pause/resume controls, and fail-open
  hooks that do not block the coding agent during an outage.

Install for Claude Code

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

Create a token at https://cairn.ink/settings/tokens when prompted.

Connect from Codex

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

This is a public alpha. Claude Code has automatic lifecycle memory in v0.1;
Codex uses the explicit MCP tools today, with automatic Codex hook packaging
next on the roadmap.

See the README and privacy contract before installing.