@modusensus/dsh-mneme 0.7.28 → 0.7.29

package/lib/service.js

@@ -416,6 +416,171 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     }
   }
 
+  /**
+   * Recall fusion (plan #1). Turns the three ranked signal lists (keyword,
+   * vector, BM25) into a single merged list. Three recipes, selected by
+   * config.recallFusion:
+   *  - blend (default): legacy behavior — weighted sum for vector/hybrid, union
+   *    backfill for auto. Byte-identical to pre-fusion code, so enabling the
+   *    config never regresses anybody.
+   *  - rrf: Reciprocal Rank Fusion — Σ 1/(k + rank + 1) over each list a row
+   *    appears in. Rank-based, so the unit mismatch (raw cosine vs keyword
+   *    score vs normalized IDF) is irrelevant.
+   *  - minmax: min-max normalize each source list's scores to [0,1] then take
+   *    the weighted sum — a scale-aware version of `blend`.
+   * Returns { merged, signals }, where signals is Map<id, {keyword, vector,
+   * bm25}> so searchMemories can decorate rows when signalTransparency is on.
+   */
+  function fuseRecall({ keyword, vector, bm25, lim, mode, wv, wk, wb }) {
+    const recipe = config?.recallFusion ?? "blend";
+
+    // Per-source scores are recorded for every recipe so signalTransparency
+    // works regardless of how the ranking was produced.
+    const signals = new Map();
+    const addSig = (id, field, sc) => {
+      const cur = signals.get(id) ?? {};
+      cur[field] = sc;
+      signals.set(id, cur);
+    };
+    for (const m of keyword) addSig(m.id, "keyword", m.score ?? 0);
+    for (const m of vector) addSig(m.id, "vector", m.score ?? 0);
+    for (const m of bm25) addSig(m.id, "bm25", m.score ?? 0);
+
+    const vectorIds = new Set(vector.map((m) => m.id));
+    const keywordIds = new Set(keyword.map((m) => m.id));
+
+    // Mode contract (aligns rrf/minmax with blend): keyword-only searches must
+    // stay keyword-only regardless of recipe, so enabling an opt-in recipe can
+    // never pull vector/BM25 rows into a mode="keyword" request. This mirrors
+    // the blend branch's `mode === "keyword"` short-circuit (byte-for-byte).
+    if (mode === "keyword") {
+      return { merged: keyword.slice(0, lim), signals };
+    }
+
+    let merged;
+    if (recipe === "rrf") {
+      // Rank-based: only the position of a row inside each surviving source
+      // list matters, so no cross-signal scale calibration is needed.
+      const k = 60; // standard RRF constant (plan #1 documents k=60)
+      const rows = new Map();
+      const addList = (list) => list.forEach((m, idx) => {
+        const s = 1 / (k + idx + 1);
+        const cur = rows.get(m.id);
+        if (cur) cur.score += s;
+        else rows.set(m.id, { ...m, score: s });
+      });
+      addList(keyword);
+      addList(vector);
+      addList(bm25);
+      merged = [...rows.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, lim);
+    } else if (recipe === "minmax") {
+      // Scale-aware weighted sum: each source list is min-max normalized to
+      // [0,1] before blending, so raw cosine and keyword score live on the
+      // same footing.
+      const norm = (list) => {
+        if (!list.length) return new Map();
+        let min = Infinity, max = -Infinity;
+        for (const m of list) { const s = m.score ?? 0; if (s < min) min = s; if (s > max) max = s; }
+        const range = max - min;
+        const out = new Map();
+        for (const m of list) out.set(m.id, range > 0 ? ((m.score ?? 0) - min) / range : 0.5);
+        return out;
+      };
+      const kw = norm(keyword), ve = norm(vector), bm = norm(bm25);
+      const rows = new Map();
+      const seed = (m) => { if (!rows.has(m.id)) rows.set(m.id, { ...m, score: 0 }); };
+      for (const m of keyword) seed(m);
+      for (const m of vector) seed(m);
+      for (const m of bm25) seed(m);
+      for (const [id, row] of rows) {
+        const k = kw.get(id) ?? 0;
+        const v = ve.get(id) ?? 0;
+        const b = bm.get(id) ?? 0;
+        row.score = v * wv + k * wk + b * wb;
+      }
+      merged = [...rows.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, lim);
+    } else {
+      // blend — the pre-existing per-mode behavior, extracted verbatim.
+      if (mode === "keyword") {
+        merged = keyword;
+      } else if (mode === "vector" || mode === "hybrid") {
+        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) {
+          const rec = byId.get(m.id);
+          if (rec) {
+            byId.set(m.id, { ...rec, score: (rec.score ?? 0) * wv + (m.score ?? 0) * wk });
+          } else {
+            byId.set(m.id, m);
+          }
+        }
+        for (const m of bm25) {
+          const rec = byId.get(m.id);
+          if (rec) {
+            if (keywordIds.has(m.id)) continue;
+            byId.set(m.id, { ...rec, score: (rec.score ?? 0) + wb * (m.score ?? 0) });
+          } else {
+            byId.set(m.id, { ...m, score: wb * (m.score ?? 0) });
+          }
+        }
+        const ranked = [...byId.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+        merged = ranked.slice(0, lim);
+        if (merged.length < lim && !merged.length) {
+          merged = keyword.slice(0, lim);
+        }
+      } else {
+        // auto: keyword leads, vector + BM25 fill remaining slots.
+        merged = keyword.slice(0, lim);
+        const seen = new Set(merged.map((m) => m.id));
+        for (const m of vector) {
+          if (merged.length >= lim) break;
+          if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
+        }
+        for (const m of bm25) {
+          if (merged.length >= lim) break;
+          if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
+        }
+      }
+    }
+
+    // Mode contract, auto (aligns rrf/minmax with blend): keyword leads, the
+    // recipe fills the remaining slots. blend.auto already front-loads keyword;
+    // rrf/minmax rank across sources, so re-apply the same "keyword first"
+    // ordering here to preserve the pre-fusion auto contract — the keyword
+    // hit list keeps its power, and only slots it couldn't fill go to the
+    // recipe's ranking.
+    if (recipe !== "blend" && mode === "auto" && keyword.length) {
+      const head = keyword.slice(0, lim);
+      const seen = new Set(head.map((m) => m.id));
+      const tail = merged.filter((m) => !seen.has(m.id)).slice(0, Math.max(0, lim - head.length));
+      merged = head.concat(tail);
+    }
+
+    return { merged, signals };
+  }
+
+  /**
+   * Search memories for a query. Merges up to three recall sources (keyword,
+   * vector, BM25) according to config.recallFusion (blend/rrf/minmax — see
+   * fuseRecall), then optionally decorates rows with per-source signals
+   * (config.signalTransparency), applies semantic dedup (non-keyword modes),
+   * reranking, and epistemic trust re-weighting, and finally hands the merged
+   * list to the recall-layer recorder.
+   *
+   * options:
+   *   mode          — 'auto' (default) | 'keyword' | 'vector' | 'hybrid'
+   *   topK          — max rows (default 20)
+   *   threshold     — explicit vector score floor (overrides adaptive)
+   *   useRerank     — apply the reranker if available (default true)
+   *   recordRecall  — write a recall_runs audit row (default from config)
+   *
+   * Returns an array of memory rows { id, title, content, score, source, ... },
+   * with `signals` added when config.signalTransparency is on. Never throws:
+   * a vector/rerank failure degrades to keyword results.
+   */
   async function searchMemories(query, options = {}) {
     const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = options.recordRecall ?? (config?.recallRecordDefault ?? true) } = options;
     const q = String(query ?? "").trim();
