@modusensus/dsh-mneme 0.4.7 → 0.5.0

package/lib/search/bm25.js

@@ -0,0 +1,96 @@
+// BM25 sparse retrieval (v0.5.0 召回率优化 1.1): the third recall path beside
+// vector search and the LIKE keyword scan. The LIKE path only matches full
+// substrings, so a multi-term query ("rust 异步 tokio") misses rows whose
+// terms are scattered. BM25 scores per-token overlap with IDF weighting,
+// which is exactly the gap: identifiers, code fragments and mixed CJK/ASCII
+// queries recall rows the substring scan cannot see.
+
+// Tokenizer: ASCII words keep their shape (identifiers like "dsh-mneme" or
+// "ZFS_4421" survive as whole tokens); CJK runs become sliding bigrams
+// (unigram only for single characters), the standard workaround for BM25's
+// whitespace tokenization on Chinese.
+export function tokenize(text) {
+  const raw = String(text ?? "").toLowerCase();
+  const tokens = [];
+  const ascii = raw.match(/[a-z0-9_]+/g) ?? [];
+  tokens.push(...ascii);
+  const cjkRuns = raw.match(/[\u4e00-\u9fff]+/g) ?? [];
+  for (const run of cjkRuns) {
+    if (run.length === 1) { tokens.push(run); continue; }
+    for (let i = 0; i < run.length - 1; i++) tokens.push(run.slice(i, i + 2));
+  }
+  return tokens;
+}
+
+const K1 = 1.5; // term-frequency saturation
+const B = 0.75;  // length normalization
+
+/**
+ * Build a BM25 index over documents: [{id, title, content}].
+ * Returns { score, search }:
+ *   score(query, doc) — per-spec ad-hoc scoring (re-tokenizes the doc)
+ *   search(query, {limit}) — precomputed-tf ranking, scores normalized to
+ *     [0,1] by the max so BM25 hits can weight-blend with vector/keyword
+ *     scores on one scale. Rows the query does not touch at all are dropped.
+ */
+export function createBM25Index(documents) {
+  const docs = Array.isArray(documents) ? documents.filter(Boolean) : [];
+  const N = docs.length;
+  const df = new Map();
+  const prepared = docs.map((doc) => {
+    const tokens = tokenize(`${doc.title ?? ""} ${doc.content ?? ""}`);
+    const tf = new Map();
+    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+    for (const t of tf.keys()) df.set(t, (df.get(t) ?? 0) + 1);
+    return { doc, tf, len: tokens.length };
+  });
+  const avgLen = N ? prepared.reduce((s, p) => s + p.len, 0) / N : 0 || 1;
+
+  const idf = (t) => {
+    const n = df.get(t) ?? 0;
+    return Math.log((N - n + 0.5) / (n + 0.5) + 1);
+  };
+
+  function scorePrepared(queryTokens, p) {
+    let score = 0;
+    for (const t of queryTokens) {
+      const f = p.tf.get(t);
+      if (!f) continue;
+      const norm = p.len ? K1 * (1 - B + B * (p.len / avgLen)) : K1;
+      score += idf(t) * ((f * (K1 + 1)) / (f + norm));
+    }
+    return score;
+  }
+
+  return {
+    score(query, doc) {
+      const tokens = tokenize(`${doc?.title ?? ""} ${doc?.content ?? ""}`);
+      const tf = new Map();
+      for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+      const len = tokens.length;
+      // Ad-hoc scoring can't see corpus df; fall back to tf-only saturation
+      // (df is approximated as 1 so idf ≈ log(N - 0.5 + 1) is constant).
+      let score = 0;
+      for (const t of tokenize(query)) {
+        const f = tf.get(t);
+        if (!f) continue;
+        const norm = len ? K1 * (1 - B + B * (len / avgLen)) : K1;
+        score += idf(t) * ((f * (K1 + 1)) / (f + norm));
+      }
+      return score;
+    },
+    search(query, { limit = 20 } = {}) {
+      const qTokens = tokenize(query);
+      if (!qTokens.length || !N) return [];
+      const scored = [];
+      for (const p of prepared) {
+        const s = scorePrepared(qTokens, p);
+        if (s > 0) scored.push({ row: p.doc, raw: s });
+      }
+      scored.sort((a, b) => b.raw - a.raw);
+      const top = scored.slice(0, limit);
+      const max = top[0]?.raw || 1;
+      return top.map(({ row, raw }) => ({ ...row, score: max ? raw / max : 0 }));
+    }
+  };
+}

