@modusensus/dsh-mneme 0.2.4 → 0.2.5

package/src/dream/decisions.js

@@ -102,79 +102,191 @@ export function validateDecisions(decisions, snapshot, options = {}) {
   return { ok: errors.length === 0, errors };
 }
 
+/** Marker thrown when a decision target changed since the run snapshot. */
+export class CasConflictError extends Error {
+  constructor(action, ids, reason) {
+    super(`cas conflict: ${action} targets changed since snapshot (${reason})`);
+    this.name = "CasConflictError";
+    this.action = action;
+    this.ids = ids;
+  }
+}
+
+function decisionIds(d) {
+  return d.action === "conflict" ? [d.winner, d.loser] : (d.ids ?? []);
+}
+
+/**
+ * CAS guard (item ①): every target memory must still match what the run
+ * snapshot captured — otherwise the decision was computed against stale state
+ * and applying it would overwrite a concurrent edit. Snapshotless replays skip
+ * the guard entirely (per-action idempotency checks handle those). Throws
+ * CasConflictError on the first mismatch; the caller's transaction rolls back.
+ */
+function casGuard(service, snapshot, ids) {
+  if (!snapshot) return;
+  for (const id of ids) {
+    const expect = snapshot.get(id);
+    if (!expect) continue; // not in snapshot: validated elsewhere, skip guard
+    const current = service.getById(id);
+    if (!current) {
+      throw new CasConflictError("deleted", [id], `memory ${id} was removed`);
+    }
+    const changed = expect.updated_at !== undefined
+      ? current.updated_at !== expect.updated_at
+      : current.content !== expect.content || current.title !== expect.title;
+    if (changed) {
+      throw new CasConflictError(
+        "changed",
+        [id],
+        `memory ${id} was concurrently modified (expected updated_at=${expect.updated_at}, got ${current.updated_at})`
+      );
+    }
+  }
+}
+
 /**
  * Apply a validated decision list to the service. Caller must validate first.
- *
- * Note: merge is intentionally non-atomic — the keeper is updated before the
- * other sources are archived, so a failure between the two never loses content.
+ * Each decision runs inside its own SQLite transaction (item ②): the multi-step
+ * mutation of a decision is atomic, so a merge can never leave "keeper updated
+ * but source not archived" or vice versa — a throwing sub-step rolls the whole
+ * decision back.
  *
  * @param decisions - validated decision list.
- * @param service - memory service (saveWithDedupe/getById/update/setArchived).
+ * @param service - memory service (saveWithDedupe/getById/update/setArchived/transaction).
  * @param logger - optional logger ({ warn }); per-decision failures are logged.
- * @returns number of applied decisions (archive counts each archived memory as one).
+ * @param snapshot - optional Map<id, memory> captured before the LLM call; when
+ *   provided, every decision target is CAS-checked against it and a decision
+ *   computed from stale state is skipped and reported as a conflict instead of
+ *   overwriting concurrent writes (item ①).
+ * @returns {{ applied: number, conflicts: Array, failures: Array, committed: Array }}
+ *   applied    - number of decisions/memories actually committed (archive counts
+ *                each archived memory as one, merge/conflict/update count one).
+ *   conflicts  - decisions skipped because a target changed since the snapshot.
+ *   failures   - decisions that threw mid-transaction (fully rolled back).
+ *   committed  - the decisions that actually landed, for outcome/receipt based
+ *                on real committed sub-steps rather than the raw LLM list.
  */
