@modusensus/dsh-mneme 0.2.4 → 0.2.5

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-236%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-258%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -19,16 +19,17 @@
 - **Markdown 镜像**：`preferences.md` / `projects.md` / `decisions.md` / `history.md` / `summary.md`，人类可读、可手工编辑（**人工修改优先**合并回库）
 - **4+1 种记忆类型**：`preference`（偏好）/ `project`（项目）/ `decision`（决策）/ `history`（历史）/ `summary`（总览）
 
-### 模型工具（6 个）
+### 模型工具（7 个）
 
 | 工具 | 功能 |
 |------|------|
 | `memory_save` | 记录一条记忆（自动按标题去重合并） |
 | `memory_search` | 全文搜索（中文子串友好，可启用向量语义搜索） |
-| `memory_list` | 按类型分页列出 |
+| `memory_list` | 按类型分页列出（`include_archived=true` 可查看已归档） |
 | `memory_update` | 修改已有记忆 |
 | `memory_delete` | 删除记忆 |
 | `memory_forget` | 抑制注入（降权不删除，可恢复） |
+| `memory_archive` | 归档/恢复记忆（v0.2.5；归档后隐藏于列表/搜索/注入/整理，`archived=false` 可恢复） |
 
 ### 自动注入 + 会话摘要
 
@@ -173,8 +174,8 @@ dsh web
 | `vectorSearchThreshold` | `0.65` | 向量搜索相似度阈值 |
 | `hybridSearchVectorWeight` | `0.6` | 混合搜索向量权重 |
 | `hybridSearchKeywordWeight` | `0.4` | 混合搜索关键词权重 |
-| `rerankEnabled` | `true` | 是否启用 Rerank 精排 |
-| `rerankProvider` | `local` | Rerank 后端：`local` / `none` |
+| `rerankEnabled` | `false` | 是否启用 Rerank 精排（显式开启才加载本地 onnxruntime 模型） |
+| `rerankProvider` | `none` | Rerank 后端：`local` / `none`（默认 `none`） |
 | `rerankModel` | `Xenova/bge-reranker-base` | Rerank 交叉编码模型 |
 | `rerankBatchSize` | `8` | Rerank 批大小 |
 | `rerankMaxCandidates` | `30` | Rerank 最大候选数 |
@@ -196,7 +197,7 @@ dsh web
 │  服务层：saveWithDedupe / injectCandidates        │
 │         / mergeHumanEdits / onWrite 钩子          │
 ├─────────────────────────────────────────────────┤
-│  模型接口：6 个工具 + 自动注入 + 会话摘要          │
+│  模型接口：7 个工具 + 自动注入 + 会话摘要          │
 ├─────────────────────────────────────────────────┤
 │  autoDream：阈值调度 → LLM 决策清单               │
 │            → 校验（fail-safe）→ 应用 → 摘要       │
@@ -213,7 +214,7 @@ src/
 ├── mirror.js         # Markdown 镜像（渲染/解析，人工优先）
 ├── service.js        # 领域逻辑（去重合并、注入筛选、写入钩子）
 ├── config.js         # schemastery 配置 schema
-├── tools.js          # 6 个模型工具（defineTool）
+├── tools.js          # 7 个模型工具（defineTool）
 ├── inject.js         # systemPrompt.context 动态注入
 ├── summarize.js      # 会话结束 LLM 摘要
 ├── dream.js          # autoDream 调度 + runDream（LLM 决策 + 摘要）
@@ -224,7 +225,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 236 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 258 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -233,7 +234,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 236 个测试
+npm test           # 运行 258 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/lib/config.js

@@ -49,8 +49,11 @@ export const Config = z.object({
   hybridSearchKeywordWeight: z.number().min(0).max(1).default(0.4),
 
   // --- semantic: rerank layer (v0.2) --------------------------------------
-  rerankEnabled: z.boolean().default(true),
-  rerankProvider: z.union([z.const("local"), z.const("none")]).default("local"),
+  // Opt-in by default (item ⑥): the local cross-encoder pulls in onnxruntime
+  // (transformers.js) at init, so a bare install must not load it. Only an
+  // explicit rerankEnabled=true + rerankProvider="local" constructs LocalReranker.
+  rerankEnabled: z.boolean().default(false),
+  rerankProvider: z.union([z.const("local"), z.const("none")]).default("none"),
   rerankModel: z.string().default("Xenova/bge-reranker-base"),
   rerankBatchSize: z.natural().min(1).max(64).default(8),
   rerankMaxCandidates: z.natural().min(5).max(100).default(30),

package/lib/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/lib/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/lib/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/lib/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/lib/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();