package/lib/service.js

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import { TYPE_FILE } from "./mirror.js";
 import { evaluateMemoryQuality } from "./quality-filter.js";
+import { createBM25Index } from "./search/bm25.js";
+import { adaptiveThreshold } from "./search/adaptive.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
@@ -307,6 +309,66 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   // Weighted blend factor for hybrid search; exposed so callers can tune it.
   const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
 
+  // Cosine over two plain arrays (shared by the search-time semantic dedup).
+  function cosineVec(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      na += a[i] * a[i];
+      nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0) return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+  }
+
+  /**
+   * BM25 third recall path (v0.5.0 1.1). Scores the query tokens against the
+   * live non-archived rows and returns the top `limit` hits with scores
+   * normalized to [0,1]. Failures degrade to [] — BM25 is a recall booster,
+   * never a correctness gate.
+   */
+  function bm25Recall(q, limit) {
+    if (config?.bm25SearchEnabled === false) return [];
+    try {
+      const docs = store.list({ limit: 500, includeForgotten: false }).filter((m) => !m.archived);
+      if (!docs.length) return [];
+      return createBM25Index(docs).search(q, { limit });
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Search-time semantic dedup (v0.5.0 2.3): greedy pass dropping candidates
+   * whose embedding similarity to an already-kept row exceeds the threshold.
+   * Rows without a stored embedding are always kept (no signal = no drop).
+   */
+  function semanticDeduplicate(candidates) {
+    // Opt-in aggressive mode (default off): collapsing near-duplicates can
+    // drop legitimately distinct rows on small embedding models, so it ships
+    // behind searchSemanticDedup=true.
+    if (config?.searchSemanticDedup !== true || candidates.length < 2) return candidates;
+    const threshold = config?.searchSemanticDedupThreshold ?? 0.95;
+    try {
+      const vecs = store.getEmbeddings(candidates.map((c) => c.id));
+      if (vecs.size < 2) return candidates;
+      const kept = [];
+      for (const c of candidates) {
+        const v = vecs.get(c.id);
+        if (!v) { kept.push(c); continue; }
+        const dup = kept.some((k) => {
+          const kv = vecs.get(k.id);
+          return kv && cosineVec(v, kv) > threshold;
+        });
+        if (!dup) kept.push(c);
+      }
+      return kept;
+    } catch {
+      return candidates;
+    }
+  }
+
   /**
    * 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
@@ -371,14 +433,39 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           : embedder.embed.bind(embedder);
         const qv = await embedSingle(q);
         if (qv?.length) {
-          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, source: "vector" }));
+          // Adaptive threshold (v0.5.0 1.2): the fetch runs at the loosest
+          // branch floor so the head-gap rule can still re-admit the tail;
+          // the final cutoff is computed against the fetched score
+          // distribution. Explicit `threshold` wins; disabled → legacy 0.
+          const adaptive = config?.adaptiveThresholdEnabled !== false;
+          const fetchThreshold = adaptive && threshold === undefined
+            ? Math.min(0.5, adaptiveThreshold(q))
+            : (threshold ?? 0);
+          const search = vectorIndex
+            ? vectorIndex.search(qv, { limit: lim * 2, threshold: fetchThreshold })
+            : store.searchVector(qv, { limit: lim * 2, threshold: fetchThreshold });
+          const finalThreshold = adaptive && threshold === undefined
+            ? adaptiveThreshold(q, search)
+            : (threshold ?? 0);
+          vector = search
+            .filter((m) => (m.score ?? 1) >= finalThreshold)
+            .map((m) => ({ ...m, vector: true, source: "vector" }));
         }
       } catch { /* vector unavailable: keep keyword results */ }
     }
 
