@modusensus/dsh-mneme 0.2.7 → 0.2.9

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-263%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-355%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -225,7 +225,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 263 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 355 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -234,7 +234,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 263 个测试
+npm test           # 运行 355 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/lib/config.js

@@ -13,6 +13,10 @@ export const Config = z.object({
   dreamProvider: z.string(),
   dreamModel: z.string(),
   dreamMaxTokens: z.natural().min(256).max(32768).default(4096),
+  // Rule version for dream adjudication: when this bumps, older dream_runs
+  // degrade to historical evidence (their receipts no longer drive live
+  // decisions). Default 0 = no versioning in use yet.
+  policyEpoch: z.natural().min(0).max(1000000).default(0),
 
   // --- API protection ------------------------------------------------------
   // Optional shared token for the plugin's HTTP API. Empty (default) keeps
@@ -63,5 +67,12 @@ export const Config = z.object({
   reflectionUpdateEnabled: z.boolean().default(true),
   reflectionFailureTracking: z.boolean().default(true),
   reflectionUpdateMaxPerRun: z.natural().min(0).max(5).default(2),
-  reflectionUpdateMinAgeHours: z.natural().min(0).max(168).default(24)
+  reflectionUpdateMinAgeHours: z.natural().min(0).max(168).default(24),
+
+  // --- conflict freeze: manual review for conflicting memories (v0.2.1) ---
+  // Opt-in by default: when true, conflicting memories are not auto-merged
+  // and are marked as pending manual review instead.
+  conflictFreezeEnabled: z.boolean().default(false),
+  // Maximum number of frozen conflicts to keep pending for manual review.
+  conflictFreezeMaxPending: z.natural().min(1).max(1000).default(100),
 });

package/lib/dream/decisions.js

@@ -244,7 +244,7 @@ function applyMerge(d, service, snapshot) {
   });
   return {
     applied: 1,
-    committed: { action: "merge", ids: d.ids, keepSource: d.keepSource, title: d.title, content: d.content, importance: d.importance }
+    committed: { action: "merge", ids: d.ids, keepSource: d.keepSource, title: d.title, content: d.content, importance: d.importance, count_before: d.ids.length, count_after: 1 }
   };
 }
 
@@ -266,7 +266,7 @@ function applyConflict(d, service, snapshot) {
     });
     service.setArchived(d.loser, true);
   });
-  return { applied: 1, committed: { action: "conflict", winner: d.winner, loser: d.loser } };
+  return { applied: 1, committed: { action: "conflict", winner: d.winner, loser: d.loser, count_before: 2, count_after: 1 } };
 }
 
 function applyUpdate(d, service, snapshot) {
@@ -288,5 +288,5 @@ function applyUpdate(d, service, snapshot) {
       importance: d.importance ?? cur.importance
     });
   });
-  return { applied: 1, committed: { action: "update", ids: [id], title: d.title, content: d.content, importance: d.importance } };
+  return { applied: 1, committed: { action: "update", ids: [id], title: d.title, content: d.content, importance: d.importance, count_before: 1, count_after: 1 } };
 }

package/lib/dream.js

@@ -100,6 +100,78 @@ export function buildOutcome(decisions) {
   return { byId };
 }
 