-export function applyDecisions(decisions, service, logger = null) {
+export function applyDecisions(decisions, service, logger = null, snapshot = null) {
   let applied = 0;
+  const conflicts = [];
+  const failures = [];
+  const committed = [];
   for (const [i, d] of decisions.entries()) {
     try {
-      if (d.action === "keep") continue;
-      if (d.action === "archive") {
-        for (const id of d.ids) {
-          const mem = service.getById(id);
-          if (mem && !mem.archived) { service.setArchived(id, true); applied++; }
-        }
-      } else if (d.action === "merge") {
-        const keeper = service.getById(d.keepSource);
-        if (!keeper || keeper.archived) continue;
-        const sources = d.ids.filter((id) => id !== d.keepSource);
-        // Idempotent replay: if every other source is already archived, this
-        // merge already landed — skip so a replayed/concurrent decision never
-        // double-counts or re-applies (guard against duplicate merges).
-        if (sources.every((id) => service.getById(id)?.archived)) continue;
-        service.update(d.keepSource, {
-          title: d.title,
-          content: d.content,
-          importance: d.importance ?? Math.max(keeper.importance, ...d.ids.map((id) => service.getById(id)?.importance ?? 1))
-        });
-        for (const id of sources) {
-          const mem = service.getById(id);
-          if (mem && !mem.archived) { service.setArchived(id, true); }
-        }
-        applied++;
-      } else if (d.action === "conflict") {
-        const winner = service.getById(d.winner);
-        const loser = service.getById(d.loser);
-        if (!winner || !loser) continue;
-        // Idempotent replay: an already-archived loser means the conflict was
-        // already adjudicated — skip so the provenance note is never
-        // re-appended and the loser is not re-archived.
-        if (loser.archived) continue;
-        service.update(d.winner, {
-          content: `${winner.content}\n\n（已否决旧信息：${[...loser.content].slice(0, 100).join("")}）`
-        });
-        service.setArchived(d.loser, true);
-        applied++;
-      } else if (d.action === "update") {
-        const id = d.ids[0];
-        const mem = service.getById(id);
-        if (!mem || mem.archived) continue;
-        // 幂等检查：如果字段已与目标一致则跳过
-        const same = (d.title === undefined || d.title === mem.title)
-          && (d.content === undefined || d.content === mem.content)
-          && (d.importance === undefined || d.importance === mem.importance);
-        if (same) continue;
-        service.update(id, {
-          title: d.title ?? mem.title,
-          content: d.content ?? mem.content,
-          importance: d.importance ?? mem.importance
-        });
-        applied++;
+      // keep is a confirmed no-op: it commits nothing but still records the
+      // per-id disposition so the outcome covers every snapshot memory.
+      if (d.action === "keep") {
+        committed.push({ action: "keep", ids: d.ids });
+        continue;
       }
+      const outcome = applyOne(d, service, snapshot);
+      if (outcome === "skipped") continue;
+      applied += outcome.applied;
+      committed.push(outcome.committed);
     } catch (error) {
-      // Skip individual bad decision; never corrupt the store. The optional
-      // logger makes the failure visible instead of failing silently.
-      logger?.warn?.(`dsh-mneme dream: failed to apply ${d.action} at index ${i}: ${error.message}`);
+      if (error instanceof CasConflictError) {
+        conflicts.push({ index: i, action: d.action, ids: error.ids, reason: error.message });
+        logger?.warn?.(`dsh-mneme dream: ${error.message}`);
+      } else {
+        failures.push({ index: i, action: d.action, ids: decisionIds(d), reason: error.message });
+        logger?.warn?.(`dsh-mneme dream: failed to apply ${d.action} at index ${i}: ${error.message}`);
+      }
     }
   }
-  return applied;
+  return { applied, conflicts, failures, committed };
+}
+
+function applyOne(d, service, snapshot) {
+  switch (d.action) {
+    case "archive": return applyArchive(d, service, snapshot);
+    case "merge": return applyMerge(d, service, snapshot);
+    case "conflict": return applyConflict(d, service, snapshot);
+    default: return applyUpdate(d, service, snapshot);
+  }
+}
+
+function applyArchive(d, service, snapshot) {
+  const targets = d.ids.filter((id) => {
+    const mem = service.getById(id);
+    return mem && !mem.archived; // existing, not-yet-archived rows only
+  });
+  if (targets.length === 0) return "skipped"; // all already archived: idempotent replay
+  service.transaction(() => {
+    casGuard(service, snapshot, d.ids);
+    for (const id of d.ids) {
+      const mem = service.getById(id);
+      if (mem && !mem.archived) service.setArchived(id, true);
+    }
+  });
+  return { applied: targets.length, committed: { action: "archive", ids: targets } };
+}
+
+function applyMerge(d, service, snapshot) {
+  const sources = d.ids.filter((id) => id !== d.keepSource);
+  // Idempotent replay: if every other source is already archived, this merge
+  // already landed — skip so a replayed/concurrent decision never double-counts
+  // or re-applies (guard against duplicate merges).
+  if (sources.every((id) => service.getById(id)?.archived)) return "skipped";
+  service.transaction(() => {
+    casGuard(service, snapshot, d.ids);
+    const keeper = service.getById(d.keepSource);
+    if (!keeper || keeper.archived) return; // missing keeper: no write, still a clean commit
+    service.update(d.keepSource, {
+      title: d.title,
+      content: d.content,
+      importance: d.importance ?? Math.max(keeper.importance, ...d.ids.map((id) => service.getById(id)?.importance ?? 1))
+    });
+    for (const id of sources) {
+      const mem = service.getById(id);
+      if (mem && !mem.archived) service.setArchived(id, true);
+    }
+  });
+  return {
+    applied: 1,
+    committed: { action: "merge", ids: d.ids, keepSource: d.keepSource, title: d.title, content: d.content, importance: d.importance }
+  };
+}
+
+function applyConflict(d, service, snapshot) {
+  const winner = service.getById(d.winner);
+  const loser = service.getById(d.loser);
+  if (!winner || !loser) return "skipped";
+  // Idempotent replay: an already-archived loser means the conflict was already
+  // adjudicated — skip so the provenance note is never re-appended and the loser
+  // is not re-archived.
+  if (loser.archived) return "skipped";
+  service.transaction(() => {
+    casGuard(service, snapshot, [d.winner, d.loser]);
+    const winnerNow = service.getById(d.winner);
+    const loserNow = service.getById(d.loser);
+    if (!winnerNow || !loserNow || loserNow.archived) return;
+    service.update(d.winner, {
+      content: `${winnerNow.content}\n\n（已否决旧信息：${[...loserNow.content].slice(0, 100).join("")}）`
+    });
+    service.setArchived(d.loser, true);
+  });
+  return { applied: 1, committed: { action: "conflict", winner: d.winner, loser: d.loser } };
+}
+
+function applyUpdate(d, service, snapshot) {
+  const id = d.ids[0];
+  const mem = service.getById(id);
+  if (!mem || mem.archived) return "skipped";
+  // 幂等检查：如果字段已与目标一致则跳过
+  const same = (d.title === undefined || d.title === mem.title)
+    && (d.content === undefined || d.content === mem.content)
+    && (d.importance === undefined || d.importance === mem.importance);
+  if (same) return "skipped";
+  service.transaction(() => {
+    casGuard(service, snapshot, [id]);
+    const cur = service.getById(id);
+    if (!cur || cur.archived) return;
+    service.update(id, {
+      title: d.title ?? cur.title,
+      content: d.content ?? cur.content,
+      importance: d.importance ?? cur.importance
+    });
+  });
+  return { applied: 1, committed: { action: "update", ids: [id], title: d.title, content: d.content, importance: d.importance } };
 }

package/src/dream.js

@@ -65,7 +65,10 @@ export function parseReceipt(receipt) {
   const parts = receipt.split(":");
   if (parts.length !== 8 || parts[0] !== "dsh-mneme" || parts[1] !== "run") return undefined;
   const [, , runId, status, snapshotHash, inputCount, applied, summaryStored] = parts;
-  if (!runId || !/^(ok|failed)$/.test(status)) return undefined;
+  // reconcile = decisions validated but one or more did not commit (CAS
+  // conflict / transaction rollback) — the store diverges from the decision
+  // list and the run must be reconciled, never reported as a fake ok.
+  if (!runId || !/^(ok|failed|reconcile)$/.test(status)) return undefined;
   const count = Number(inputCount);
   const appliedN = Number(applied);
   if (!Number.isInteger(count) || !Number.isInteger(appliedN)) return undefined;
@@ -282,7 +285,11 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // (e.g. summary step failed after consolidation), so the partial write is
     // replayable too.
     const finish = (result) => {
-      const status = result.ok ? "ok" : "failed";
+      // status is derived from what actually committed: ok only when the full
+      // decision list landed; reconcile when decisions were validated but some
+      // did not commit (CAS conflict / rollback); failed on any LLM/validation
+      // error. No fake "ok" for a partial commit.
+      const status = result.status ?? (result.ok ? "ok" : "failed");
       const applied = result.applied ?? 0;
       const summaryStored = result.summary ?? false;
       const receipt = buildReceipt({ runId, status, snapshotHash, inputCount: snapshot.size, applied, summaryStored });
@@ -407,7 +414,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       }
     }
 
-    const applied = applyDecisions(decisions, service, logger);
+    // CAS-guarded, per-decision-transactional apply against the run snapshot:
+    // a target changed during the LLM call is skipped and reported as a
+    // conflict instead of being overwritten (item ①).
+    const { applied, conflicts, failures, committed } = applyDecisions(decisions, service, logger, snapshot);
     // Attach the pre-update snapshot to the audit copy of each update decision
     // so the recorded row shows the before/after delta, not just the target.
     const auditDecisions = decisions.map((d) =>
@@ -415,7 +425,13 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         ? { ...d, _before: updateSnapshots[d.ids[0]] }
         : d
     );
-    const outcome = buildOutcome(decisions);
+    // Outcome is derived from the ACTUALLY committed sub-steps, never from the
+    // raw LLM decision list — a merge whose archive step rolled back must not
+    // claim "merge-archived" (item ②). Conflicts/failures ride along so the
+    // audit row records why the run diverged.
+    const outcome = { ...buildOutcome(committed), conflicts, failures };
+    // Decisions validated but not fully committed → reconcile (not ok).
+    const partial = conflicts.length > 0 || failures.length > 0;
 
     // Keep the vector index consistent with the post-dream store state.
     if (semantic?.embedder && semantic?.vectorIndex) {
@@ -460,7 +476,16 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         } catch { /* best-effort */ }
       }
     }