+    // BM25 third path (v0.5.0 1.1): IDF-weighted token overlap recalls rows
+    // whose query terms are scattered — the gap LIKE substring matching
+    // cannot close. Scores are already normalized to [0,1].
+    const bm25 = bm25Recall(q, lim).map((m) => ({ ...m, source: "bm25" }));
+    // 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;
@@ -387,9 +474,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     if (mode === "keyword") {
       merged = keyword;
     } else if (mode === "vector" || mode === "hybrid") {
-      // 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.
+      // 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);
@@ -404,6 +492,19 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           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) {
@@ -411,15 +512,26 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         merged = keyword.slice(0, lim);
       }
     } else {
-      // auto: keyword leads, vector fills remaining slots (legacy behavior)
+      // 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); }
+      }
     }
 
+    // Search-time semantic dedup (v0.5.0 2.3): near-duplicate rows are
+    // dropped before the reranker sees them, so topK slots carry distinct
+    // information instead of the same memory twice. Keyword mode is exempt —
+    // it is the documented text-only path and must not be altered by
+    // embedding state.
+    merged = mode === "keyword" ? merged : semanticDeduplicate(merged);
     merged = merged.slice(0, lim);
     let result = useRerank && reranker && merged.length
       ? await rerankCandidates(q, merged, lim)
@@ -806,6 +918,20 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         candidates = merged;
       }
     }
+    // Topic-ranked selection (v0.5.0 2.2): when the current query's vector is
+    // available the whole candidate list is re-ordered by similarity to that
+    // vector, so the injected slots go to memories on the current topic
+    // rather than to the rule-based order. Rows the index did not return
+    // keep their relative order after the scored ones.
+    if (config?.selectiveInjectEnabled !== false && Array.isArray(queryVector) && queryVector.length && vectorIndex) {
+      try {
+        const hits = vectorIndex.search(queryVector, { limit: 200, threshold: 0 });
+        const sim = new Map(hits.map((m) => [m.id, m.score ?? 0]));
+        if (sim.size) {
+          candidates = [...candidates].sort((a, b) => (sim.get(b.id) ?? -1) - (sim.get(a.id) ?? -1));
+        }
+      } catch { /* topic re-rank unavailable: keep rule-based order */ }
+    }
     const selected = candidates.slice(0, maxItems);
     touchRecalled(selected);
     return selected;
@@ -1352,6 +1478,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     findEntityByName: (n) => store.findEntityByName(n),
     findEntityById: (id) => store.findEntityById(id),
     getAttrsByMemory: (id) => store.getAttrsByMemory(id),
+    getCurrentAttrs: (id) => store.getCurrentAttrs(id),
     migrateAttrsToMemory: (fromId, toId, now) => store.migrateAttrsToMemory(fromId, toId, now)
   };
 }

package/lib/store.js

@@ -911,6 +911,29 @@ export function createStore(path) {
     db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(json, id);
   }
 
