@modusensus/dsh-mneme 0.2.0 → 0.2.2

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-198%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-212%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -38,13 +38,15 @@
 ### autoDream 自动记忆整理 🧠
 
 - **触发**：记忆数 > 10 或总字符 > 5000 时，异步自动触发（不阻塞写入）
-- **决策清单式整理**：LLM 输出 `keep` / `merge` / `archive` / `conflict` 决策清单，服务端校验后逐条应用
+- **决策清单式整理**：LLM 输出 `keep` / `merge` / `archive` / `conflict` / `update` 决策清单，服务端校验后逐条应用
   - `merge`：合并主题相近的条目，保留信息最完整者
   - `archive`：归档过时/冗余条目（可恢复，不物理删除）
   - `conflict`：裁决矛盾信息，胜者保留、败者归档并追加溯源注释
+  - `update`（v0.2.1）：直接修正单条记忆的过时/错误内容（单 id / 必须实际变化 / 非 summary / 24h 保护 / 每次 ≤2）
+- **失败追踪（v0.2.1）**：用户纠正记忆时写入 `failure_memories` 表（旧值/新值），为后续自进化积累数据
 - **摘要生成**：整理后生成"记忆库总览"（单一实例），作为下次会话的优先注入
 - **Fail-safe**：非法 LLM 输出（未知 id / 非法 action / 跨类型合并 / 越界 importance）拒绝整单，绝不破坏记忆库
-- **裁决审计**：每次运行写入 `dream_runs` 审计表（输入快照 sha256 digest + 完整输入快照 + 决策清单 + 逐 id 去向 + receipt），可离线回放；merge / conflict 幂等应用，重放/并发重复执行无累积副作用
+- **裁决审计**：每次运行写入 `dream_runs` 审计表（输入快照 sha256 digest + 完整输入快照 + 决策清单 + 逐 id 去向 + receipt），可离线回放；merge / conflict / update 幂等应用，重放/并发重复执行无累积副作用；update 记录 `_before` 快照
 
 ### Web 记忆面板
 
@@ -204,7 +206,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 198 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 212 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -213,7 +215,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 198 个测试
+npm test           # 运行 212 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/lib/api.js