-    return finish({ ok: true, applied, decisions: auditDecisions, outcome, summary: summaryStored });
+    return finish({
+      ok: !partial,
+      status: partial ? "reconcile" : "ok",
+      applied,
+      decisions: auditDecisions,
+      outcome,
+      conflicts,
+      failures,
+      summary: summaryStored
+    });
   }
 
   return { maybeSchedule, runDream, dispose };

package/src/index.js

@@ -83,7 +83,9 @@ export const apply = (ctx, config) => {
   }
 
   // Cross-encoder rerank over recall candidates. Best-effort: a failed model
-  // load only disables reranking, never search itself.
+  // load only disables reranking, never search itself. Explicit opt-in only
+  // (rerankEnabled defaults to false): constructing LocalReranker is what pulls
+  // in onnxruntime, so the default config never loads it (item ⑥).
   if (cfg.rerankEnabled && cfg.rerankProvider === "local") {
     try {
       reranker = new LocalReranker({

package/src/mirror.js

@@ -92,10 +92,16 @@ export function createMirror(dir) {
         if (lastSep) body = body.slice(0, lastSep.index);
         body = body.trim();
 
+        // The machine-written "更新时间" line records the store's updated_at at
+        // render time — the version token for detecting a concurrent store write
+        // during a three-way merge of human edits (see service.syncMirror).
+        const block = text.slice(blockStart, blockEnd);
+        const updatedMatch = block.match(/- \*\*更新时间\*\*: ([^\n]+)/);
         edits.push({
           id: anchor[1],
           title: titleMatch ? unescape(titleMatch[1]).trim() : undefined,
-          content: body
+          content: body,
+          updated_at: updatedMatch ? updatedMatch[1].trim() : undefined
         });
 
         const lineEnd = text.indexOf("\n", blockStart);

package/src/service.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { TYPE_FILE } from "./mirror.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
@@ -15,7 +16,14 @@ export function createService({ store, mirror, config, onWrite }) {
   let vectorIndex = null;
   let reranker = null;
 
+  // Transaction nesting depth. Inside service.transaction the per-mutation side
+  // effects (mirror render, write notify, re-embed) are deferred so a ROLLBACK
+  // never leaves the mirror file diverged from the database; transaction()
+  // replays them exactly once against the committed state.
+  let txDepth = 0;
+
   function scheduleEmbed(memory) {
+    if (txDepth > 0) return; // deferred to the transaction's commit
     if (embedder && memory?.id) {
       try { embedder.schedule(memory); } catch { /* ignore */ }
     }
@@ -152,6 +160,7 @@ export function createService({ store, mirror, config, onWrite }) {
    * state toggles, not content writes, so they never notify.
    */
   function notifyWrite() {
+    if (txDepth > 0) return; // deferred to the transaction's commit
     if (onWrite) {
       try { onWrite(); } catch { /* ignore */ }
     }
@@ -160,6 +169,31 @@ export function createService({ store, mirror, config, onWrite }) {
     }
   }
 
+  /**
+   * Run several store mutations atomically (SQLite BEGIN/COMMIT/ROLLBACK) and
+   * fire the deferred side effects once against the committed state. A throwing
+   * body rolls the whole batch back — no partial writes, no diverged mirror.
+   * Errors propagate to the caller. NOTE: the commit path re-renders the mirror
+   * and notifies subscribers, but re-embedding is left to the caller (the dream
+   * flow re-embeds through maintainIndexAfterDream).
+   */
+  function transaction(fn) {
+    store.db.exec("BEGIN");
+    txDepth++;
+    try {
+      const result = fn();
+      store.db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      try { store.db.exec("ROLLBACK"); } catch { /* store may be closed */ }
+      throw error;
+    } finally {
+      txDepth--;
+      syncMirror();
+      notifyWrite();
+    }
+  }
+
   /**
    * Save a memory, merging into an existing one when title matches within the same type.
    * @returns {{action: "created"|"merged", memory: object}}
@@ -253,12 +287,62 @@ export function createService({ store, mirror, config, onWrite }) {
   }
 
   /**
-   * Re-render the human-editable mirror after any store mutation. Only
+   * Three-way merge of in-flight human mirror edits before a re-render.
+   * Runs on every syncMirror, so a human edit made between two store writes is
+   * never silently overwritten by the next sync (human priority is not limited
+   * to startup). Per edited entry:
+   *   - file changed only → human wins; the edit is merged back into the store.
+   *   - file AND store changed → real three-way conflict: keep the human edit
+   *     and append a marker preserving the store's concurrent version, so no
+   *     side is dropped.
+   *   - store changed only → store wins (the file is simply re-rendered).
+   * Only title/content are taken (structure fields stay machine-owned, matching
+   * mergeHumanEdits). Returns the memory list to render.
+   */
+  function reconcileHumanEdits(memories) {
+    if (!mirror) return memories;
+    const byType = new Map();
+    for (const m of memories) {
+      if (!byType.has(m.type)) byType.set(m.type, []);
+      byType.get(m.type).push(m);
+    }
+    const result = [];
+    for (const type of Object.keys(TYPE_FILE)) {
+      const list = byType.get(type) ?? [];
+      if (list.length === 0) continue;
+      const editsById = new Map(mirror.readHumanEdits(type).map((e) => [e.id, e]));
+      for (const m of list) {
+        const edit = editsById.get(m.id);
+        if (!edit) { result.push(m); continue; }
+        const humanChanged = (typeof edit.title === "string" && edit.title !== m.title)
+          || (typeof edit.content === "string" && edit.content !== m.content);
+        if (!humanChanged) { result.push(m); continue; }
+        // Store changed since the file was last rendered (file records the
+        // store's updated_at at render time) AND the file was hand-edited.
+        const storeChanged = edit.updated_at !== undefined && m.updated_at !== edit.updated_at;
+        if (storeChanged) {
+          const marker = `\n\n> ⚠️ 并发冲突：人工编辑 vs 记忆库并发更新（${m.updated_at}）\n> 记忆库版本：${m.content}`;
+          store.update(m.id, { title: edit.title, content: `${edit.content}${marker}` });
+        } else {
+          store.update(m.id, { title: edit.title, content: edit.content });
+        }
+        const merged = store.getById(m.id);
+        scheduleEmbed(merged);
+        result.push(merged);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Re-render the human-editable mirror after any store mutation, merging any
+   * in-flight human edits first (never silently overwriting them). Only
    * non-forgotten memories are mirrored: forgotten entries must not reach the
    * human-editable file (a human "edit" could otherwise resurrect them).
    */
   function syncMirror() {
-    if (mirror) mirror.sync(store.list({ limit: 500, includeForgotten: false }));
+    if (txDepth > 0 || !mirror) return; // deferred to the transaction's commit
+    mirror.sync(reconcileHumanEdits(store.list({ limit: 500, includeForgotten: false })));
   }
 
   return {
@@ -266,6 +350,7 @@ export function createService({ store, mirror, config, onWrite }) {
     injectCandidates,
     mergeHumanEdits,
     toApiList,
+    transaction,
     setDreamHook(fn) { dreamHook = fn; },
     setEmbedder(emb) { embedder = emb; },
     setVectorIndex(vi) { vectorIndex = vi; },
@@ -277,7 +362,7 @@ export function createService({ store, mirror, config, onWrite }) {
     embeddedCount: () => store.embeddedCount(),
     list: (o) => store.list(o),
     all: () => store.all(),
-    count: (type) => store.count(type),
+    count: (type, opts) => store.count(type, opts),
     getById: (id) => store.getById(id),
     remove: (id) => {
       store.remove(id);
@@ -312,6 +397,35 @@ export function createService({ store, mirror, config, onWrite }) {
       scheduleEmbed(updated);
       return updated;
     },
+    // Compare-and-set update: applies the patch only when the row still carries
+    // `expectedUpdatedAt`. Returns undefined on a miss (no write) so the caller
+    // can re-read and retry — the primitive that prevents lost updates across
+    // concurrent read-modify-write (see scripts/stress-dsh.js axis 3).
+    compareAndUpdate: (id, expectedUpdatedAt, patch, ctx = {}) => {
+      const old = store.getById(id);
+      const updated = store.compareAndUpdate(id, expectedUpdatedAt, patch);
+      if (updated === undefined) return undefined; // CAS miss: no write, no side effects
+      const hasMeaningfulChange = old && updated && (
+        old.content !== updated.content ||
+        old.title !== updated.title ||
+        old.importance !== updated.importance
+      );
+      if (hasMeaningfulChange && config.reflectionFailureTracking) {
+        store.saveFailure({
+          id: randomUUID(),
+          query: ctx.query ?? null,
+          expected: updated.content,
+          actual: old.content,
+          before: { title: old.title, content: old.content, importance: old.importance },
+          failure_type: "user_correction",
+          memory_id: id
+        });
+      }
+      syncMirror();
+      notifyWrite();
+      scheduleEmbed(updated);
+      return updated;
+    },
     setForget: (id, f) => {
       const updated = store.setForget(id, f);
       syncMirror();

package/src/store.js

@@ -223,6 +223,45 @@ export function createStore(path) {
     db.prepare("DELETE FROM memories WHERE id = ?").run(id);
   }
 
+  /**
+   * Atomic compare-and-set update: applies `patch` only when the row still
+   * carries `expectedUpdatedAt` (the version token read by the caller). Returns
+   * the updated memory on success, or undefined when the row changed since the
+   * caller read it — the caller must re-read and retry. The version guard lives
+   * in the UPDATE's WHERE clause, so a concurrent read-modify-write across
+   * connections cannot silently overwrite a newer value (lost update).
+   */
+  function compareAndUpdate(id, expectedUpdatedAt, patch) {
+    const existing = getById(id);
+    if (!existing) throw new Error(`memory not found: ${id}`);
+    const type = patch.type ?? existing.type;
+    if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
+    if (patch.tags !== undefined && !Array.isArray(patch.tags)) {
+      throw new Error("tags must be an array");
+    }
+    const now = nowIso();
+    const embedding = patch.embedding !== undefined
+      ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
+      : existing.embedding ?? null;
+    const result = db.prepare(
+      `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=?
+       WHERE id=? AND updated_at=?`
+    ).run(
+      type,
+      patch.title ?? existing.title,
+      patch.content ?? existing.content,
+      JSON.stringify(patch.tags ?? existing.tags),
+      Number.isInteger(patch.importance) ? patch.importance : existing.importance,
+      patch.source !== undefined ? patch.source : (existing.source ?? null),
+      embedding,
+      now,
+      id,
+      expectedUpdatedAt
+    );
+    if (result.changes === 0) return undefined; // CAS miss: a concurrent write won
+    return getById(id);
+  }
+
   function setForget(id, forgotten) {
     db.prepare("UPDATE memories SET forgotten = ?, updated_at = ? WHERE id = ?")
       .run(forgotten === true || forgotten === 1 ? 1 : 0, nowIso(), id);
@@ -457,6 +496,7 @@ export function createStore(path) {
     getById,
     save,
     update,
+    compareAndUpdate,
     remove,
     setForget,
     setArchived,

package/src/tools.js

@@ -98,11 +98,12 @@ export function createTools(ctx, service, config, embedder) {
 
     defineTool({
       name: "memory_list",
-      description: "List memory entries by type, high-importance first, then newest, paginated.",
+      description: "List memory entries by type, high-importance first, then newest, paginated. Set include_archived=true to also list archived (hidden) entries so they can be located and restored.",
       parameters: {
         type: { type: "string", enum: ["preference", "project", "decision", "history"], description: "Filter by type; omit for all" },
         limit: { type: "integer", description: "Page size (default 50)" },
-        offset: { type: "integer", description: "Page offset (default 0)" }
+        offset: { type: "integer", description: "Page offset (default 0)" },
+        include_archived: { type: "boolean", description: "Include archived (hidden) entries so they can be found and restored (default false)" }
       },
       output: {
         schema: {
@@ -119,8 +120,14 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(`${value.items.length} memory entries (of ${value.total}).`)
       },
       async execute(args) {
-        const rows = service.toApiList(service.list({ type: args.type, limit: args.limit ?? 50, offset: args.offset ?? 0 }));
-        return { items: rows, total: service.count(args.type) };
+        const includeArchived = args.include_archived === true;
+        const rows = service.toApiList(service.list({
+          type: args.type,
+          limit: args.limit ?? 50,
+          offset: args.offset ?? 0,
+          includeArchived
+        }));
+        return { items: rows, total: service.count(args.type, { includeArchived }) };
       }
     }),
 
@@ -220,6 +227,42 @@ export function createTools(ctx, service, config, embedder) {
         const memory = service.setForget(args.id, args.forgotten ?? true);
         return { memory: { id: memory.id, forgotten: memory.forgotten } };
       }
+    }),
+
+    defineTool({
+      name: "memory_archive",
+      description:
+        "Archive a memory (hide it from active lists, search, injection and dream consolidation) or restore it. " +
+        "Archived entries stay in storage and are recoverable: pass archived=false to restore, and use memory_list with " +
+        "include_archived=true to find archived entries.",
+      parameters: {
+        id: { type: "string", required: true, description: "Memory id" },
+        archived: { type: "boolean", description: "Archive (true, default) or restore (false) the entry" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            memory: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                id: { type: "string", required: true },
+                archived: { type: "boolean", required: true }
+              }
+            }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(`Memory ${value.memory.id} ${value.memory.archived ? "archived" : "restored"}.`)
+      },
+      async execute(args) {
+        if (service.getById(args.id) === undefined) {
+          throw new Error("memory not found");
+        }
+        const memory = service.setArchived(args.id, args.archived ?? true);
+        return { memory: { id: memory.id, archived: memory.archived } };
+      }
     })
   ];