@@ -477,69 +642,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // Loose blend weight: BM25 confirms and backfills, never dominates the
     // semantic signal. Same-memory overlap boosts, unseen ids backfill.
     const wb = 0.3;
-    // Path bookkeeping for the boost rule below: which ids each semantic
-    // recall path surfaced.
-    const vectorIds = new Set(vector.map((m) => m.id));
-    const keywordIds = new Set(keyword.map((m) => m.id));
 
     // 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 + BM25 fill remaining
-      // slots. Weighted blend when sides scored the same memory; otherwise
-      // vector order leads (it is the semantic signal), lexical paths
-      // backfill.
-      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) {
-        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);
-        }
-      }
-      for (const m of bm25) {
-        const rec = byId.get(m.id);
-        if (rec) {
-          // Boost rule: a row the LIKE keyword path already hit carries the
-          // query as a substring, so BM25 tokens are trivially present —
-          // boosting it double-counts lexical evidence. Only vector-recalled
-          // rows (lexical hit is genuinely new information) get the boost.
-          if (keywordIds.has(m.id)) continue;
-          byId.set(m.id, { ...rec, score: (rec.score ?? 0) + wb * (m.score ?? 0) });
-        } else {
-          byId.set(m.id, { ...m, score: wb * (m.score ?? 0) });
-        }
-      }
-      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 + BM25 fill remaining slots (legacy
-      // behavior, extended with the third path)
-      merged = keyword.slice(0, lim);
-      const seen = new Set(merged.map((m) => m.id));
-      for (const m of vector) {
-        if (merged.length >= lim) break;
-        if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
-      }
-      for (const m of bm25) {
-        if (merged.length >= lim) break;
-        if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
-      }
+    const { merged: fusedMerged, signals } = fuseRecall({ keyword, vector, bm25, lim, mode, wv, wk, wb });
+    let merged = fusedMerged;
+    // Signal transparency (#2): decorate each returned row with its per-source
+    // scores and the final fused score. Purely additive — never changes rank.
+    if (config?.signalTransparency === true) {
+      merged = merged.map((m) => ({ ...m, signals: { ...(signals.get(m.id) ?? {}), final: m.score ?? 0 } }));
     }
 
     // Search-time semantic dedup (v0.5.0 2.3): near-duplicate rows are

package/lib/settings.js

@@ -58,6 +58,9 @@ const FEATURE_FLAG_BOOLEANS = [
   "bm25SearchEnabled",
   "conflictFreezeEnabled",
   "trustEpistemicWeighting",
+  // Plan #2: attach per-source {keyword, vector, bm25, final} signals to each
+  // search result for transparency/debugging. Default off, purely decorative.
+  "signalTransparency",
   // Issue #89：宽容校验回归（默认开）+ 跨类型合并显式放宽（默认关）。
   "dreamSkipInvalid",
   "allowCrossTypeMerge",
@@ -86,6 +89,10 @@ const FEATURE_FLAG_STRINGS = [
   // /llm-providers 端点一起提供，留空 = 用巩固模型或当前模型。
   "sleepProvider",
   "sleepModel",
+  // 实体抽取侧专用路由（issue #109）：provider/model 显式指定，
+  // 留空 = 用当前默认模型。
+  "entityExtractionProvider",
+  "entityExtractionModel",
   "localEmbedModel",
   "ollamaModel"
 ];
@@ -94,7 +101,12 @@ const FEATURE_FLAG_STRINGS = [
 const FEATURE_FLAG_URLS = ["ollamaBaseUrl"];
 // 枚举开关（与 config.js 的 z.union(z.const(...)) 对齐）：仅允许列出的值。
 const FEATURE_FLAG_ENUMS = {
-  embedProvider: ["openai", "local", "ollama"]
+  embedProvider: ["openai", "local", "ollama"],
+  // Plan #1: recall fusion recipe. blend = legacy (default); rrf / minmax are
+  // rank/scale-aware alternatives selected by the panel.
+  recallFusion: ["blend", "rrf", "minmax"],
+  // 实体抽取思考强度（issue #109）：与 dreamReasoningEffort 枚举对齐。
+  entityExtractionReasoning: ["low", "medium", "high", "none"]
 };
 const FEATURE_FLAG_STRING_MAX = 200;
 

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, 7 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.7.28",
+  "version": "0.7.29",
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/benchmark-recall.js

@@ -37,7 +37,16 @@ const SEED = [
   { id: "mem_city_thesis", type: "project", title: "湿地论文", content: "毕业论文研究城市湿地公园周边开发案例，ArcGIS 空间分析", importance: 4, tags: ["thesis"] },
   { id: "mem_async_pattern", type: "decision", title: "异步并发模式", content: "async runtime 选用 tokio，任务用 spawn 管理，channel 通信", importance: 3, tags: ["rust"] },
   { id: "mem_python_etl", type: "project", title: "ETL 脚本", content: "夜间 ETL 用 Python 编写，pandas 清洗，SQLite 落地", importance: 3, tags: ["etl"] },
-  { id: "mem_ui_style", type: "preference", title: "界面审美", content: "喜欢编辑风 brutalism 排版，低饱和度配色，衬线标题", importance: 3, tags: ["design"] }
+  { id: "mem_ui_style", type: "preference", title: "界面审美", content: "喜欢编辑风 brutalism 排版，低饱和度配色，衬线标题", importance: 3, tags: ["design"] },
+  // Cross-topic distractors (plan #0): memories that share keywords with a
+  // target but belong to a different subject. They raise the recall bar — the
+  // fused ranking must keep the true positive ahead of the distractor, which
+  // is exactly what a scale-mixed blend (raw cosine + keyword score + IDF)
+  // tends to get wrong.
+  { id: "mem_ops_alert", type: "project", title: "存储告警", content: "Prometheus 存储告警走 zfs 池健康检查与磁盘替换流程", importance: 3, tags: ["ops"] },
+  { id: "mem_rust_dep", type: "project", title: "rust 依赖", content: "Rust 项目的 cargo 依赖管理与 workspace 组织", importance: 3, tags: ["rust"] },
+  { id: "mem_etl_csv", type: "project", title: "ETL CSV", content: "每日 CSV 导入脚本用 golang 而非 python，写 postgres", importance: 2, tags: ["etl"] },
+  { id: "mem_ux_toolbar", type: "preference", title: "工具栏", content: "偏好 IDE 顶栏简洁，避免深色浮层遮挡代码", importance: 2, tags: ["design"] }
 ];
 
 // Standard query set: each case is a query plus the ids that MUST appear in
@@ -53,10 +62,15 @@ export const TEST_CASES = [
   { query: "channel 通信 任务", expected: ["mem_async_pattern"], note: "scattered terms" },
   { query: "内存安全 语言", expected: ["mem_rust_switch"], note: "scattered terms" },
   { query: "配色 审美", expected: ["mem_ui_style"], note: "scattered CJK" },
-  { query: "HBA 固件", expected: ["mem_zfs_bug"], note: "scattered terms" }
+  { query: "HBA 固件", expected: ["mem_zfs_bug"], note: "scattered terms" },
+  // Plan #0 additions: a distractor-dominance case (the target shares the
+  // leading token with a cross-topic memory that must rank below it) and an
+  // exact-token case that leans on the BM25 path.
+  { query: "zfs 磁盘 替换", expected: ["mem_zfs_bug"], note: "shared-token distractor" },
+  { query: "tokio spawn channel", expected: ["mem_async_pattern"], note: "exact async tokens" }
 ];
 
-function seedService(overrides = {}) {
+export function seedService(overrides = {}) {
   const store = createStore(":memory:");
   const config = {
     bm25SearchEnabled: true,
@@ -74,7 +88,11 @@ function seedService(overrides = {}) {
     embedSingle: async (text) => hashVec(text)
   });
   for (const m of SEED) {
-    const row = store.save({ type: m.type, title: m.title, content: m.content, tags: m.tags, importance: m.importance, source: "seed" });
+    // store.save accepts a caller-supplied id (store.js: memory.id ?? randomUUID).
+    // Passing m.id keeps the seeded id stable so TEST_CASES.expected (which
+    // references mem_*) match — without it every row gets a UUID and the
+    // benchmark always reports 0% recall.
+    const row = store.save({ id: m.id, type: m.type, title: m.title, content: m.content, tags: m.tags, importance: m.importance, source: "seed" });
     store.setEmbedding(row.id, hashVec(`${m.title} ${m.content}`));
   }
   return service;
@@ -109,6 +127,52 @@ export async function runBenchmark({ topK = 5, mode = "auto" } = {}) {
   return { topK, mode, runs };
 }
 
+/**
+ * Fusion-recipe A/B (plan #1): runs the same seed + query set with
+ * config.recallFusion forced to each of blend / rrf / minmax, so the scale
+ * mismatch fix can be judged on identical data. `blend` is the legacy recipe
+ * and acts as the control — the pre-fusion behavior.
+ */
+export async function runFusionBenchmark({ topK = 5, mode = "auto" } = {}) {
+  const recipes = ["blend", "rrf", "minmax"];
+  const runs = [];
+  for (const recipe of recipes) {
+    const service = seedService({ recallFusion: recipe });
+    const rows = [];
+    let hits = 0;
+    let mrrSum = 0;
+    for (const tc of TEST_CASES) {
+      const results = await service.searchMemories(tc.query, { mode, topK, useRerank: false });
+      const ids = results.map((r) => r.id);
+      const metrics = service.computeRetrievalMetrics(ids, tc.expected);
+      if (metrics.recall === 1) hits++;
+      mrrSum += metrics.mrr;
+      rows.push({ query: tc.query, note: tc.note, expected: tc.expected, got: ids, ...metrics });
+    }
+    runs.push({
+      config: recipe,
+      recallAtK: +(hits / TEST_CASES.length).toFixed(3),
+      avgMrr: +(mrrSum / TEST_CASES.length).toFixed(3),
+      rows
+    });
+  }
+  return { topK, mode, runs };
+}
+
+function printFusionReport(report) {
+  for (const run of report.runs) {
+    console.log(`\n=== ${run.config} (topK=${report.topK}, mode=${report.mode}) ===`);
+    for (const r of run.rows) {
+      const ok = r.recall === 1 ? "PASS" : "MISS";
+      console.log(`  [${ok}] "${r.query}" (${r.note}) recall=${r.recall} mrr=${r.mrr}`);
+      if (r.recall < 1) console.log(`         expected ⊇ ${r.expected.join(", ")}  got: ${r.got.join(", ") || "—"}`);
+    }
+    console.log(`  → Recall@${report.topK}: ${(run.recallAtK * 100).toFixed(1)}%   avg MRR: ${run.avgMrr}`);
+  }
+  const summary = report.runs.map((r) => `${r.config}=${(r.recallAtK * 100).toFixed(1)}%`).join("  ");
+  console.log(`\n融合配方 A/B (Recall@${report.topK}, ${report.mode}): ${summary}`);
+}
+
 function printReport(report) {
   for (const run of report.runs) {
     console.log(`\n=== ${run.config} (topK=${report.topK}, mode=${report.mode}) ===`);
@@ -127,7 +191,9 @@ function printReport(report) {
 const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/").split("/").pop() ?? "");
 if (invokedDirectly) {
   const asJson = process.argv.includes("--json");
-  const report = await runBenchmark({});
+  const asFusion = process.argv.includes("--fusion");
+  const report = asFusion ? await runFusionBenchmark({}) : await runBenchmark({});
   if (asJson) console.log(JSON.stringify(report, null, 2));
+  else if (asFusion) printFusionReport(report);
   else printReport(report);
 }

package/src/api.js

@@ -161,6 +161,16 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // 反馈入口预填用的插件版本（面板「帮助与反馈」卡片拉取）。读取失败（打包
+  // 环境）返回 "unknown"，链接照常可用，纯展示信息不拦截。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/info",
+    handler(req, res) {
+      sendJson(res, 200, { version: PACKAGE_VERSION });
+    }
+  });
+
   register({
     kind: "exact",
     path: "/api/dsh-mneme/list",

package/src/config.js

@@ -178,6 +178,19 @@ export const Config = z.object({
   searchSemanticDedup: z.boolean().default(false),
   searchSemanticDedupThreshold: z.number().min(0.5).max(1).default(0.95),
 
+  // Recall fusion recipe (plan #1): how the keyword/vector/BM25 ranked lists
+  // are combined into the final ranking. `blend` (default) is the legacy
+  // behavior — weighted sum for vector/hybrid, union backfill for auto —
+  // unchanged. `rrf` (Reciprocal Rank Fusion) and `minmax` (min-max normalized
+  // weighted sum) are rank/scale-aware recipes that fix the unit mismatch the
+  // issue describes (raw cosine vs keyword score vs normalized IDF are added
+  // directly). Off by default so existing behavior holds exactly.
+  recallFusion: z.union([z.const("blend"), z.const("rrf"), z.const("minmax")]).default("blend"),
+  // Attach a `signals` object { keyword, vector, bm25, final } to each search
+  // result for transparency/debugging (plan #2). Default off; when on it only
+  // decorates the returned rows, never changes the ranking.
+  signalTransparency: z.boolean().default(false),
+
   // --- semantic: rerank layer (v0.2) --------------------------------------
   // 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
@@ -207,9 +220,23 @@ export const Config = z.object({
   // The storage layer (entities/entity_attrs/entity_relations tables + CRUD)
   // is always available regardless of this flag.
   entityExtractionEnabled: z.boolean().default(false),
+  // Optional provider override for entity extraction; empty = use the caller's
+  // default provider/model. Combined with entityExtractionModel — provider
+  // without model (or vice versa) falls through to the caller default.
+  entityExtractionProvider: z.string().default(""),
   // Optional model override for entity extraction; empty = use the caller's
   // default provider/model.
   entityExtractionModel: z.string().default(""),
+  // Reasoning effort for entity extraction (issue #109), mirrors
+  // dreamReasoningEffort: 'none' (default) omits the field / provider default;
+  // low/medium/high passed through. A provider that rejects the effort retries
+  // once without it, so opting in is safe to experiment with.
+  entityExtractionReasoning: z.union([
+    z.const("low"),
+    z.const("medium"),
+    z.const("high"),
+    z.const("none")
+  ]).default("none"),
   // Cap on entities per extraction pass and attributes per entity.
   entityExtractionMaxEntities: z.natural().min(1).max(20).default(10),
   entityExtractionMaxAttrs: z.natural().min(1).max(50).default(20),

package/src/entities/extractor.js

@@ -146,16 +146,23 @@ export async function extractEntities(memory, { store, config, callLLM, logger }
       return { ok: false, error: "Invalid memory: missing content" };
     }
     
-    const model = config.entityExtractionModel || null;
     const systemPrompt = buildSystemPrompt(config);
     const userText = buildUserMessage(memory.content);
-    
+
     const messages = [
       { role: "system", content: [{ type: "text", text: systemPrompt }] },
       { role: "user", content: [{ type: "text", text: userText }] }
     ];
-    
-    const options = model ? { model } : {};
+
+    // Issue #109: optional provider/model override + reasoning effort are
+    // passed through to callLLM's options; the index.js adapter maps them onto
+    // the route (or falls back to the caller's default model). Empty provider/
+    // model both mean "use the caller default".
+    const options = {};
+    if (config.entityExtractionProvider) options.provider = config.entityExtractionProvider;
+    if (config.entityExtractionModel) options.model = config.entityExtractionModel;
+    const reasoning = config.entityExtractionReasoning;
+    if (reasoning && reasoning !== "none") options.reasoningEffort = reasoning;
     const llmResponse = await callLLM(messages, options);
     
     if (!llmResponse) {
@@ -219,7 +226,7 @@ export async function extractEntities(memory, { store, config, callLLM, logger }
           to_entity: toId,
           relation_type: rel.type,
           memory_id: memory.id,
-          metadata: { model: model || "default" }
+          metadata: { model: options.model || "default" }
         });
         savedRelations.push(saved);
       } catch (err) {

package/src/index.js

@@ -35,6 +35,57 @@ export { Config };
 // value, so a `function apply` disposer would never run on unload. An arrow
 // has no prototype, is called normally, and its returned disposer is collected
 // and run by the fiber on unload.
+// Entity-extraction LLM adapter (issue #108/#109): maps the extractor's
+// options (provider/model override + reasoningEffort) onto a real dsh-llm
+// stream route and retries once without the effort when the first attempt is
+// rejected. Extracted from apply() so the effort-fallback branch is
+// unit-testable; the extractor only ever sees a callLLM(messages, options)
+// => Promise<string>. The route always carries a real provider/model (dsh-llm
+// GenerateOptions requires both) — never a bare stream.
+export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
+  return async function streamEntityText(messages, options = {}) {
+    let route = {};
+    if (options.provider) route.provider = options.provider;
+    if (options.model) route.model = options.model;
+    if (!route.provider || !route.model) {
+      try {
+        const sel = agentDefaultModel?.currentSelection?.();
+        if (sel?.provider && sel?.model) {
+          route.provider ??= sel.provider;
+          route.model ??= sel.model;
+        }
+      } catch { /* fall through to whatever route we already have */ }
+    }
+    const effort = options.reasoningEffort;
+    const tryStream = (withEffort) => {
+      let text = "";
+      return (async () => {
+        for await (const chunk of llm.stream({
+          ...route,
+          maxTokens: 4096,
+          ...(withEffort && effort ? { reasoningEffort: effort } : {}),
+          messages
+        })) {
+          if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+          if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) return undefined;
+        }
+        return text;
+      })().catch((err) => {
+        logger?.warn?.(`[dsh-mneme] entity extraction llm stream failed: ${String(err)}`);
+        return undefined;
+      });
+    };
+    let text = await tryStream(true);
+    if (text === undefined && effort) {
+      // Mirror dream's effort fallback: a provider rejecting the reasoning
+      // effort must not sink the whole extraction — retry once without it.
+      logger?.warn?.(`[dsh-mneme] entity extraction: reasoningEffort "${effort}" rejected, retrying without it`);
+      text = await tryStream(false);
+    }
+    return text;
+  };
+}
+
 export const apply = (ctx, config) => {
   const rawCfg = Config(config);
 
@@ -320,36 +371,27 @@ export const apply = (ctx, config) => {
   // expects, reusing the same ctx.llm.stream consumption pattern as dream.js.
   // Explicit opt-in only (entityExtractionEnabled defaults to false); any LLM
   // failure degrades inside the extractor to { ok:false }, never a write error.
-  if (cfg.entityExtractionEnabled && ctx.llm) {
-    const streamEntityText = async (messages, options = {}) => {
-      let route = null;
-      if (options.model) {
-        route = { model: options.model };
-      } else {
-        try {
-          const sel = ctx.agentDefaultModel?.currentSelection?.();
-          if (sel?.provider && sel?.model) route = sel;
-        } catch { /* fall through to no route */ }
-      }
-      let text = "";
-      for await (const chunk of ctx.llm.stream({
-        ...(route ?? {}),
-        purpose: "entity-extract",
-        maxTokens: 4096,
-        messages
-      })) {
-        if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
-        if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) return undefined;
-      }
-      return text;
-    };
-    service.setEntityExtractor((memory) =>
-      extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
-        .catch((err) => {
-          ctx.logger?.warn?.(`[dsh-mneme] entity extraction failed: ${String(err)}`);
-          return { ok: false, error: String(err) };
-        })
-    );
+  if (cfg.entityExtractionEnabled) {
+    if (!ctx.llm) {
+      // Issue #108: an enabled-but-unwired extractor failed silently before —
+      // zero entities, zero llm_audit_logs, no log line anywhere. Make the
+      // missing dependency visible so a user can tell "extractor not installed"
+      // from "extraction failed".
+      ctx.logger?.warn?.("[dsh-mneme] entityExtractionEnabled=true but ctx.llm unavailable — entity extractor NOT installed");
+    } else {
+      const streamEntityText = createEntityStreamAdapter({
+        llm: ctx.llm,
+        agentDefaultModel: ctx.agentDefaultModel,
+        logger: ctx.logger
+      });
+      service.setEntityExtractor((memory) =>
+        extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
+          .catch((err) => {
+            ctx.logger?.warn?.(`[dsh-mneme] entity extraction failed: ${String(err)}`);
+            return { ok: false, error: String(err) };
+          })
+      );
+    }
   }
 
   const disposers = [];