@@ -26,6 +26,13 @@ function parseBody(text) {
 export function createApi(ctx, service, settings, commands, embedder, semantic = null) {
   const disposers = [];
 
+  // Ensure the service has an embedder when the API layer was handed one
+  // (tests wire the embedder through the API instead of index.js). Without
+  // this, /api/dsh-mneme/search would silently degrade to keyword-only.
+  if (embedder && typeof service.setEmbedder === "function") {
+    service.setEmbedder(embedder);
+  }
+
   const register = (route) => {
     disposers.push(ctx.webServer.register(route));
   };
@@ -64,60 +71,34 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         const url = new URL(req.url, "http://localhost");
         const q = url.searchParams.get("q") ?? "";
         const limit = Number(url.searchParams.get("limit") ?? 20);
-        // mode: auto (default) | keyword | vector | hybrid
+        // mode selects the recall strategy (defaults to auto):
+        //   auto    (default) keyword first, vector fills remaining slots
+        //   hybrid  vector first, keyword fills remaining slots; scores of
+        //           memories hit by both sides are weight-blended
+        //   vector  vector only, falls back to keyword when the vector path
+        //           is unavailable (no embedder or a throwing one)
+        //   keyword literal text only; never queries the embedder
+        // rerank=false disables the cross-encoder reorder for this request;
+        // the response `mode` field reports which path actually produced rows.
         const mode = url.searchParams.get("mode") ?? "auto";
+        const rerank = url.searchParams.get("rerank") !== "false";
         const query = q.trim();
         if (!query) {
           sendJson(res, 200, { items: [], mode: "keyword" });
           return;
         }
-        // Keyword results (existing behavior) always computed; used as a
-        // fallback and as the primary ranking when vector is unavailable.
-        const keyword = service.toApiList(service.search(query, { limit }));
-        if (mode === "keyword" || !embedder) {
-          sendJson(res, 200, { items: keyword, mode: "keyword" });
-          return;
-        }
-        const cfg = settings.getVectorConfig();
-        if (mode === "vector" && !cfg?.enabled) {
-          sendJson(res, 200, { items: keyword, mode: "keyword", error: "vector-disabled" });
-          return;
-        }
-        // Try vector search; on any failure fall back to keyword results.
-        return embedder.embed(query).then(async (vector) => {
-          let items = keyword;
-          let used = "keyword";
-          if (vector) {
-            const scored = service.toApiList(service.searchVector(vector, { limit }));
-            if (mode === "hybrid") {
-              // hybrid: vector recalls lead, keyword fills remaining slots
-              const seen = new Set(scored.map((m) => m.id));
-              const merged = [...scored.slice(0, limit)];
-              for (const m of keyword) {
-                if (merged.length >= limit) break;
-                if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
-              }
-              items = merged;
-              used = "vector";
-            } else {
-              // auto/vector: keyword exact hits first (the user's literal
-              // words), then vector results fill the remaining slots, deduped.
-              const seen = new Set(keyword.map((m) => m.id));
-              const merged = [...keyword];
-              for (const m of scored) {
-                if (merged.length >= limit) break;
-                if (!seen.has(m.id)) {
-                  seen.add(m.id);
-                  merged.push(m);
-                }
-              }
-              items = merged;
-              used = "vector";
-            }
-          }
-          sendJson(res, 200, { items, mode: used });
+        // Route through the unified semantic pipeline; any vector/rerank
+        // failure degrades to keyword results inside searchMemories. The
+        // returned promise lets the test double await the async search.
+        return Promise.resolve(
+          service.searchMemories(query, { mode, topK: limit, useRerank: rerank })
+        ).then((rows) => {
+          // mode reflects what actually happened: rows marked `vector` came
+          // through the semantic path, everything else is keyword fallback.
+          const used = rows.some((m) => m.vector === true) ? "vector" : "keyword";
+          sendJson(res, 200, { items: service.toApiList(rows), mode: used });
         }).catch(() => {
-          sendJson(res, 200, { items: keyword, mode: "keyword" });
+          sendJson(res, 200, { items: service.toApiList(service.search(query, { limit })), mode: "keyword" });
         });
       } catch {
         sendJson(res, 500, { error: "internal" });
@@ -202,7 +183,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         }
         const url = new URL(req.url, "http://localhost");
         const limit = Number(url.searchParams.get("limit") ?? 100);
-        embedder.reindexMissing(limit).then((result) => {
+        // Unified re-index entry: works for both the legacy OpenAI embedder and
+        // the new local/ollama backends (which have no reindexMissing method).
+        const viaIndex = semantic?.vectorIndex && semantic?.vectorIndex.rebuildIndex;
+        const task = viaIndex
+          ? semantic.vectorIndex.rebuildIndex(embedder, { limit })
+          : embedder.reindexMissing ? embedder.reindexMissing(limit) : Promise.resolve({ indexed: 0, skipped: 0, error: "vector-unavailable" });
+        task.then((result) => {
           sendJson(res, 200, result);
         }).catch(() => {
           sendJson(res, 200, { indexed: 0, skipped: 0, error: "vector-failed" });

package/lib/config.js

@@ -45,5 +45,11 @@ export const Config = z.object({
   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),
-  rerankScoreThreshold: z.number().min(0).max(1).default(0.1)
+  rerankScoreThreshold: z.number().min(0).max(1).default(0.1),
+
+  // --- reflection: update decision + failure tracking (v0.2.1) ------------
+  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)
 });

package/lib/dream/decisions.js

@@ -1,4 +1,4 @@
-const ACTIONS = new Set(["keep", "merge", "archive", "conflict"]);
+const ACTIONS = new Set(["keep", "merge", "archive", "conflict", "update"]);
 
 /**
  * Validate a dream decision list against a snapshot of eligible memories.
@@ -6,8 +6,10 @@ const ACTIONS = new Set(["keep", "merge", "archive", "conflict"]);
  * @param snapshot - Map<id, memory> of eligible (non-archived, non-summary) entries.
  * @returns {{ok: boolean, errors: string[]}}
  */
-export function validateDecisions(decisions, snapshot) {
+export function validateDecisions(decisions, snapshot, options = {}) {
   const errors = [];
+  const maxUpdatePerRun = options.maxUpdatePerRun ?? 2;
+  const minAgeHours = options.minAgeHours ?? 24;
   if (!Array.isArray(decisions) || decisions.length === 0) {
     return { ok: false, errors: ["decision list must be a non-empty array"] };
   }
@@ -28,6 +30,36 @@ export function validateDecisions(decisions, snapshot) {
       errors.push(`${at}: ${d.action} needs non-empty ids`);
       continue;
     }
+    // update-specific field validation runs BEFORE claiming ids, so a failing
+    // update never pollutes the claimed set (which drives the "every id must
+    // appear in a decision" check below).
+    if (d.action === "update") {
+      // 只能更新单条
+      if (!Array.isArray(d.ids) || d.ids.length !== 1) {
+        errors.push(`${at}: update must target exactly one id`);
+        continue;
+      }
+      // 必须产生实际变化
+      const mem = snapshot.get(d.ids[0]);
+      const hasChange = (d.title !== undefined && d.title !== mem?.title)
+        || (d.content !== undefined && d.content !== mem?.content)
+        || (d.importance !== undefined && d.importance !== mem?.importance);
+      if (!hasChange) {
+        errors.push(`${at}: update must change at least one field`);
+        continue;
+      }
+      // 不能更新 summary
+      if (mem?.type === "summary") {
+        errors.push(`${at}: cannot update summary via update action`);
+        continue;
+      }
+      // 保护期：新建记忆不可立即被 update（可配置）
+      const ageHours = (Date.now() - new Date(mem?.created_at).getTime()) / 3600000;
+      if (ageHours < minAgeHours) {
+        errors.push(`${at}: memory too young (< ${minAgeHours}h)`);
+        continue;
+      }
+    }
     for (const id of ids) {
       const mem = snapshot.get(id);
       if (!mem) {
@@ -58,6 +90,11 @@ export function validateDecisions(decisions, snapshot) {
       }
     }
   }
+  // Cap update churn: too many edits in one cycle signals a runaway model
+  const updateCount = decisions.filter((d) => d.action === "update").length;
+  if (updateCount > maxUpdatePerRun) {
+    errors.push(`too many update decisions: ${updateCount} > ${maxUpdatePerRun}`);
+  }
   // Every snapshot id must appear in at least one decision
   for (const id of snapshot.keys()) {
     if (!claimed.has(id)) errors.push(`memory ${JSON.stringify(id)} missing from decisions`);
@@ -117,6 +154,21 @@ export function applyDecisions(decisions, service, logger = null) {
         });
         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++;
       }
     } catch (error) {
       // Skip individual bad decision; never corrupt the store. The optional

package/lib/dream.js

@@ -10,7 +10,13 @@ const CONSOLIDATION_PROMPT = `你是记忆库整理助手。下面是全部记
 1. 识别主题相近的条目 → 输出 merge（合并为更精炼的摘要，保留信息最完整的 id 作为 keepSource）
 2. 识别重复/过时信息 → 输出 archive
 3. 识别内容矛盾的条目 → 输出 conflict（根据时间新旧、来源完整性、信息具体程度判断 winner/loser）
-4. 无问题的条目 → 输出 keep
+4. 发现单条记忆中的信息已过时、错误或遗漏 → 输出 update（直接修正内容）
+   - update 的 ids 只能包含一个 id
+   - 必须提供修正后的 title 和/或 content
+   - 仅当内容确实需要修正时才使用，不要滥用
+   - 每次整理最多输出 2 个 update
+   - 24 小时内新建的记忆不可 update
+5. 无问题的条目 → 输出 keep
 
 规则：
 - 每条记忆至少出现在一个决策中
@@ -18,6 +24,7 @@ const CONSOLIDATION_PROMPT = `你是记忆库整理助手。下面是全部记
 - 仅合并同类型条目（type 相同）
 - 不要编造 ids；只使用提供的 id
 - 重要性 1-5，合并后取最高
+- update 只能改一条，且要有实际变化
 - 只输出 JSON 数组，不要其他文字`;
 
 function totalChars(memories) {
@@ -83,6 +90,8 @@ export function buildOutcome(decisions) {
     } else if (d.action === "conflict") {
       byId[d.winner] = "conflict-winner";
       byId[d.loser] = "conflict-archived";
+    } else if (d.action === "update") {
+      for (const id of d.ids) byId[id] = "updated";
     }
   }
   return { byId };
@@ -171,6 +180,17 @@ async function maintainIndexAfterDream(decisions, service, semantic) {
       }
     } else if (d.action === "archive" || d.action === "conflict") {
       for (const id of d.ids ?? [d.loser]) vectorIndex.deleteEmbedding(id);
+    } else if (d.action === "update") {
+      const id = d.ids[0];
+      const mem = service.getById(id);
+      if (mem) {
+        vectorIndex.deleteEmbedding(id);
+        try {
+          const text = [mem.title, mem.content].filter(Boolean).join("\n");
+          const v = await embedder.embedSingle(text);
+          if (v?.length) vectorIndex.saveEmbedding(id, v);
+        } catch { /* best-effort */ }
+      }
     }
   }
   for (const [id, text] of rebuild) {
@@ -369,13 +389,32 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       logger?.warn?.("dsh-mneme dream: invalid decisions json");
       return finish({ ok: false, error: "invalid decisions json", summary: false });
     }
-    const { ok, errors } = validateDecisions(decisions, snapshot);
+    const { ok, errors } = validateDecisions(decisions, snapshot, {
+      maxUpdatePerRun: config.reflectionUpdateMaxPerRun,
+      minAgeHours: config.reflectionUpdateMinAgeHours
+    });
     if (!ok) {
       logger?.warn?.(`dsh-mneme dream: invalid decisions: ${errors.join("; ")}`);
       return finish({ ok: false, error: `invalid decisions: ${errors.length} errors`, summary: false });
     }
 
+    // Capture pre-update snapshots so the audit records what each update changed.
+    const updateSnapshots = {};
+    for (const d of decisions) {
+      if (d.action === "update") {
+        const mem = snapshot.get(d.ids[0]);
+        if (mem) updateSnapshots[d.ids[0]] = { title: mem.title, content: mem.content, importance: mem.importance };
+      }
+    }
+
     const applied = applyDecisions(decisions, service, logger);
+    // 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) =>
+      d.action === "update" && updateSnapshots[d.ids[0]]
+        ? { ...d, _before: updateSnapshots[d.ids[0]] }
+        : d
+    );
     const outcome = buildOutcome(decisions);
 
     // Keep the vector index consistent with the post-dream store state.
@@ -403,7 +442,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, outcome, summary: false });
+      return finish({ ok: false, error: "llm failed", applied, decisions: auditDecisions, outcome, summary: false });
     }
     let summaryStored = false;
     if (summaryText !== undefined && summaryText.trim()) {
@@ -421,7 +460,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         } catch { /* best-effort */ }
       }
     }
-    return finish({ ok: true, applied, decisions, outcome, summary: summaryStored });
+    return finish({ ok: true, applied, decisions: auditDecisions, outcome, summary: summaryStored });
   }
 
   return { maybeSchedule, runDream, dispose };

package/lib/reranker.js

@@ -74,6 +74,7 @@ export class LocalReranker {
     this.pipeline = null;
     this._batchScorer = null;
     this._queryVec = null;
+    this._queryKey = null;
   }
 
   /** Load the model; throws when no strategy can be bound. */
@@ -140,10 +141,15 @@ export class LocalReranker {
     } else {
       // Feature extraction: mean-pool the concatenated pair and compare with
       // the query embedding via cosine. Degraded but model-agnostic.
+      // The query vector is cached per query string, so a new query always
+      // recomputes it instead of reusing a stale vector from the previous call.
+      this._queryVec = null;
+      this._queryKey = null;
       this._batchScorer = async (query, passages) => {
-        if (!this._queryVec) {
+        if (this._queryKey !== query) {
           const t = await this.pipeline([query], { pooling: "mean", normalize: true });
           this._queryVec = tensorToRows(t)[0];
+          this._queryKey = query;
         }
         const t = await this.pipeline(passages.map((p) => `${query}\n${p}`), {
           pooling: "mean",
@@ -199,5 +205,6 @@ export class LocalReranker {
     }
     this.pipeline = null;
     this._queryVec = null;
+    this._queryKey = null;
   }
 }

package/lib/service.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
 export function createService({ store, mirror, config, onWrite }) {
@@ -51,12 +53,32 @@ export function createService({ store, mirror, config, onWrite }) {
    * useRerank runs the cross-encoder over the merged list when a reranker is
    * installed; results carry an extra `score` when reranked.
    */
+  // Weighted blend factor for hybrid search; exposed so callers can tune it.
+  const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
+
+  /**
+   * Give a keyword-hit row a relevance score in [0,1]: title hits score
+   * higher than content hits, then scaled by importance (1-5). This lets
+   * keyword results participate in weighted hybrid blends.
+   */
+  function scoreKeyword(row, q) {
+    const ql = q.toLowerCase();
+    const title = (row.title ?? "").toLowerCase();
+    const content = (row.content ?? "").toLowerCase();
+    const titleHit = title.includes(ql);
+    const base = titleHit ? 1 : content.includes(ql) ? 0.6 : 0.3;
+    return base * (0.5 + (row.importance ?? 3) / 10);
+  }
+
   async function searchMemories(query, { mode = "auto", topK = 20, threshold, useRerank = true } = {}) {
     const q = String(query ?? "").trim();
     if (!q) return [];
     const lim = topK > 0 ? topK : 20;
 
-    const keyword = store.search(q, { limit: lim });
+    // Keyword results, decorated with a score so they can be weight-blended
+    // with vector results and reported uniformly.
+    const rawKeyword = store.search(q, { limit: lim });
+    const keyword = rawKeyword.map((m) => ({ ...m, score: scoreKeyword(m, q) }));
     const wantVector = mode === "vector" || mode === "hybrid" || (mode === "auto" && !!embedder);
     let vector = [];
     if (wantVector && embedder) {
@@ -67,23 +89,44 @@ export function createService({ store, mirror, config, onWrite }) {
           : embedder.embed.bind(embedder);
         const qv = await embedSingle(q);
         if (qv?.length) {
-          vector = vectorIndex
+          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 }));
         }
       } catch { /* vector unavailable: keep keyword results */ }
     }
 
+    // Hybrid blending weights from config when provided.
+    const wv = config?.hybridSearchVectorWeight ?? DEFAULT_HYBRID_WEIGHTS.vector;
+    const wk = config?.hybridSearchKeywordWeight ?? DEFAULT_HYBRID_WEIGHTS.keyword;
+
     let merged;
     if (mode === "keyword") {
       merged = keyword;
     } else if (mode === "vector" || mode === "hybrid") {
-      // semantic-first: vector recalls lead, keyword fills remaining slots
-      merged = vector.length ? vector.slice(0, lim) : keyword;
-      const seen = new Set(merged.map((m) => m.id));
+      // semantic-first: vector recalls lead, keyword fills remaining slots.
+      // Weighted blend when both sides scored the same memory; otherwise
+      // vector order leads (it is the semantic signal), keyword backfills.
+      const byId = new Map();
+      for (const m of vector) {
+        const rec = byId.get(m.id);
+        byId.set(m.id, rec ? { ...rec, score: Math.max(rec.score ?? 0, m.score ?? 0) } : m);
+      }
       for (const m of keyword) {
-        if (merged.length >= lim) break;
-        if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
+        const rec = byId.get(m.id);
+        if (rec) {
+          // Same memory from both sides: blend the scores.
+          byId.set(m.id, { ...rec, score: (rec.score ?? 0) * wv + (m.score ?? 0) * wk });
+        } else {
+          byId.set(m.id, m);
+        }
+      }
+      const ranked = [...byId.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+      merged = ranked.slice(0, lim);
+      if (merged.length < lim && !merged.length) {
+        // Vector unavailable entirely: fall back to plain keyword.
+        merged = keyword.slice(0, lim);
       }
     } else {
       // auto: keyword leads, vector fills remaining slots (legacy behavior)
@@ -241,8 +284,28 @@ export function createService({ store, mirror, config, onWrite }) {
       syncMirror();
       notifyWrite();
     },
-    update: (id, p) => {
+    update: (id, p, ctx = {}) => {
+      const old = store.getById(id);
       const updated = store.update(id, p);
+      // Record a user correction when any meaningful field changed and the
+      // reflection failure tracker is enabled. expected = what it became,
+      // actual = what it was before; query (when provided) captures the
+      // user's original intent so later reflection can reason about recall.
+      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,
+          failure_type: "user_correction",
+          memory_id: id
+        });
+      }
       syncMirror();
       notifyWrite();
       scheduleEmbed(updated);

package/lib/store.js

@@ -40,6 +40,21 @@ CREATE TABLE IF NOT EXISTS dream_runs (
   receipt        TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_dream_runs_created ON dream_runs(created_at);
+
+-- failure_memories: records user corrections / reflection failures. Captures
+-- what a memory was ("actual") vs what the user changed it to ("expected")
+-- so later reflection passes can mine recurring correction patterns.
+CREATE TABLE IF NOT EXISTS failure_memories (
+  id           TEXT PRIMARY KEY,
+  query        TEXT,
+  expected     TEXT,
+  actual       TEXT,
+  failure_type TEXT NOT NULL,
+  memory_id    TEXT,
+  created_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_failure_memories_created ON failure_memories(created_at);
+CREATE INDEX IF NOT EXISTS idx_failure_memories_type ON failure_memories(failure_type);
 `;
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
@@ -383,6 +398,50 @@ export function createStore(path) {
     return rows.map(toDreamRun);
   }
 
+  // --- failure memories ----------------------------------------------------
+
+  /**
+   * Persist one failure record (user correction, failed expectation, etc.).
+   * Like the dream audit trail this is bookkeeping: it never triggers write
+   * hooks, so reflection mining of failures cannot loop back into the writer.
+   */
+  function saveFailure({ id, query, expected, actual, failure_type, memory_id }) {
+    const now = nowIso();
+    db.prepare(
+      `INSERT INTO failure_memories (id, query, expected, actual, failure_type, memory_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(id ?? randomUUID(), query ?? null, expected ?? null, actual ?? null, failure_type, memory_id ?? null, now);
+    return { id, query, expected, actual, failure_type, memory_id, created_at: now };
+  }
+
+  function listFailures({ limit = 50, offset = 0, since, memory_id, failure_type } = {}) {
+    const clauses = [];
+    const params = [];
+    if (since) { clauses.push("created_at >= ?"); params.push(since); }
+    if (memory_id) { clauses.push("memory_id = ?"); params.push(memory_id); }
+    if (failure_type) { clauses.push("failure_type = ?"); params.push(failure_type); }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const lim = Number.isInteger(limit) && limit > 0 ? limit : 50;
+    const off = Number.isInteger(offset) && offset > 0 ? offset : 0;
+    return db.prepare(`SELECT * FROM failure_memories ${where} ORDER BY created_at DESC, id LIMIT ? OFFSET ?`).all(...params, lim, off);
+  }
+
+  /** Delete failure rows older than `before` (ISO string). Returns count removed. */
+  function deleteOldFailures(before) {
+    return db.prepare("DELETE FROM failure_memories WHERE created_at < ?").run(before).changes;
+  }
+
+  function getFailureStats({ since } = {}) {
+    const clause = since ? "WHERE created_at >= ?" : "";
+    const params = since ? [since] : [];
+    const rows = db.prepare(
+      `SELECT failure_type, count(*) AS c FROM failure_memories ${clause} GROUP BY failure_type`
+    ).all(...params);
+    const stats = {};
+    for (const row of rows) stats[row.failure_type] = row.c;
+    return stats;
+  }
+
   return {
     db,
     count,
@@ -402,6 +461,10 @@ export function createStore(path) {
     saveDreamRun,
     getDreamRun,
     listDreamRuns,
+    saveFailure,
+    listFailures,
+    getFailureStats,
+    deleteOldFailures,
     close() {
       db.close();
     }

package/lib/tools.js

@@ -133,7 +133,8 @@ export function createTools(ctx, service, config, embedder) {
         content: { type: "string" },
         type: { type: "string", enum: ["preference", "project", "decision", "history"] },
         tags: { type: "array", items: { type: "string" } },
-        importance: { type: "integer", description: "1-5" }
+        importance: { type: "integer", description: "1-5" },
+        reason: { type: "string", description: "Optional context for the correction (what the user actually said/wanted), recorded for reflection" }
       },
       output: {
         schema: {
@@ -160,7 +161,7 @@ export function createTools(ctx, service, config, embedder) {
           type: args.type,
           tags: args.tags,
           importance: args.importance
-        });
+        }, { query: args.reason });
         return { memory: { id: memory.id, title: memory.title, content: memory.content } };
       }
     }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 6 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",

package/src/api.js

@@ -26,6 +26,13 @@ function parseBody(text) {
 export function createApi(ctx, service, settings, commands, embedder, semantic = null) {
   const disposers = [];
 
+  // Ensure the service has an embedder when the API layer was handed one
+  // (tests wire the embedder through the API instead of index.js). Without
+  // this, /api/dsh-mneme/search would silently degrade to keyword-only.
+  if (embedder && typeof service.setEmbedder === "function") {
+    service.setEmbedder(embedder);
+  }
+
   const register = (route) => {
     disposers.push(ctx.webServer.register(route));
   };
@@ -64,60 +71,34 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         const url = new URL(req.url, "http://localhost");
         const q = url.searchParams.get("q") ?? "";
         const limit = Number(url.searchParams.get("limit") ?? 20);
-        // mode: auto (default) | keyword | vector | hybrid
+        // mode selects the recall strategy (defaults to auto):
+        //   auto    (default) keyword first, vector fills remaining slots
+        //   hybrid  vector first, keyword fills remaining slots; scores of
+        //           memories hit by both sides are weight-blended
+        //   vector  vector only, falls back to keyword when the vector path
+        //           is unavailable (no embedder or a throwing one)
+        //   keyword literal text only; never queries the embedder
+        // rerank=false disables the cross-encoder reorder for this request;
+        // the response `mode` field reports which path actually produced rows.
         const mode = url.searchParams.get("mode") ?? "auto";
+        const rerank = url.searchParams.get("rerank") !== "false";
         const query = q.trim();
         if (!query) {
           sendJson(res, 200, { items: [], mode: "keyword" });
           return;
         }
-        // Keyword results (existing behavior) always computed; used as a
-        // fallback and as the primary ranking when vector is unavailable.
-        const keyword = service.toApiList(service.search(query, { limit }));
-        if (mode === "keyword" || !embedder) {
-          sendJson(res, 200, { items: keyword, mode: "keyword" });
-          return;
-        }
-        const cfg = settings.getVectorConfig();
-        if (mode === "vector" && !cfg?.enabled) {
-          sendJson(res, 200, { items: keyword, mode: "keyword", error: "vector-disabled" });
-          return;
-        }
-        // Try vector search; on any failure fall back to keyword results.
-        return embedder.embed(query).then(async (vector) => {
-          let items = keyword;
-          let used = "keyword";
-          if (vector) {
-            const scored = service.toApiList(service.searchVector(vector, { limit }));
-            if (mode === "hybrid") {
-              // hybrid: vector recalls lead, keyword fills remaining slots
-              const seen = new Set(scored.map((m) => m.id));
-              const merged = [...scored.slice(0, limit)];
-              for (const m of keyword) {
-                if (merged.length >= limit) break;
-                if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
-              }
-              items = merged;
-              used = "vector";
-            } else {
-              // auto/vector: keyword exact hits first (the user's literal
-              // words), then vector results fill the remaining slots, deduped.
-              const seen = new Set(keyword.map((m) => m.id));
-              const merged = [...keyword];
-              for (const m of scored) {
-                if (merged.length >= limit) break;
-                if (!seen.has(m.id)) {
-                  seen.add(m.id);
-                  merged.push(m);
-                }
-              }
-              items = merged;
-              used = "vector";
-            }
-          }
-          sendJson(res, 200, { items, mode: used });
+        // Route through the unified semantic pipeline; any vector/rerank
+        // failure degrades to keyword results inside searchMemories. The
+        // returned promise lets the test double await the async search.
+        return Promise.resolve(
+          service.searchMemories(query, { mode, topK: limit, useRerank: rerank })
+        ).then((rows) => {
+          // mode reflects what actually happened: rows marked `vector` came
+          // through the semantic path, everything else is keyword fallback.
+          const used = rows.some((m) => m.vector === true) ? "vector" : "keyword";
+          sendJson(res, 200, { items: service.toApiList(rows), mode: used });
         }).catch(() => {
-          sendJson(res, 200, { items: keyword, mode: "keyword" });
+          sendJson(res, 200, { items: service.toApiList(service.search(query, { limit })), mode: "keyword" });
         });
       } catch {
         sendJson(res, 500, { error: "internal" });
@@ -202,7 +183,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         }
         const url = new URL(req.url, "http://localhost");
         const limit = Number(url.searchParams.get("limit") ?? 100);
-        embedder.reindexMissing(limit).then((result) => {
+        // Unified re-index entry: works for both the legacy OpenAI embedder and
+        // the new local/ollama backends (which have no reindexMissing method).
+        const viaIndex = semantic?.vectorIndex && semantic?.vectorIndex.rebuildIndex;
+        const task = viaIndex
+          ? semantic.vectorIndex.rebuildIndex(embedder, { limit })
+          : embedder.reindexMissing ? embedder.reindexMissing(limit) : Promise.resolve({ indexed: 0, skipped: 0, error: "vector-unavailable" });
+        task.then((result) => {
           sendJson(res, 200, result);
         }).catch(() => {
           sendJson(res, 200, { indexed: 0, skipped: 0, error: "vector-failed" });

package/src/config.js

@@ -45,5 +45,11 @@ export const Config = z.object({
   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),
-  rerankScoreThreshold: z.number().min(0).max(1).default(0.1)
+  rerankScoreThreshold: z.number().min(0).max(1).default(0.1),
+
+  // --- reflection: update decision + failure tracking (v0.2.1) ------------
+  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)
 });

package/src/dream/decisions.js

@@ -1,4 +1,4 @@
-const ACTIONS = new Set(["keep", "merge", "archive", "conflict"]);
+const ACTIONS = new Set(["keep", "merge", "archive", "conflict", "update"]);
 
 /**
  * Validate a dream decision list against a snapshot of eligible memories.
@@ -6,8 +6,10 @@ const ACTIONS = new Set(["keep", "merge", "archive", "conflict"]);
  * @param snapshot - Map<id, memory> of eligible (non-archived, non-summary) entries.
  * @returns {{ok: boolean, errors: string[]}}
  */
-export function validateDecisions(decisions, snapshot) {
+export function validateDecisions(decisions, snapshot, options = {}) {
   const errors = [];
+  const maxUpdatePerRun = options.maxUpdatePerRun ?? 2;
+  const minAgeHours = options.minAgeHours ?? 24;
   if (!Array.isArray(decisions) || decisions.length === 0) {
     return { ok: false, errors: ["decision list must be a non-empty array"] };
   }
@@ -28,6 +30,36 @@ export function validateDecisions(decisions, snapshot) {
       errors.push(`${at}: ${d.action} needs non-empty ids`);
       continue;
     }
+    // update-specific field validation runs BEFORE claiming ids, so a failing
+    // update never pollutes the claimed set (which drives the "every id must
+    // appear in a decision" check below).
+    if (d.action === "update") {
+      // 只能更新单条
+      if (!Array.isArray(d.ids) || d.ids.length !== 1) {
+        errors.push(`${at}: update must target exactly one id`);
+        continue;
+      }
+      // 必须产生实际变化
+      const mem = snapshot.get(d.ids[0]);
+      const hasChange = (d.title !== undefined && d.title !== mem?.title)
+        || (d.content !== undefined && d.content !== mem?.content)
+        || (d.importance !== undefined && d.importance !== mem?.importance);
+      if (!hasChange) {
+        errors.push(`${at}: update must change at least one field`);
+        continue;
+      }
+      // 不能更新 summary
+      if (mem?.type === "summary") {
+        errors.push(`${at}: cannot update summary via update action`);
+        continue;
+      }
+      // 保护期：新建记忆不可立即被 update（可配置）
+      const ageHours = (Date.now() - new Date(mem?.created_at).getTime()) / 3600000;
+      if (ageHours < minAgeHours) {
+        errors.push(`${at}: memory too young (< ${minAgeHours}h)`);
+        continue;
+      }
+    }
     for (const id of ids) {
       const mem = snapshot.get(id);
       if (!mem) {
@@ -58,6 +90,11 @@ export function validateDecisions(decisions, snapshot) {
       }
     }
   }
+  // Cap update churn: too many edits in one cycle signals a runaway model
+  const updateCount = decisions.filter((d) => d.action === "update").length;
+  if (updateCount > maxUpdatePerRun) {
+    errors.push(`too many update decisions: ${updateCount} > ${maxUpdatePerRun}`);
+  }
   // Every snapshot id must appear in at least one decision
   for (const id of snapshot.keys()) {
     if (!claimed.has(id)) errors.push(`memory ${JSON.stringify(id)} missing from decisions`);
@@ -117,6 +154,21 @@ export function applyDecisions(decisions, service, logger = null) {
         });
         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++;
       }
     } catch (error) {
       // Skip individual bad decision; never corrupt the store. The optional

package/src/dream.js

@@ -10,7 +10,13 @@ const CONSOLIDATION_PROMPT = `你是记忆库整理助手。下面是全部记
 1. 识别主题相近的条目 → 输出 merge（合并为更精炼的摘要，保留信息最完整的 id 作为 keepSource）
 2. 识别重复/过时信息 → 输出 archive
 3. 识别内容矛盾的条目 → 输出 conflict（根据时间新旧、来源完整性、信息具体程度判断 winner/loser）
-4. 无问题的条目 → 输出 keep
+4. 发现单条记忆中的信息已过时、错误或遗漏 → 输出 update（直接修正内容）
+   - update 的 ids 只能包含一个 id
+   - 必须提供修正后的 title 和/或 content
+   - 仅当内容确实需要修正时才使用，不要滥用
+   - 每次整理最多输出 2 个 update
+   - 24 小时内新建的记忆不可 update
+5. 无问题的条目 → 输出 keep
 
 规则：
 - 每条记忆至少出现在一个决策中
@@ -18,6 +24,7 @@ const CONSOLIDATION_PROMPT = `你是记忆库整理助手。下面是全部记
 - 仅合并同类型条目（type 相同）
 - 不要编造 ids；只使用提供的 id
 - 重要性 1-5，合并后取最高
+- update 只能改一条，且要有实际变化
 - 只输出 JSON 数组，不要其他文字`;
 
 function totalChars(memories) {
@@ -83,6 +90,8 @@ export function buildOutcome(decisions) {
     } else if (d.action === "conflict") {
       byId[d.winner] = "conflict-winner";
       byId[d.loser] = "conflict-archived";
+    } else if (d.action === "update") {
+      for (const id of d.ids) byId[id] = "updated";
     }
   }
   return { byId };
@@ -171,6 +180,17 @@ async function maintainIndexAfterDream(decisions, service, semantic) {
       }
     } else if (d.action === "archive" || d.action === "conflict") {
       for (const id of d.ids ?? [d.loser]) vectorIndex.deleteEmbedding(id);
+    } else if (d.action === "update") {
+      const id = d.ids[0];
+      const mem = service.getById(id);
+      if (mem) {
+        vectorIndex.deleteEmbedding(id);
+        try {
+          const text = [mem.title, mem.content].filter(Boolean).join("\n");
+          const v = await embedder.embedSingle(text);
+          if (v?.length) vectorIndex.saveEmbedding(id, v);
+        } catch { /* best-effort */ }
+      }
     }
   }
   for (const [id, text] of rebuild) {
@@ -369,13 +389,32 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       logger?.warn?.("dsh-mneme dream: invalid decisions json");
       return finish({ ok: false, error: "invalid decisions json", summary: false });
     }
-    const { ok, errors } = validateDecisions(decisions, snapshot);
+    const { ok, errors } = validateDecisions(decisions, snapshot, {
+      maxUpdatePerRun: config.reflectionUpdateMaxPerRun,
+      minAgeHours: config.reflectionUpdateMinAgeHours
+    });
     if (!ok) {
       logger?.warn?.(`dsh-mneme dream: invalid decisions: ${errors.join("; ")}`);
       return finish({ ok: false, error: `invalid decisions: ${errors.length} errors`, summary: false });
     }
 
+    // Capture pre-update snapshots so the audit records what each update changed.
+    const updateSnapshots = {};
+    for (const d of decisions) {
+      if (d.action === "update") {
+        const mem = snapshot.get(d.ids[0]);
+        if (mem) updateSnapshots[d.ids[0]] = { title: mem.title, content: mem.content, importance: mem.importance };
+      }
+    }
+
     const applied = applyDecisions(decisions, service, logger);
+    // 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) =>
+      d.action === "update" && updateSnapshots[d.ids[0]]
+        ? { ...d, _before: updateSnapshots[d.ids[0]] }
+        : d
+    );
     const outcome = buildOutcome(decisions);
 
     // Keep the vector index consistent with the post-dream store state.
@@ -403,7 +442,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, outcome, summary: false });
+      return finish({ ok: false, error: "llm failed", applied, decisions: auditDecisions, outcome, summary: false });
     }
     let summaryStored = false;
     if (summaryText !== undefined && summaryText.trim()) {
@@ -421,7 +460,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         } catch { /* best-effort */ }
       }
     }
