@modusensus/dsh-mneme 0.4.7 → 0.5.1

package/lib/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

package/lib/dream.js

@@ -3,6 +3,43 @@ import { clusterMemories, findPotentialConflicts } from "./dream/clustering.js";
 import { createHash, randomUUID } from "node:crypto";
 export { validateDecisions, applyDecisions };
 
+
+// Extract the first JSON array from LLM output, tolerating markdown fences,
+// leading/trailing prose, and common wrapper noise. Returns an array or null.
+function extractJsonArray(text) {
+  if (typeof text !== "string" || text.trim().length === 0) return null;
+
+  // 1. Strip markdown code fences (```json ... ``` or ``` ... ```).
+  let cleaned = text.replace(/```(?:json)?\s*([\s\S]*?)```/gi, "$1");
+  cleaned = cleaned.trim();
+
+  // 2. Find the first '[' and the matching last ']' that yields valid JSON.
+  const start = cleaned.indexOf("[");
+  if (start === -1) return null;
+  for (let end = cleaned.lastIndexOf("]"); end > start; end = cleaned.lastIndexOf("]", end - 1)) {
+    const candidate = cleaned.slice(start, end + 1);
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      // Light repair: remove trailing commas before ] or }.
+      try {
+        const repaired = candidate.replace(/,(\s*[}\]])/g, "$1");
+        return JSON.parse(repaired);
+      } catch {
+        // keep searching backwards
+      }
+    }
+  }
+
+  // 3. Fallback: a broader regex extraction.
+  try {
+    const match = cleaned.match(/\[[\s\S]*\]/);
+    if (match) return JSON.parse(match[0]);
+  } catch {
+    // fall through
+  }
+  return null;
+}
 const SUMMARY_PROMPT = `你是记忆库摘要助手。根据整理后的记忆，生成一段 150-200 字的记忆库总览，覆盖：用户偏好、活跃项目、关键决策。之后作为会话上下文注入。只输出摘要文本，不要其他内容。`;
 
 const CONSOLIDATION_PROMPT = `你是记忆库整理助手。下面是全部记忆条目（id、类型、标题、内容、重要性、更新时间）。
@@ -579,18 +616,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       return finish({ ok: false, error: "llm failed", summary: false });
     }
 
-    let decisions;
-    try {
-      const start = decisionText.indexOf("[");
-      const end = decisionText.lastIndexOf("]");
-      if (start === -1 || end <= start) {
-        logger?.warn?.("dsh-mneme dream: no json array in llm output");
-        return finish({ ok: false, error: "no json array in llm output", summary: false });
-      }
-      decisions = JSON.parse(decisionText.slice(start, end + 1));
-    } catch {
-      logger?.warn?.("dsh-mneme dream: invalid decisions json");
-      return finish({ ok: false, error: "invalid decisions json", summary: false });
+    const decisions = extractJsonArray(decisionText);
+    if (!Array.isArray(decisions)) {
+      logger?.warn?.(`dsh-mneme dream: no json array in llm output (raw length ${decisionText?.length ?? 0})`);
+      return finish({ ok: false, error: "no json array in llm output", summary: false });
     }
     const { ok, errors } = validateDecisions(decisions, snapshot, {
       maxUpdatePerRun: config.reflectionUpdateMaxPerRun,

package/lib/hot-memory.js

@@ -0,0 +1,53 @@
+// Session-scoped hot memory (v0.5.0 召回率优化 1.3): a short-term buffer of
+// the latest dialogue rounds, kept strictly apart from the long-term memory
+// store. The injector renders it ahead of the long-term recall block so the
+// agent sees "what we were just talking about" without those rounds ever
+// being persisted as memories. Bounded two ways: maxRounds (count) and
+// maxTokens (budget) — whichever evicts first.
+
+// CJK-aware token estimate: one Chinese character ≈ 0.6 tokens (clustering
+// behavior of mainstream tokenizers), one ASCII char ≈ 0.25.
+export function estimateTokens(text) {
+  const s = String(text ?? "");
+  let cjk = 0;
+  for (const ch of s) if (ch >= "\u4e00" && ch <= "\u9fff") cjk++;
+  return Math.ceil(cjk * 0.6 + (s.length - cjk) * 0.25);
+}
+
+/**
+ * @param {{maxRounds?: number, maxTokens?: number}} opts
+ * @returns {{add(round: {query: string, response?: string}): void,
+ *            getContext(): string,
+ *            rounds(): Array, clear(): void}}
+ */
+export function createHotMemory({ maxRounds = 5, maxTokens = 2000 } = {}) {
+  // Entry defense: a non-positive or non-integer maxRounds (0, -1, 1.5, NaN,
+  // null, "2") would make the eviction while-loop unbounded — the buffer can
+  // never shrink below `buffer.length > maxRounds`, so `add` would spin forever.
+  // Fall back to the defaults so a hostile/buggy caller can never wedge the
+  // hot-memory buffer in an infinite loop.
+  maxRounds = (Number.isInteger(maxRounds) && maxRounds > 0) ? maxRounds : 5;
+  maxTokens = (Number.isFinite(maxTokens) && maxTokens > 0) ? maxTokens : 2000;
+  const buffer = [];
+
+  function totalTokens() {
+    return buffer.reduce(
+      (sum, r) => sum + estimateTokens(`Q: ${r.query}\nA: ${r.response ?? ""}`),
+      0
+    );
+  }
+
+  return {
+    add(round) {
+      if (!round?.query) return;
+      buffer.push({ query: String(round.query), response: String(round.response ?? "") });
+      while (buffer.length > maxRounds) buffer.shift();
+      while (buffer.length > 1 && totalTokens() > maxTokens) buffer.shift();
+    },
+    getContext() {
+      return buffer.map((r) => `Q: ${r.query}\nA: ${r.response ?? ""}`).join("\n\n");
+    },
+    rounds: () => [...buffer],
+    clear() { buffer.length = 0; }
+  };
+}

package/lib/inject.js

@@ -1,3 +1,5 @@
+import { createHotMemory } from "./hot-memory.js";
+
 // Best-effort extraction of the current user's latest message text from the
 // live session, for semantic-first injection (Bug4). The system-prompt
 // interpolator renders synchronously, so this walks the already-materialized
@@ -25,6 +27,50 @@ function lastUserQuery(ctx) {
   return "";
 }
 
+// Hot-memory round extraction (v0.5.0 1.3): pairs each user/message with the
+// next assistant reply from the materialized session log. Tolerates shapes
+// where assistant events carry a different type tag — anything whose payload
+// has content parts and is not a user message counts as a reply. Best-effort:
+// returns [] on any failure, and the hot block simply does not render.
+function extractRounds(ctx, maxRounds) {
+  try {
+    const events = ctx?.agent?.session?.events;
+    if (!Array.isArray(events) || events.length === 0) return [];
+    const rounds = [];
+    let pendingQuery = null;
+    const textOf = (event) => {
+      const parts = event?.data?.content;
+      if (!Array.isArray(parts)) return "";
+      return parts
+        .map((p) => (typeof p === "string" ? p : p?.text ?? ""))
+        .filter(Boolean)
+        .join("\n")
+        .trim();
+    };
+    for (const event of events) {
+      const kind = event?.data?.source?.kind;
+      const isUser = event?.type === "user/message" && (kind === undefined || kind === "user");
+      if (isUser) {
+        if (pendingQuery) rounds.push({ query: pendingQuery, response: "" });
+        pendingQuery = textOf(event).slice(0, 500);
+        continue;
+      }
+      // Only assistant-originated events close a round; tool/system events
+      // carrying text must not be mistaken for the model's reply.
+      const isAssistant = typeof event?.type === "string" && event.type.includes("assistant")
+        || kind === "assistant";
+      const body = isAssistant ? textOf(event) : "";
+      if (!body || !pendingQuery) continue;
+      rounds.push({ query: pendingQuery, response: body.slice(0, 800) });
+      pendingQuery = null;
+    }
+    if (pendingQuery) rounds.push({ query: pendingQuery, response: "" });
+    return rounds.slice(-maxRounds);
+  } catch {
+    return [];
+  }
+}
+
 export function createInjector(ctx, service, settings, config) {
   const maxItems = config.maxInjectedItems ?? 5;
   const threshold = config.importanceThreshold ?? 3;
@@ -36,6 +82,35 @@ export function createInjector(ctx, service, settings, config) {
   const MAX_CONTENT = 300;
   const MAX_BLOCK = 1500;
 
+  // Compressed injection (v0.5.0 2.1): a sleep-demoted row already carries its
+  // summary in `content` with the original parked in `_full_content` — inject
+  // the summary verbatim instead of re-truncating the (already short) text.
+  // Regular long rows keep the hard truncate.
+  function injectMemory(m, maxLength = MAX_CONTENT) {
+    if (m?._full_content) return String(m.content ?? "");
+    const text = String(m?.content ?? "");
+    return text.length <= maxLength ? text : `${text.slice(0, maxLength)}…`;
+  }
+
+  // Hot memory (v0.5.0 1.3): the latest rounds of THIS session, rebuilt from
+  // the materialized event log on every render — stateless, so it survives
+  // session switches and never persists anywhere.
+  const hot = createHotMemory({
+    maxRounds: config.hotMemoryRounds ?? 5,
+    maxTokens: config.hotMemoryMaxTokens ?? 2000
+  });
+
+  function renderHotContext(ctx) {
+    if (config.hotMemoryEnabled === false) return "";
+    const rounds = extractRounds(ctx, config.hotMemoryRounds ?? 5);
+    if (!rounds.length) return "";
+    hot.clear();
+    for (const r of rounds) hot.add(r);
+    const body = hot.getContext();
+    if (!body) return "";
+    return `[短期上下文] 最近对话（共 ${rounds.length} 轮）：\n${body}`;
+  }
+
   function render(candidates) {
     if (!candidates.length) return "";
     const header = "[记忆库] 来自 dsh-mneme 的跨会话记忆（用户偏好与高优先级项目/决策）：";
@@ -48,8 +123,7 @@ export function createInjector(ctx, service, settings, config) {
         ? "[verified] "
         : "";
       const title = `${m.title}（重要性 ${m.importance}）`;
-      let content = String(m.content ?? "");
-      if (content.length > MAX_CONTENT) content = `${content.slice(0, MAX_CONTENT)}…`;
+      const content = injectMemory(m);
       const full = `- [${m.type}] ${verified}${title}：${content}`;
       if (budget - full.length >= 0) {
         lines.push(full);
@@ -108,7 +182,14 @@ export function createInjector(ctx, service, settings, config) {
         if (query) prefetchQueryVector(query);
         const queryVector = queryVectorCache.get(query);
         const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold });
-        return render(candidates);
+        // Hot memory (v0.5.0 1.3) leads the single memory block: the agent
+        // sees the short-term rounds first, then the cross-session recall —
+        // the documented injection order 1→2. Folding it here (instead of a
+        // separate context) keeps the prompt assembly stable at two blocks.
+        const hotText = renderHotContext(ctx);
+        const body = render(candidates);
+        if (!hotText) return body;
+        return body ? `${hotText}\n\n${body}` : hotText;
       }
     }),
     ctx.systemPrompt.context({

package/lib/local-embedder.js

@@ -22,7 +22,13 @@ function modelHash(model) {
 
 /** Lazy default loader: dynamic import keeps module load cheap. */
 async function defaultPipelineLoader(task, model, options) {
-  const { pipeline } = await import("@huggingface/transformers");
+  const { env, pipeline } = await import("@huggingface/transformers");
+  // issue #13: transformers.js's get_tokenizer_files() drops the caller's
+  // cache_dir when it pre-checks tokenizer_config.json metadata, so the HEAD
+  // request falls back to env.cacheDir and hits the network even when the
+  // model is fully cached locally. Mirroring the cache_dir onto env.cacheDir
+  // makes that pre-check resolve locally too — fully offline loading.
+  if (options?.cache_dir) env.cacheDir = options.cache_dir;
   return pipeline(task, model, options);
 }
 

package/lib/reranker.js

@@ -21,7 +21,10 @@ function modelHash(model) {
 
 /** Lazy default pipeline factory: dynamic import keeps module load cheap. */
 async function defaultPipelineLoader(task, model, options) {
-  const { pipeline } = await import("@huggingface/transformers");
+  const { env, pipeline } = await import("@huggingface/transformers");
+  // issue #13: mirror cache_dir onto env.cacheDir so the tokenizer pre-check
+  // resolves locally too (same fix as local-embedder.js).
+  if (options?.cache_dir) env.cacheDir = options.cache_dir;
   return pipeline(task, model, options);
 }
 

package/lib/search/adaptive.js

@@ -0,0 +1,22 @@
+// Adaptive vector threshold (v0.5.0 召回率优化 1.2): replaces the fixed
+// vectorSearchThreshold=0.65 with a query-aware cutoff.
+//   entity:/attr: prefixes → 0.5  (entity recall is name-driven; loosen)
+//   very short queries      → 0.7  (<5 chars match almost anything; tighten)
+//   very long queries       → 0.6  (semantically specific; loosen a little)
+//   head-gap rule           → when the top-1 vs top-5 candidate gap exceeds
+//                             0.3 the head is decisive — loosen to 0.5 so
+//                             the tail still reaches the reranker
+//   otherwise               → 0.65 (the legacy default)
+// Pure and total: same inputs, same cutoff, no store access.
+export function adaptiveThreshold(query, candidates = []) {
+  const q = String(query ?? "");
+  if (q.startsWith("entity:") || q.startsWith("attr:")) return 0.5;
+  if (q.length > 0 && q.length < 5) return 0.7;
+  if (q.length > 50) return 0.6;
+  const scores = (Array.isArray(candidates) ? candidates : [])
+    .map((c) => (typeof c?._score === "number" ? c._score : typeof c?.score === "number" ? c.score : 0))
+    .filter((s) => s > 0)
+    .sort((a, b) => b - a);
+  if (scores.length >= 5 && scores[0] - scores[4] > 0.3) return 0.5;
+  return 0.65;
+}

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,22 +492,48 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           byId.set(m.id, m);
         }
       }
-      const ranked = [...byId.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+      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))
+        .map((r) => ({ ...r, score: Math.max(0, Math.min(1, r.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)
+      // 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 +920,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 +1480,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)
   };
 }