+/**
+ * Content-addressed digest of the memories a verdict was decided against
+ * (id + title + content + importance), sorted by id so identical inputs always
+ * hash the same. This is the per-record "判定依据" fingerprint: a receipt whose
+ * digest cannot be reproduced from the involved memories is a bare claim, and a
+ * digest match with a divergent outcome pinpoints drift to the exact record.
+ */
+export function hashDecisionInput(memories) {
+  const canon = (memories ?? [])
+    .map((m) => [m.id, m.title, m.content, m.importance])
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map((p) => p.map((x) => String(x ?? "")).join("
"))
+    .join("");
+  return createHash("sha256").update(canon).digest("hex");
+}
+
+/**
+ * Build the per-record receipts for a run's actually-committed mutable verdicts
+ * (merge/conflict/update) — one row per verdict in the receipt_chain. Inputs
+ * are drawn from the run snapshot (what the LLM actually arbitrated against),
+ * and the idempotency counters count_before → count_after come from the
+ * committed sub-step, so replaying the same decision must reproduce the same
+ * numbers. verdict starts "live"; a later policy_epoch upgrade will batch-mark
+ * older verdicts "historical" (a receipt_chain rewrite driven by the store's
+ * getLatestPolicyEpoch — out of scope for this pass), while "revoked" is
+ * reserved for verdicts later overturned by an explicit human decision.
+ */
+function buildRecordReceipts({ runId, committed, snapshot, policyEpoch }) {
+  const at = (id) => snapshot?.get?.(id);
+  const receipts = [];
+  for (const c of committed ?? []) {
+    const base = {
+      run_id: runId,
+      verdict: "live",
+      count_before: c.count_before,
+      count_after: c.count_after,
+      policy_epoch: policyEpoch,
+      created_at: new Date().toISOString()
+    };
+    if (c.action === "merge") {
+      receipts.push({
+        ...base,
+        receipt_id: randomUUID(),
+        record_id: c.keepSource,
+        kind: "merge",
+        input_digest: hashDecisionInput((c.ids ?? []).map(at).filter(Boolean)),
+        keep_source: c.keepSource,
+        sources: c.ids
+      });
+    } else if (c.action === "conflict") {
+      receipts.push({
+        ...base,
+        receipt_id: randomUUID(),
+        record_id: c.winner,
+        kind: "conflict",
+        input_digest: hashDecisionInput([at(c.winner), at(c.loser)].filter(Boolean)),
+        winner_id: c.winner,
+        loser_id: c.loser
+      });
+    } else if (c.action === "update") {
+      receipts.push({
+        ...base,
+        receipt_id: randomUUID(),
+        record_id: c.ids[0],
+        kind: "update",
+        input_digest: hashDecisionInput([at(c.ids[0])].filter(Boolean))
+      });
+    }
+  }
+  return receipts;
+}
+
 /**
  * Consume an LLM stream and return the accumulated text. Direct text-delta
  * accumulation covers both the real protocol ({type:"text-delta", index, text})
@@ -278,6 +350,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     const route = resolveRoute(ctx, config, logger);
     const runId = randomUUID();
     const snapshotHash = hashSnapshot([...snapshot.values()]);
+    // Conflict freeze (opt-in): when enabled, conflict decisions are parked for
+    // manual review instead of auto-adjudicated. Read once up front so the
+    // prompt hint and the apply-split agree on the same gate.
+    const freezeEnabled = config.conflictFreezeEnabled === true;
     // Every exit (success or failure) funnels through `finish`, which writes
     // the audit row + receipt. A record failure is logged, never thrown —
     // auditing must not break the consolidation path. Failed runs still
@@ -304,6 +380,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
           model: route?.model,
           snapshot_hash: snapshotHash,
           input_count: snapshot.size,
+          // 裁决规则版本号：config.policyEpoch（默认 0）。规则升级后该行保留
+          // 当时的 epoch，旧裁决据此降级为历史证据（store 层 getLatestPolicyEpoch
+          // 只负责读取当前生效版本，写入由这里完成）。
+          policy_epoch: config.policyEpoch ?? 0,
           // Full input snapshot (canonical fields) so the exact arbitration
           // input can be rebuilt offline from the audit row alone — the
           // digest + decisions + outcome triple makes silent errors locatable
@@ -364,6 +444,12 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       ).join("\n");
     }
 
+    // Freeze-aware prompt: in freeze mode the conflict branch still outputs
+    // winner/loser (validation requires them) but they are treated as tentative
+    // candidates — the human makes the final call, not the model.
+    const consolidationPrompt = freezeEnabled
+      ? CONSOLIDATION_PROMPT + `\n\n当前为「冲突冻结」模式：检测到内容矛盾的条目时，仍请输出 conflict，并以 winner/loser 作为候选、reason 说明理由；冲突不会被自动裁决，而会冻结待人工确认。`
+      : CONSOLIDATION_PROMPT;
     let decisionText;
     try {
       decisionText = await streamText(ctx, {
@@ -372,7 +458,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         purpose: "compaction",
         maxTokens: config.dreamMaxTokens ?? 4096,
         messages: [
-          { role: "system", content: [{ type: "text", text: CONSOLIDATION_PROMPT }] },
+          { role: "system", content: [{ type: "text", text: consolidationPrompt }] },
           { role: "user", content: [{ type: "text", text: listText }] }
         ]
       });
@@ -416,10 +502,59 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       }
     }
 
+    // Conflict freeze (opt-in): when enabled, conflict decisions are not
+    // auto-adjudicated — no winner kept, no loser archived. The pair is parked
+    // in conflict_pending for human review instead. Best-effort: a store
+    // failure here must never block the run (fail-safe — the memories are left
+    // untouched and nothing is arbitrated). The cap (conflictFreezeMaxPending)
+    // bounds the review queue; overflow is skipped with a warning.
+    let frozenCount = 0;
+    const frozenIds = [];
+    const applyList = freezeEnabled ? decisions.filter((d) => d.action !== "conflict") : decisions;
+    if (freezeEnabled) {
+      const conflictsToFreeze = decisions.filter((d) => d.action === "conflict");
+      if (conflictsToFreeze.length > 0) {
+        try {
+          const maxPending = Number.isInteger(config.conflictFreezeMaxPending) ? config.conflictFreezeMaxPending : 100;
+          const pendingNow = service.countConflictPending();
+          const budget = Math.max(0, maxPending - pendingNow);
+          const toFreeze = conflictsToFreeze.slice(0, budget);
+          if (conflictsToFreeze.length > budget) {
+            logger?.warn?.(`dsh-mneme dream: conflict freeze queue full (${pendingNow}/${maxPending}), skipped ${conflictsToFreeze.length - budget} conflict(s)`);
+          }
+          for (const d of toFreeze) {
+            try {
+              service.saveConflictPending({ run_id: runId, memory_a: d.winner, memory_b: d.loser, reason: d.reason });
+              frozenCount++;
+              frozenIds.push(d.winner, d.loser);
+            } catch (error) {
+              logger?.warn?.(`dsh-mneme dream: failed to freeze conflict ${d.winner}/${d.loser}: ${String(error)}`);
+            }
+          }
+        } catch (error) {
+          logger?.warn?.(`dsh-mneme dream: conflict freeze lookup failed: ${String(error)}`);
+        }
+      }
+    }
+
     // 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);
+    // conflict instead of being overwritten (item ①). Frozen conflicts are
+    // excluded from this list (they are parked, not applied).
+    const { applied, conflicts, failures, committed } = applyDecisions(applyList, service, logger, snapshot);
+    // Per-record receipt chain: one row per actually-committed merge/conflict/
+    // update verdict, stamped with the decision-basis digest + idempotency
+    // counters (count_before → count_after). Written here, before the run audit
+    // row, so the verdict trail always precedes the run trail it belongs to.
+    // Bookkeeping: a write failure is logged and swallowed — it must never
+    // block the consolidation flow.
+    try {
+      for (const r of buildRecordReceipts({ runId, committed, snapshot, policyEpoch: config.policyEpoch ?? 0 })) {
+        service.saveReceipt(r);
+      }
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme dream: failed to write per-record receipt: ${String(error)}`);
+    }
     // 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) =>
@@ -432,18 +567,25 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // claim "merge-archived" (item ②). Conflicts/failures ride along so the
     // audit row records why the run diverged.
     const outcome = { ...buildOutcome(committed), conflicts, failures };
+    // Frozen conflicts were not adjudicated: mark both sides pending in the
+    // per-id outcome so the audit row shows they were parked, not skipped.
+    if (frozenIds.length) {
+      for (const id of frozenIds) outcome.byId[id] = "conflict-pending";
+    }
     // Decisions validated but not fully committed → reconcile (not ok).
     const partial = conflicts.length > 0 || failures.length > 0;
     // No decision landed (all-keep, or every decision skipped as an idempotent
     // replay) → nothing substantive changed. Distinct from a success: such a
     // run must never be reported as ok, or the audit claims work that never
     // happened and the scheduler refreshes the baseline on a false positive.
-    const noChange = applied === 0 && committed.every((c) => c.action === "keep");
+    // Frozen conflicts are substantive output (parked for review), so a run
+    // that only froze conflicts is not a noop.
+    const noChange = frozenCount === 0 && applied === 0 && committed.every((c) => c.action === "keep");
 
     // Keep the vector index consistent with the post-dream store state.
     if (semantic?.embedder && semantic?.vectorIndex) {
       try {
-        await maintainIndexAfterDream(decisions, service, semantic);
+        await maintainIndexAfterDream(applyList, service, semantic);
       } catch (error) {
         logger?.warn?.(`[dsh-mneme] dream index maintenance failed: ${String(error)}`);
       }
@@ -465,7 +607,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       });
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: summary llm call failed: ${String(error)}`);
-      return finish({ ok: false, error: "llm failed", applied, decisions: auditDecisions, outcome, summary: false });
+      return finish({ ok: false, error: "llm failed", applied, decisions: auditDecisions, outcome, frozen: frozenCount, summary: false });
     }
     let summaryStored = false;
     if (summaryText !== undefined && summaryText.trim()) {
@@ -512,6 +654,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       outcome,
       conflicts,
       failures,
+      frozen: frozenCount,
       summary: summaryStored
     });
   }

package/lib/index.js

@@ -44,6 +44,23 @@ export const apply = (ctx, config) => {
   const mirror = createMirror(memoryDir);
   const service = createService({ store, mirror, config: cfg });
 
+  // Recall-layer receipt: when searchMemories runs with recordRecall=true, the
+  // retrieval scene (query/mode/topK/threshold + candidates) is persisted to
+  // recall_runs for audit/replay — the sibling of the dream_runs judgment trail.
+  // Best-effort: a failed recall write must never break the search.
+  service.setRecallRecorder((recall) => {
+    try {
+      store.saveRecallRun({
+        query: recall.query,
+        mode: recall.mode,
+        topK: recall.topK,
+        threshold: recall.threshold ?? null,
+        candidates: recall.candidates ?? [],
+        created_at: recall.createdAt
+      });
+    } catch { /* non-fatal: recall recording is bookkeeping */ }
+  });
+
   // User-configurable settings (profile, rules) and custom commands share the
   // same SQLite file but live in dedicated tables, isolated from memories.
   const settings = createSettings(store.db);