+  /** Batch fetch stored embeddings by id (v0.5.0 search-time semantic dedup).
+   *  Returns a Map(id → number[]); rows without a parseable embedding are
+   *  simply absent from the map. */
+  function getEmbeddings(ids) {
+    const out = new Map();
+    const list = (Array.isArray(ids) ? ids : []).filter(Boolean);
+    for (let i = 0; i < list.length; i += 100) {
+      const chunk = list.slice(i, i + 100);
+      const rows = db.prepare(
+        `SELECT id, embedding FROM memories
+         WHERE embedding IS NOT NULL AND embedding != ''
+           AND id IN (${chunk.map(() => "?").join(",")})`
+      ).all(...chunk);
+      for (const row of rows) {
+        try {
+          const vec = JSON.parse(row.embedding);
+          if (Array.isArray(vec) && vec.length) out.set(row.id, vec);
+        } catch { /* corrupt row: skip */ }
+      }
+    }
+    return out;
+  }
+
   function embeddedCount() {
     return db.prepare(
       "SELECT count(*) AS c FROM memories WHERE embedding IS NOT NULL AND embedding != ''"
@@ -1852,6 +1875,7 @@ export function createStore(path) {
     all,
     search,
     setEmbedding,
+    getEmbeddings,
     embeddedCount,
     needsEmbedding,
     searchVector,

package/package.json

@@ -1,8 +1,16 @@
 {
   "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.4.7",
+  "version": "0.5.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modusensus/dsh-mneme.git"
+  },
+  "homepage": "https://github.com/modusensus/dsh-mneme#readme",
+  "bugs": {
+    "url": "https://github.com/modusensus/dsh-mneme/issues"
+  },
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/scripts/benchmark-recall.js

@@ -0,0 +1,133 @@
+// Recall benchmark (v0.5.0 评测体系): a self-contained harness that seeds an
+// in-memory store with labelled memories, runs a standard query set through
+// the real searchMemories pipeline, and reports Recall@K / MRR per case and
+// in aggregate. Runs in two configurations so the BM25/third-path lift is
+// visible: `legacy` (bm25 + adaptive + dedup off) vs `fused` (defaults on).
+//
+// Usage:
+//   node scripts/benchmark-recall.js            # run both configurations
+//   node scripts/benchmark-recall.js --json     # machine-readable output
+// The harness exports runBenchmark()/TEST_CASES for the test suite; the CLI
+// path below only executes when invoked directly.
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createVectorIndex } from "../src/vector-index.js";
+
+// Deterministic toy embedder: bag-of-words hashed into a fixed-dimension
+// vector, so cosine similarity ≈ lexical overlap. Good enough to exercise
+// the vector path mechanically — semantic quality is not under test here.
+const DIM = 256;
+function hashVec(text) {
+  const v = new Array(DIM).fill(0);
+  const tokens = String(text ?? "").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+  for (const t of tokens) {
+    let h = 0;
+    for (const ch of t) h = (h * 31 + ch.codePointAt(0)) >>> 0;
+    v[h % DIM] += 1;
+  }
+  const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1;
+  return v.map((x) => x / norm);
+}
+
+const SEED = [
+  { id: "mem_user_pref", type: "preference", title: "编辑器偏好", content: "用户偏好 VS Code，深色主题，等宽字体 JetBrains Mono", importance: 4, tags: ["editor"] },
+  { id: "mem_user_project", type: "project", title: "dsh-mneme 插件项目", content: "用户在开发 dsh-mneme 记忆插件，TypeScript 与 cordis 框架", importance: 5, tags: ["plugin"] },
+  { id: "mem_rust_switch", type: "decision", title: "语言迁移决策", content: "项目编译模块从 Go 迁移到 Rust，理由是内存安全", importance: 4, tags: ["rust"] },
+  { id: "mem_zfs_bug", type: "project", title: "ZFS-4421 数据损坏", content: "线上池 ZFS-4421 出现 checksum 错误，根因是 HBA 固件 bug", importance: 5, tags: ["ops"] },
+  { 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"] }
+];
+
+// Standard query set: each case is a query plus the ids that MUST appear in
+// the top-K for the case to count as a hit. Covers the three recall paths —
+// multi-term lexical (BM25's home turf), identifier lookup, and semantic.
+export const TEST_CASES = [
+  { query: "rust 异步", expected: ["mem_async_pattern", "mem_rust_switch"], note: "scattered terms — BM25 territory" },
+  { query: "ZFS-4421 checksum", expected: ["mem_zfs_bug"], note: "identifier + keyword" },
+  { query: "插件 开发", expected: ["mem_user_project"], note: "multi-term CJK" },
+  { query: "论文 空间分析", expected: ["mem_city_thesis"], note: "scattered CJK terms" },
+  { query: "ETL 脚本", expected: ["mem_python_etl"], note: "mixed" },
+  { query: "深色主题", expected: ["mem_user_pref"], note: "substring match" },
+  { 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" }
+];
+
+function seedService(overrides = {}) {
+  const store = createStore(":memory:");
+  const config = {
+    bm25SearchEnabled: true,
+    adaptiveThresholdEnabled: true,
+    searchSemanticDedup: true,
+    searchSemanticDedupThreshold: 0.95,
+    selectiveInjectEnabled: true,
+    entitySearchEnabled: false,
+    ...overrides
+  };
+  const service = createService({ store, mirror: null, config, logger: null });
+  const vectorIndex = createVectorIndex({ store, logger: null });
+  service.setVectorIndex(vectorIndex);
+  service.setEmbedder({
+    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.setEmbedding(row.id, hashVec(`${m.title} ${m.content}`));
+  }
+  return service;
+}
+
+export async function runBenchmark({ topK = 5, mode = "auto" } = {}) {
+  const configs = [
+    { name: "legacy", overrides: { bm25SearchEnabled: false, adaptiveThresholdEnabled: false, searchSemanticDedup: false } },
+    { name: "fused", overrides: {} }
+  ];
+  const runs = [];
+  for (const cfg of configs) {
+    const service = seedService(cfg.overrides);
+    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: cfg.name,
+      recallAtK: +(hits / TEST_CASES.length).toFixed(3),
+      avgMrr: +(mrrSum / TEST_CASES.length).toFixed(3),
+      rows
+    });
+  }
+  return { topK, mode, runs };
+}
+
+function printReport(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 [legacy, fused] = report.runs;
+  const lift = ((fused.recallAtK - legacy.recallAtK) * 100).toFixed(1);
+  console.log(`\n三路融合 vs 旧两路: Recall@${report.topK} ${legacy.recallAtK * 100}% → ${fused.recallAtK * 100}% (${lift >= 0 ? "+" : ""}${lift}pp)`);
+}
+
+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({});
+  if (asJson) console.log(JSON.stringify(report, null, 2));
+  else printReport(report);
+}

package/src/api.js

@@ -103,7 +103,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
       try {
         const url = new URL(req.url, "http://localhost");
         const q = url.searchParams.get("q") ?? "";
-        const limit = Number(url.searchParams.get("limit") ?? 20);
+        const limit = Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 20);
         // 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
@@ -306,6 +306,122 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- ego graph: 1-2 hop neighborhood of one entity (graph panel P1) ---
+  // Read-only like list/search/semantic, so it stays open when apiToken is set.
+  // BFS from the root entity over entity_relations (both directions; the
+  // idx_relations_from/to indexes keep a 2-hop walk in the tens of ms even
+  // for a few thousand nodes). `distance` on each node is the hop count from
+  // the root so the UI can shade the frontier. The API is graph-traversal
+  // only — nodes carry no attr payload; hover summaries come from
+  // /semantic/graph/entity-attrs.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/semantic/graph/ego",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const name = (url.searchParams.get("entity") ?? "").trim();
+        if (!name) {
+          sendJson(res, 400, { error: "missing-entity" });
+          return;
+        }
+        const root = service.findEntityByName?.(name);
+        if (!root) {
+          sendJson(res, 404, { error: "entity-not-found" });
+          return;
+        }
+        const depth = Math.max(1, Math.min(2, Number(url.searchParams.get("depth") ?? 1) || 1));
+        const limit = Math.max(1, Math.min(100, Number(url.searchParams.get("limit") ?? 40) || 40));
+
+        const nodes = new Map([[root.id, { ...root, distance: 0 }]]);
+        let frontier = [root.id];
+        for (let d = 1; d <= depth && nodes.size < limit; d++) {
+          const next = [];
+          for (const id of frontier) {
+            for (const rel of service.getRelations?.(id) ?? []) {
+              const other = rel.from_entity === id ? rel.to_entity : rel.from_entity;
+              if (nodes.has(other) || nodes.size >= limit) continue;
+              const entity = service.findEntityById?.(other);
+              if (!entity) continue;
+              nodes.set(other, { ...entity, distance: d });
+              next.push(other);
+            }
+          }
+          frontier = next;
+        }
+
+        // Collect every relation whose endpoints both survived the limit cut;
+        // each edge is visited twice (once per endpoint) so dedupe by id.
+        const edgeMap = new Map();
+        for (const id of nodes.keys()) {
+          for (const rel of service.getRelations?.(id) ?? []) {
+            if (nodes.has(rel.from_entity) && nodes.has(rel.to_entity)) {
+              edgeMap.set(rel.id, rel);
+            }
+          }
+        }
+
+        sendJson(res, 200, {
+          root: { id: root.id, name: root.name, type: root.type ?? null, mention_count: root.mention_count ?? 1 },
+          nodes: [...nodes.values()].map((n) => ({
+            id: n.id,
+            name: n.name,
+            type: n.type ?? null,
+            mention_count: n.mention_count ?? 1,
+            distance: n.distance
+          })),
+          edges: [...edgeMap.values()].map((e) => ({
+            id: e.id,
+            from: e.from_entity,
+            to: e.to_entity,
+            relation_type: e.relation_type,
+            memory_id: e.memory_id ?? null,
+            created_at: e.created_at
+          }))
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- entity attrs: current valid attrs for one entity (graph hover panel) ---
+  // Read-only; mirrors getCurrentAttrs (valid_until IS NULL). Also used as the
+  // graph panel's fallback list when the ego graph is too sparse to draw.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/semantic/graph/entity-attrs",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const name = (url.searchParams.get("entity") ?? "").trim();
+        if (!name) {
+          sendJson(res, 400, { error: "missing-entity" });
+          return;
+        }
+        const entity = service.findEntityByName?.(name);
+        if (!entity) {
+          sendJson(res, 404, { error: "entity-not-found" });
+          return;
+        }
+        const attrs = service.getCurrentAttrs?.(entity.id) ?? [];
+        sendJson(res, 200, {
+          entity: { id: entity.id, name: entity.name, type: entity.type ?? null, mention_count: entity.mention_count ?? 1 },
+          attrs: Array.isArray(attrs)
+            ? attrs.map((a) => ({
+                key: a.attr_key,
+                value: a.attr_value,
+                confidence: a.confidence ?? null,
+                valid_from: a.valid_from ?? null
+              }))
+            : []
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- health: mirror sync state (F-NEW-03 / v0.3.6) ---
   // Auth-gated; only returns a sanitized error code (never raw last_error which
   // may leak paths/token-like strings/internal hosts). On state read failure it

package/src/config.js

@@ -17,7 +17,7 @@ export const Config = z.object({
   dreamDelayMs: z.natural().min(0).max(60000).default(2000),
   dreamProvider: z.string(),
   dreamModel: z.string(),
-  dreamMaxTokens: z.natural().min(256).max(131072).default(4096),
+  dreamMaxTokens: z.natural().min(256).max(131072).default(8192),
   // Pass-through reasoning effort for dream's LLM calls. 'none' (default)
   // omits the field so the provider's own default applies; low/medium/high
   // are forwarded verbatim. Useful to cap reasoning spend on thinking-type
@@ -92,6 +92,35 @@ export const Config = z.object({
   // rule-based pick to fill/dedupe. Empty query / no vector → legacy behavior.
   hybridInject: z.boolean().default(true),
 
+  // --- recall optimization (v0.5.0) ----------------------------------------
+  // BM25 third recall path beside vector + LIKE keyword (1.1): per-token IDF
+  // scoring recalls rows whose query terms are scattered — identifiers, code
+  // fragments, mixed CJK/ASCII — where substring LIKE cannot match.
+  bm25SearchEnabled: z.boolean().default(true),
+  // Query-aware vector cutoff (1.2) replacing the fixed 0.65: entity:/attr:
+  // prefixes loosen to 0.5, short queries tighten to 0.7, long queries loosen
+  // to 0.6, and a decisive top-1/top-5 score gap loosens to 0.5 so the tail
+  // still reaches the reranker. Off = legacy fixed threshold behavior.
+  adaptiveThresholdEnabled: z.boolean().default(true),
+  // Session-scoped hot memory (1.3): the latest N dialogue rounds rendered
+  // ahead of the long-term recall block — short-term context that never
+  // enters the memory store.
+  hotMemoryEnabled: z.boolean().default(true),
+  hotMemoryRounds: z.natural().min(1).max(50).default(5),
+  hotMemoryMaxTokens: z.natural().min(200).max(32000).default(2000),
+  // Topic-ranked injection (2.2): when a query vector is available the whole
+  // injection candidate list is re-ordered by similarity to the current
+  // query instead of keeping the rule-based order.
+  selectiveInjectEnabled: z.boolean().default(true),
+  // Search-time semantic dedup (2.3): greedy pass over the merged candidate
+  // list dropping rows whose embedding cosine-similarity to an already-kept
+  // row exceeds the threshold — duplicates are filtered at recall time
+  // instead of waiting for a dream consolidation. Opt-in aggressive mode:
+  // small embedding models can collapse legitimately distinct rows, so the
+  // default keeps every recalled row.
+  searchSemanticDedup: z.boolean().default(false),
+  searchSemanticDedupThreshold: z.number().min(0.5).max(1).default(0.95),
+
   // --- 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