-    return finish({ ok: true, applied, decisions, outcome, summary: summaryStored });
+    return finish({ ok: true, applied, decisions: auditDecisions, outcome, summary: summaryStored });
   }
 
   return { maybeSchedule, runDream, dispose };

package/src/reranker.js

@@ -74,6 +74,7 @@ export class LocalReranker {
     this.pipeline = null;
     this._batchScorer = null;
     this._queryVec = null;
+    this._queryKey = null;
   }
 
   /** Load the model; throws when no strategy can be bound. */
@@ -140,10 +141,15 @@ export class LocalReranker {
     } else {
       // Feature extraction: mean-pool the concatenated pair and compare with
       // the query embedding via cosine. Degraded but model-agnostic.
+      // The query vector is cached per query string, so a new query always
+      // recomputes it instead of reusing a stale vector from the previous call.
+      this._queryVec = null;
+      this._queryKey = null;
       this._batchScorer = async (query, passages) => {
-        if (!this._queryVec) {
+        if (this._queryKey !== query) {
           const t = await this.pipeline([query], { pooling: "mean", normalize: true });
           this._queryVec = tensorToRows(t)[0];
+          this._queryKey = query;
         }
         const t = await this.pipeline(passages.map((p) => `${query}\n${p}`), {
           pooling: "mean",
@@ -199,5 +205,6 @@ export class LocalReranker {
     }
     this.pipeline = null;
     this._queryVec = null;
+    this._queryKey = null;
   }
 }

package/src/service.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
 export function createService({ store, mirror, config, onWrite }) {
@@ -51,12 +53,32 @@ export function createService({ store, mirror, config, onWrite }) {
    * useRerank runs the cross-encoder over the merged list when a reranker is
    * installed; results carry an extra `score` when reranked.
    */
+  // Weighted blend factor for hybrid search; exposed so callers can tune it.
+  const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
+
+  /**
+   * Give a keyword-hit row a relevance score in [0,1]: title hits score
+   * higher than content hits, then scaled by importance (1-5). This lets
+   * keyword results participate in weighted hybrid blends.
+   */
+  function scoreKeyword(row, q) {
+    const ql = q.toLowerCase();
+    const title = (row.title ?? "").toLowerCase();
+    const content = (row.content ?? "").toLowerCase();
+    const titleHit = title.includes(ql);
+    const base = titleHit ? 1 : content.includes(ql) ? 0.6 : 0.3;
+    return base * (0.5 + (row.importance ?? 3) / 10);
+  }
+
   async function searchMemories(query, { mode = "auto", topK = 20, threshold, useRerank = true } = {}) {
     const q = String(query ?? "").trim();
     if (!q) return [];
     const lim = topK > 0 ? topK : 20;
 
-    const keyword = store.search(q, { limit: lim });
+    // Keyword results, decorated with a score so they can be weight-blended
+    // with vector results and reported uniformly.
+    const rawKeyword = store.search(q, { limit: lim });
+    const keyword = rawKeyword.map((m) => ({ ...m, score: scoreKeyword(m, q) }));
     const wantVector = mode === "vector" || mode === "hybrid" || (mode === "auto" && !!embedder);
     let vector = [];
     if (wantVector && embedder) {
@@ -67,23 +89,44 @@ export function createService({ store, mirror, config, onWrite }) {
           : embedder.embed.bind(embedder);
         const qv = await embedSingle(q);
         if (qv?.length) {
-          vector = vectorIndex
+          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 }));
         }
       } catch { /* vector unavailable: keep keyword results */ }
     }
 
+    // Hybrid blending weights from config when provided.
+    const wv = config?.hybridSearchVectorWeight ?? DEFAULT_HYBRID_WEIGHTS.vector;
+    const wk = config?.hybridSearchKeywordWeight ?? DEFAULT_HYBRID_WEIGHTS.keyword;
+
     let merged;
     if (mode === "keyword") {
       merged = keyword;
     } else if (mode === "vector" || mode === "hybrid") {
-      // semantic-first: vector recalls lead, keyword fills remaining slots
-      merged = vector.length ? vector.slice(0, lim) : keyword;
-      const seen = new Set(merged.map((m) => m.id));
+      // semantic-first: vector recalls lead, keyword fills remaining slots.
+      // Weighted blend when both sides scored the same memory; otherwise
+      // vector order leads (it is the semantic signal), keyword backfills.
+      const byId = new Map();
+      for (const m of vector) {
+        const rec = byId.get(m.id);
+        byId.set(m.id, rec ? { ...rec, score: Math.max(rec.score ?? 0, m.score ?? 0) } : m);
+      }
       for (const m of keyword) {
-        if (merged.length >= lim) break;
-        if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
+        const rec = byId.get(m.id);
+        if (rec) {
+          // Same memory from both sides: blend the scores.
+          byId.set(m.id, { ...rec, score: (rec.score ?? 0) * wv + (m.score ?? 0) * wk });
+        } else {
+          byId.set(m.id, m);
+        }
+      }
+      const ranked = [...byId.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+      merged = ranked.slice(0, lim);
+      if (merged.length < lim && !merged.length) {
+        // Vector unavailable entirely: fall back to plain keyword.
+        merged = keyword.slice(0, lim);
       }
     } else {
       // auto: keyword leads, vector fills remaining slots (legacy behavior)
@@ -241,8 +284,28 @@ export function createService({ store, mirror, config, onWrite }) {
       syncMirror();
       notifyWrite();
     },
-    update: (id, p) => {
+    update: (id, p, ctx = {}) => {
+      const old = store.getById(id);
       const updated = store.update(id, p);
+      // Record a user correction when any meaningful field changed and the
+      // reflection failure tracker is enabled. expected = what it became,
+      // actual = what it was before; query (when provided) captures the
+      // user's original intent so later reflection can reason about recall.
+      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,
+          failure_type: "user_correction",
+          memory_id: id
+        });
+      }
       syncMirror();
       notifyWrite();
       scheduleEmbed(updated);

package/src/store.js

@@ -40,6 +40,21 @@ CREATE TABLE IF NOT EXISTS dream_runs (
   receipt        TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_dream_runs_created ON dream_runs(created_at);
+
+-- failure_memories: records user corrections / reflection failures. Captures
+-- what a memory was ("actual") vs what the user changed it to ("expected")
+-- so later reflection passes can mine recurring correction patterns.
+CREATE TABLE IF NOT EXISTS failure_memories (
+  id           TEXT PRIMARY KEY,
+  query        TEXT,
+  expected     TEXT,
+  actual       TEXT,
+  failure_type TEXT NOT NULL,
+  memory_id    TEXT,
+  created_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_failure_memories_created ON failure_memories(created_at);
+CREATE INDEX IF NOT EXISTS idx_failure_memories_type ON failure_memories(failure_type);
 `;
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
@@ -383,6 +398,50 @@ export function createStore(path) {
     return rows.map(toDreamRun);
   }
 
+  // --- failure memories ----------------------------------------------------
+
+  /**
+   * Persist one failure record (user correction, failed expectation, etc.).
+   * Like the dream audit trail this is bookkeeping: it never triggers write
+   * hooks, so reflection mining of failures cannot loop back into the writer.
+   */
+  function saveFailure({ id, query, expected, actual, failure_type, memory_id }) {
+    const now = nowIso();
+    db.prepare(
+      `INSERT INTO failure_memories (id, query, expected, actual, failure_type, memory_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(id ?? randomUUID(), query ?? null, expected ?? null, actual ?? null, failure_type, memory_id ?? null, now);
+    return { id, query, expected, actual, failure_type, memory_id, created_at: now };
+  }
+
+  function listFailures({ limit = 50, offset = 0, since, memory_id, failure_type } = {}) {
+    const clauses = [];
+    const params = [];
+    if (since) { clauses.push("created_at >= ?"); params.push(since); }
+    if (memory_id) { clauses.push("memory_id = ?"); params.push(memory_id); }
+    if (failure_type) { clauses.push("failure_type = ?"); params.push(failure_type); }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const lim = Number.isInteger(limit) && limit > 0 ? limit : 50;
+    const off = Number.isInteger(offset) && offset > 0 ? offset : 0;
+    return db.prepare(`SELECT * FROM failure_memories ${where} ORDER BY created_at DESC, id LIMIT ? OFFSET ?`).all(...params, lim, off);
+  }
+
+  /** Delete failure rows older than `before` (ISO string). Returns count removed. */
+  function deleteOldFailures(before) {
+    return db.prepare("DELETE FROM failure_memories WHERE created_at < ?").run(before).changes;
+  }
+
+  function getFailureStats({ since } = {}) {
+    const clause = since ? "WHERE created_at >= ?" : "";
+    const params = since ? [since] : [];
+    const rows = db.prepare(
+      `SELECT failure_type, count(*) AS c FROM failure_memories ${clause} GROUP BY failure_type`
+    ).all(...params);
+    const stats = {};
+    for (const row of rows) stats[row.failure_type] = row.c;
+    return stats;
+  }
+
   return {
     db,
     count,
@@ -402,6 +461,10 @@ export function createStore(path) {
     saveDreamRun,
     getDreamRun,
     listDreamRuns,
+    saveFailure,
+    listFailures,
+    getFailureStats,
+    deleteOldFailures,
     close() {
       db.close();
     }

package/src/tools.js

@@ -133,7 +133,8 @@ export function createTools(ctx, service, config, embedder) {
         content: { type: "string" },
         type: { type: "string", enum: ["preference", "project", "decision", "history"] },
         tags: { type: "array", items: { type: "string" } },
-        importance: { type: "integer", description: "1-5" }
+        importance: { type: "integer", description: "1-5" },
+        reason: { type: "string", description: "Optional context for the correction (what the user actually said/wanted), recorded for reflection" }
       },
       output: {
         schema: {
@@ -160,7 +161,7 @@ export function createTools(ctx, service, config, embedder) {
           type: args.type,
           tags: args.tags,
           importance: args.importance
-        });
+        }, { query: args.reason });
         return { memory: { id: memory.id, title: memory.title, content: memory.content } };
       }
     }),