@cairnkeep/cli 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable user-facing changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [2.1.0] - 2026-07-16
+
+### Added
+
+- Add `memory_apply_reviewed` for idempotent application of externally reviewed
+  memory revisions with durable provenance and collision-safe history.
+- Add `memory_invalidate_reviewed` for revision-matched retraction and durable
+  tombstones that prevent delayed writes from resurrecting invalid memory.
+- Add end-to-end checks for replay, supersession, manual changes, retraction,
+  tombstones, and reserved provenance records.
+
+### Changed
+
+- Make history snapshot keys unique when multiple revisions occur in the same
+  millisecond.
+
+The existing memory tools, database locations, and remote HTTP routing contract
+are unchanged. Existing clients remain compatible and reviewed-memory records
+are created only when an integration explicitly invokes the new tools.
+
 ## [2.0.0] - 2026-07-15
 
 ### Breaking
@@ -69,6 +89,7 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
+[2.1.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.3...v2.0.0
 [1.1.3]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.2...v1.1.3
 [1.1.2]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.1...v1.1.2

package/docs/storage.md

@@ -112,6 +112,31 @@ sqlite3 /path/to/project/.agentfs/project.db \
 Treat every database and export archive as sensitive. They may contain source
 paths, decisions, incident details, and other project context.
 
+## Reviewed-memory integration
+
+External review systems should not compose `memory_write`, `memory_read`, and
+`memory_delete` into their own promotion protocol. That sequence is not atomic
+and can delete a newer manual revision during lifecycle invalidation.
+
+Cairnkeep exposes two additive MCP tools for reviewed integrations:
+
+- `memory_apply_reviewed` takes `scope`, `review_id`, `key`, and `value`. It is
+  idempotent for the same review and content, preserves a displaced live value
+  in memory history, and rejects reuse of the review ID with different content.
+- `memory_invalidate_reviewed` takes `scope`, `review_id`, `key`, and an optional
+  `reason`. It removes the live value only when it still matches that reviewed
+  revision. If apply has not arrived yet, it records a tombstone so a delayed
+  apply cannot resurrect invalid memory.
+
+Provenance and tombstones use a hidden reserved namespace in the same scoped
+database. Generic memory writes and deletes cannot modify those records. Review
+IDs must be stable, non-secret idempotency identifiers; evidence payloads and
+credentials do not belong in them.
+
+These tools are for an explicit, trusted integration. Cairnkeep itself does not
+approve candidates, discover an evidence service, or promote memory
+automatically. Existing clients and the original memory tools remain unchanged.
+
 ## Automating trusted personal clients
 
 Keep fleet-specific values in a private dotfiles repository or secret manager,

package/mcp-memory-server/dist/index.js

@@ -29,6 +29,8 @@ const anythingllmSyncScript = process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT
     ? resolve(expandHome(process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT))
     : join(infraRoot, "examples", "anythingllm", "sync_to_anythingllm.py");
 const HISTORY_NAMESPACE = "__history__";
+const REVIEWED_NAMESPACE = "__reviewed__";
+const REVIEW_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const PROJECT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const WORKSPACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 function expandHome(value) {
@@ -180,17 +182,52 @@ async function openScope(scope, create, options = {}) {
 function isHistoryKey(key) {
     return key === HISTORY_NAMESPACE || key.startsWith(`${HISTORY_NAMESPACE}/`);
 }
+function isReviewedKey(key) {
+    return key === REVIEWED_NAMESPACE || key.startsWith(`${REVIEWED_NAMESPACE}/`);
+}
+function assertWritableMemoryKey(key) {
+    if (isHistoryKey(key) || isReviewedKey(key)) {
+        throw new Error(`Keys under ${HISTORY_NAMESPACE}/ and ${REVIEWED_NAMESPACE}/ are reserved.`);
+    }
+}
 function historyPrefix(baseKey) {
     return `${HISTORY_NAMESPACE}/${baseKey}/`;
 }
 function historySnapshotKey(baseKey, timestamp) {
-    return `${historyPrefix(baseKey)}${timestamp}`;
+    return `${historyPrefix(baseKey)}${timestamp}-${randomUUID()}`;
+}
+const reviewedRecordSchema = z.object({
+    schema_version: z.literal(1),
+    review_id: z.string(),
+    key: z.string(),
+    value_hash: z.string(),
+    state: z.enum(["active", "superseded", "invalidated"]),
+    applied_at: z.string(),
+    superseded_at: z.string().optional(),
+    superseded_by: z.string().optional(),
+    invalidated_at: z.string().optional(),
+    invalidation_reason: z.string().optional(),
+});
+function reviewedRecordKey(reviewId) {
+    return `${REVIEWED_NAMESPACE}/${reviewId}`;
+}
+function parseReviewedRecord(value) {
+    const parsed = reviewedRecordSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error("Stored reviewed-memory provenance is invalid; refusing to continue.");
+    }
+    return parsed.data;
+}
+async function inImmediateScopeTransaction(agent, operation) {
+    const transaction = agent.getDatabase().transaction(operation);
+    const immediate = transaction.immediate;
+    return immediate();
 }
 function visibleEntries(entries, includeHistory) {
     if (includeHistory) {
         return entries;
     }
-    return entries.filter((entry) => !isHistoryKey(entry.key));
+    return entries.filter((entry) => !isHistoryKey(entry.key) && !isReviewedKey(entry.key));
 }
 async function listEntries(scope, prefix = "", options = {}) {
     const agent = await openScope(scope, false, options);
@@ -759,9 +796,7 @@ function createMemoryServer(context = {}) {
             promote_to: z.string().optional(),
         }),
     }, async ({ scope, key, value, promote_to }) => {
-        if (isHistoryKey(key)) {
-            throw new Error(`Keys under ${HISTORY_NAMESPACE}/ are reserved for memory history.`);
-        }
+        assertWritableMemoryKey(key);
         const targets = promote_to && promote_to !== scope ? [scope, promote_to] : [scope];
         // Collision-safe: in the unified store, writes from different repos/machines
         // can share a key. If a different value already exists, preserve the old one
@@ -824,6 +859,9 @@ function createMemoryServer(context = {}) {
             key: z.string().min(1),
         }),
     }, async ({ scope, key }) => {
+        if (isReviewedKey(key)) {
+            throw new Error(`Keys under ${REVIEWED_NAMESPACE}/ are reserved for reviewed-memory provenance.`);
+        }
         const agent = await openScope(scope, false, scopeOptions);
         if (agent) {
             try {
@@ -887,9 +925,7 @@ function createMemoryServer(context = {}) {
             reason: z.string().optional(),
         }),
     }, async ({ scope, key, value, reason }) => {
-        if (isHistoryKey(key)) {
-            throw new Error(`Keys under ${HISTORY_NAMESPACE}/ are reserved for memory history.`);
-        }
+        assertWritableMemoryKey(key);
         const agent = await openScope(scope, true, scopeOptions);
         if (!agent) {
             throw new Error(`Unable to open scope ${scope}.`);
@@ -929,6 +965,207 @@ function createMemoryServer(context = {}) {
             await agent.close();
         }
     });
+    server.registerTool("memory_apply_reviewed", {
+        description: "Idempotently apply a human-reviewed memory revision with durable provenance.",
+        inputSchema: z.object({
+            scope: z.string(),
+            review_id: z.string().regex(REVIEW_ID_PATTERN),
+            key: z.string().min(1),
+            value: z.string(),
+        }),
+    }, async ({ scope, review_id, key, value }) => {
+        assertWritableMemoryKey(key);
+        const agent = await openScope(scope, true, scopeOptions);
+        if (!agent) {
+            throw new Error(`Unable to open scope ${scope}.`);
+        }
+        try {
+            const payload = await inImmediateScopeTransaction(agent, async () => {
+                const recordKey = reviewedRecordKey(review_id);
+                const valueHash = hashText(value);
+                const stored = await agent.kv.get(recordKey);
+                if (stored !== undefined) {
+                    const existing = parseReviewedRecord(stored);
+                    if (existing.key !== key || existing.value_hash !== valueHash) {
+                        throw new Error(`Review id ${review_id} was already used with different content.`);
+                    }
+                    if (existing.state !== "active") {
+                        throw new Error(`Review id ${review_id} is ${existing.state} and cannot be reapplied.`);
+                    }
+                    return {
+                        ok: true,
+                        scope,
+                        review_id,
+                        key,
+                        applied: false,
+                        idempotent: true,
+                        snapshot_key: null,
+                    };
+                }
+                const appliedAt = new Date().toISOString();
+                const provenance = await agent.kv.list(`${REVIEWED_NAMESPACE}/`);
+                for (const entry of provenance) {
+                    const previousRecord = parseReviewedRecord(entry.value);
+                    if (previousRecord.state === "active" && previousRecord.key === key) {
+                        await agent.kv.set(entry.key, {
+                            ...previousRecord,
+                            state: "superseded",
+                            superseded_at: appliedAt,
+                            superseded_by: review_id,
+                        });
+                    }
+                }
+                const previous = await agent.kv.get(key);
+                const previousValue = previous === undefined ? undefined : normalizeValue(previous);
+                let snapshotKey = null;
+                if (previousValue !== undefined && previousValue !== value) {
+                    snapshotKey = historySnapshotKey(key, appliedAt);
+                    await agent.kv.set(snapshotKey, {
+                        value: previousValue,
+                        superseded_at: appliedAt,
+                        superseded_reason: `reviewed memory ${review_id}`,
+                    });
+                }
+                await agent.kv.set(key, value);
+                await agent.kv.set(recordKey, {
+                    schema_version: 1,
+                    review_id,
+                    key,
+                    value_hash: valueHash,
+                    state: "active",
+                    applied_at: appliedAt,
+                });
+                return {
+                    ok: true,
+                    scope,
+                    review_id,
+                    key,
+                    applied: true,
+                    idempotent: false,
+                    snapshot_key: snapshotKey,
+                };
+            });
+            return {
+                content: [{ type: "text", text: asToolText(payload) }],
+                structuredContent: payload,
+            };
+        }
+        finally {
+            await agent.close();
+        }
+    });
+    server.registerTool("memory_invalidate_reviewed", {
+        description: "Invalidate a reviewed revision, removing it only when the live value still matches.",
+        inputSchema: z.object({
+            scope: z.string(),
+            review_id: z.string().regex(REVIEW_ID_PATTERN),
+            key: z.string().min(1),
+            reason: z.string().max(512).optional(),
+        }),
+    }, async ({ scope, review_id, key, reason }) => {
+        assertWritableMemoryKey(key);
+        const agent = await openScope(scope, true, scopeOptions);
+        if (!agent) {
+            throw new Error(`Unable to open scope ${scope}.`);
+        }
+        try {
+            const payload = await inImmediateScopeTransaction(agent, async () => {
+                const recordKey = reviewedRecordKey(review_id);
+                const stored = await agent.kv.get(recordKey);
+                if (stored === undefined) {
+                    const invalidatedAt = new Date().toISOString();
+                    await agent.kv.set(recordKey, {
+                        schema_version: 1,
+                        review_id,
+                        key,
+                        value_hash: "",
+                        state: "invalidated",
+                        applied_at: invalidatedAt,
+                        invalidated_at: invalidatedAt,
+                        ...(reason ? { invalidation_reason: reason } : {}),
+                    });
+                    return {
+                        ok: true,
+                        scope,
+                        review_id,
+                        key,
+                        invalidated: true,
+                        idempotent: false,
+                        missing: true,
+                        removed: false,
+                        current_changed: false,
+                        snapshot_key: null,
+                    };
+                }
+                const record = parseReviewedRecord(stored);
+                if (record.key !== key) {
+                    throw new Error(`Review id ${review_id} belongs to a different memory key.`);
+                }
+                if (record.state === "invalidated") {
+                    return {
+                        ok: true,
+                        scope,
+                        review_id,
+                        key: record.key,
+                        invalidated: false,
+                        idempotent: true,
+                        missing: record.value_hash === "",
+                        removed: false,
+                        current_changed: false,
+                        snapshot_key: null,
+                    };
+                }
+                const invalidatedAt = new Date().toISOString();
+                let currentChanged = false;
+                let removed = false;
+                let snapshotKey = null;
+                if (record.state === "active") {
+                    const current = await agent.kv.get(record.key);
+                    if (current !== undefined) {
+                        const currentValue = normalizeValue(current);
+                        if (hashText(currentValue) === record.value_hash) {
+                            snapshotKey = historySnapshotKey(record.key, invalidatedAt);
+                            await agent.kv.set(snapshotKey, {
+                                value: currentValue,
+                                superseded_at: invalidatedAt,
+                                superseded_reason: reason ?? `reviewed memory ${review_id} invalidated`,
+                            });
+                            await agent.kv.delete(record.key);
+                            removed = true;
+                        }
+                        else {
+                            currentChanged = true;
+                        }
+                    }
+                }
+                await agent.kv.set(recordKey, {
+                    ...record,
+                    state: "invalidated",
+                    invalidated_at: invalidatedAt,
+                    ...(reason ? { invalidation_reason: reason } : {}),
+                });
+                return {
+                    ok: true,
+                    scope,
+                    review_id,
+                    key: record.key,
+                    invalidated: true,
+                    idempotent: false,
+                    missing: false,
+                    removed,
+                    current_changed: currentChanged,
+                    snapshot_key: snapshotKey,
+                };
+            });
+            return {
+                content: [{ type: "text", text: asToolText(payload) }],
+                structuredContent: payload,
+            };
+        }
+        finally {
+            await agent.close();
+        }
+    });
     server.registerTool("memory_history", {
         description: "Read prior versions of a memory entry from the hidden history namespace.",
         inputSchema: z.object({

package/mcp-memory-server/package.json

@@ -22,8 +22,9 @@
         "check:explore-cache": "node scripts/smoke-explore-cache.mjs",
         "check:explore-crossref": "node scripts/smoke-explore-crossref.mjs",
         "check:route-guard": "node scripts/smoke-route-guard.mjs",
+        "check:reviewed-memory": "node scripts/smoke-reviewed-memory.mjs",
         "test": "npm run test:smoke",
-        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard",
+        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory",
         "test:search": "npm run build && npm run check:search",
         "test:memory": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:search",
         "test:all": "npm run test:memory"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",