package/lib/service.js

@@ -16,6 +16,13 @@ export function createService({ store, mirror, config, onWrite }) {
   let vectorIndex = null;
   let reranker = null;
 
+  // Optional recall recorder, installed via setRecallRecorder after creation.
+  // When searchMemories is called with recordRecall=true it receives the
+  // actual merged recall scene (candidates + scores + source + threshold) so
+  // the retrieval layer can be audited/replayed — the sibling of the dream
+  // judgment-layer audit trail (dream_runs).
+  let recallRecorder = 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()
@@ -43,7 +50,7 @@ export function createService({ store, mirror, config, onWrite }) {
       const out = [];
       for (const s of scored) {
         const c = byId.get(s.id);
-        if (c) { out.push({ ...c, score: s.score }); if (out.length >= topK) break; }
+        if (c) { out.push({ ...c, score: s.score, source: "rerank" }); if (out.length >= topK) break; }
       }
       return out.length ? out : candidates.slice(0, topK);
     } catch {
@@ -78,15 +85,16 @@ export function createService({ store, mirror, config, onWrite }) {
     return base * (0.5 + (row.importance ?? 3) / 10);
   }
 
-  async function searchMemories(query, { mode = "auto", topK = 20, threshold, useRerank = true } = {}) {
+  async function searchMemories(query, { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = {}) {
     const q = String(query ?? "").trim();
     if (!q) return [];
     const lim = topK > 0 ? topK : 20;
 
     // Keyword results, decorated with a score so they can be weight-blended
-    // with vector results and reported uniformly.
+    // with vector results and reported uniformly. source tracks where each
+    // candidate came from for the recall layer receipt.
     const rawKeyword = store.search(q, { limit: lim });
-    const keyword = rawKeyword.map((m) => ({ ...m, score: scoreKeyword(m, q) }));
+    const keyword = rawKeyword.map((m) => ({ ...m, score: scoreKeyword(m, q), source: "keyword" }));
     const wantVector = mode === "vector" || mode === "hybrid" || (mode === "auto" && !!embedder);
     let vector = [];
     if (wantVector && embedder) {
@@ -100,7 +108,7 @@ export function createService({ store, mirror, config, onWrite }) {
           const hits = vectorIndex
             ? vectorIndex.search(qv, { limit: lim * 2, threshold: threshold ?? 0 })
             : store.searchVector(qv, { limit: lim * 2, threshold: threshold ?? 0 });
-          vector = hits.map((m) => ({ ...m, vector: true }));
+          vector = hits.map((m) => ({ ...m, vector: true, source: "vector" }));
         }
       } catch { /* vector unavailable: keep keyword results */ }
     }
@@ -147,10 +155,34 @@ export function createService({ store, mirror, config, onWrite }) {
     }
 
     merged = merged.slice(0, lim);
-    if (useRerank && reranker && merged.length) {
-      return rerankCandidates(q, merged, lim);
+    const result = useRerank && reranker && merged.length
+      ? await rerankCandidates(q, merged, lim)
+      : merged;
+
+    // Recall layer receipt: with recordRecall on, hand the actual merged
+    // candidate list (id/title/content/score/source) to the injected recorder
+    // before returning, making the retrieval scene replayable — the sibling of
+    // the dream judgment-layer audit trail. Recorder failures must never break
+    // the search itself.
+    if (recordRecall && recallRecorder) {
+      try {
+        recallRecorder({
+          query: q,
+          mode,
+          topK: lim,
+          threshold: threshold ?? null,
+          candidates: result.map((m) => ({
+            id: m.id,
+            title: m.title,
+            content: m.content,
+            score: m.score ?? null,
+            source: m.source ?? "keyword"
+          })),
+          createdAt: new Date().toISOString()
+        });
+      } catch { /* recall receipt is best effort */ }
     }
-    return merged;
+    return result;
   }
 
   /**
@@ -355,6 +387,7 @@ export function createService({ store, mirror, config, onWrite }) {
     setEmbedder(emb) { embedder = emb; },
     setVectorIndex(vi) { vectorIndex = vi; },
     setReranker(rn) { reranker = rn; },
+    setRecallRecorder(fn) { recallRecorder = fn; },
     searchMemories,
     // passthroughs used by tools and api layers; mutations keep the mirror in sync
     search: (q, o) => store.search(q, o),
@@ -441,6 +474,17 @@ export function createService({ store, mirror, config, onWrite }) {
     // dream scheduler that just recorded the run.
     saveDreamRun: (run) => store.saveDreamRun(run),
     getDreamRun: (id) => store.getDreamRun(id),
-    listDreamRuns: (opts) => store.listDreamRuns(opts)
+    listDreamRuns: (opts) => store.listDreamRuns(opts),
+    // Per-record receipt chain (same bookkeeping semantics as saveDreamRun: an
+    // audit write, never a write-hook-triggering memory mutation).
+    saveReceipt: (r) => store.saveReceipt(r),
+    getReceipt: (id) => store.getReceipt(id),
+    listReceipts: (opts) => store.listReceipts(opts),
+    // Conflict freeze bookkeeping (same semantics as the audit passthroughs
+    // above: an audit write, never a write-hook-triggering memory mutation).
+    saveConflictPending: (r) => store.saveConflictPending(r),
+    listConflictPending: (opts) => store.listConflictPending(opts),
+    resolveConflictPending: (id, o) => store.resolveConflictPending(id, o),
+    countConflictPending: () => store.countConflictPending()
   };
 }