@modusensus/dsh-mneme 0.5.2 → 0.6.0

package/src/store.js

@@ -11,6 +11,7 @@ CREATE TABLE IF NOT EXISTS memories (
   importance  INTEGER NOT NULL DEFAULT 3,
   forgotten   INTEGER NOT NULL DEFAULT 0,
   archived    INTEGER NOT NULL DEFAULT 0,
+  session_disposed_at TEXT,
   source      TEXT,
   session_id  TEXT,
   content_history TEXT,
@@ -321,6 +322,7 @@ function toRow(row) {
     importance: row.importance,
     forgotten: row.forgotten === 1,
     archived: row.archived === 1,
+    session_disposed_at: row.session_disposed_at ?? undefined,
     source: row.source ?? undefined,
     session_id: row.session_id ?? undefined,
     content_history: parseJsonArray(row.content_history),
@@ -567,6 +569,7 @@ export function createStore(path) {
   };
 
   addColumn("memories", "archived", "ALTER TABLE memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
+  addColumn("memories", "session_disposed_at", "ALTER TABLE memories ADD COLUMN session_disposed_at TEXT");
   addColumn("memories", "embedding", "ALTER TABLE memories ADD COLUMN embedding TEXT");
   addColumn("memories", "last_accessed_at", "ALTER TABLE memories ADD COLUMN last_accessed_at TEXT");
   addColumn("memories", "_full_content", "ALTER TABLE memories ADD COLUMN _full_content TEXT");
@@ -575,6 +578,12 @@ export function createStore(path) {
   addColumn("memories", "quality_score", "ALTER TABLE memories ADD COLUMN quality_score REAL");
   addColumn("memories", "session_id", "ALTER TABLE memories ADD COLUMN session_id TEXT");
 
+  // Composite index for session-lifecycle queries (dispose/restore/listBySession).
+  // Created post-migration, NOT in SCHEMA: on legacy DBs both columns arrive via
+  // ADD COLUMN above, so the index would fail at db.exec(SCHEMA) time. CREATE
+  // INDEX IF NOT EXISTS is atomic, so the two-process race is safe here.
+  db.exec("CREATE INDEX IF NOT EXISTS idx_memories_session ON memories(session_id, session_disposed_at)");
+
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   addColumn("dream_runs", "policy_epoch", "ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
   addColumn("dream_runs", "run_type", "ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
@@ -618,7 +627,7 @@ export function createStore(path) {
     return ts;
   }
 
-  function count(type, { includeForgotten = false, includeArchived = false } = {}) {
+  function count(type, { includeForgotten = false, includeArchived = false, includeDisposed = false } = {}) {
     const clauses = [];
     const params = [];
     if (type !== undefined) {
@@ -631,6 +640,9 @@ export function createStore(path) {
     if (!includeArchived) {
       clauses.push("archived = 0");
     }
+    if (!includeDisposed) {
+      clauses.push("session_disposed_at IS NULL");
+    }
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     return db.prepare(`SELECT count(*) AS c FROM memories ${where}`).get(...params).c;
   }
@@ -820,6 +832,45 @@ export function createStore(path) {
     return getById(id);
   }
 
+  // --- session lifecycle (v0.6.0) ------------------------------------------
+  // Session dispose is orthogonal to `archived`: memory_archive is the user/AI
+  // choosing to keep an entry long-term-but-quiet, while session_disposed_at
+  // marks entries hidden because the session they were born in was deleted
+  // (a reversible "undo" — restoreBySession clears it). They never clobber each
+  // other: restoreBySession must not resurrect user-archived memories.
+  // Mirrors list/search: disposed rows are hidden by default. A consumer that
+  // needs to see the full picture (e.g. a restore flow that tells the user
+  // "these N entries were hidden") opts in via includeDisposed.
+  function listBySession(sessionId, { includeDisposed = false } = {}) {
+    const disposedFilter = includeDisposed ? "" : "AND session_disposed_at IS NULL";
+    const rows = db.prepare(
+      `SELECT * FROM memories WHERE session_id = ? ${disposedFilter} ORDER BY updated_at DESC`
+    ).all(sessionId);
+    return rows.map(toRow);
+  }
+
+  // Idempotent by state guard, not timestamp compare (nowIso() differs every
+  // call, so a fresh-timestamp re-dispose would spuriously count): dispose only
+  // touches rows that are NOT yet disposed; restore only touches rows that ARE.
+  // updated_at is deliberately left alone — this is a lifecycle flag, not
+  // content — so a true flip is the sole trigger for a mirror generation.
+  function setDisposedBySession(sessionId, disposed) {
+    const at = disposed ? nowIso() : null;
+    let affected = 0;
+    runAtomically(() => {
+      const result = disposed
+        ? db.prepare(
+            "UPDATE memories SET session_disposed_at = ? WHERE session_id = ? AND session_disposed_at IS NULL"
+          ).run(at, sessionId)
+        : db.prepare(
+            "UPDATE memories SET session_disposed_at = NULL WHERE session_id = ? AND session_disposed_at IS NOT NULL"
+          ).run(sessionId);
+      affected = result.changes;
+      if (affected > 0) incrementGeneration();
+    });
+    return affected;
+  }
+
   // --- sleep-mode storage support (v0.4.0) ---------------------------------
   // touchLastAccess stamps the read time on recall/inject paths. It deliberately
   // does NOT bump the mirror generation: reads must not mark the mirror dirty.
@@ -876,6 +927,7 @@ export function createStore(path) {
     const rows = db.prepare(
       `SELECT * FROM memories
        WHERE forgotten = 0 AND archived = 0
+         AND session_disposed_at IS NULL
          AND (last_accessed_at IS NULL OR last_accessed_at < ?)
        ORDER BY COALESCE(last_accessed_at, created_at) ASC, id
        LIMIT ?`
@@ -883,7 +935,7 @@ export function createStore(path) {
     return rows.map(toRow);
   }
 
-  function list({ type, limit = 50, offset = 0, includeForgotten = false, includeArchived = false } = {}) {
+  function list({ type, limit = 50, offset = 0, includeForgotten = false, includeArchived = false, includeDisposed = false } = {}) {
     const clauses = [];
     const params = [];
     if (type) {
@@ -896,6 +948,9 @@ export function createStore(path) {
     if (!includeArchived) {
       clauses.push("archived = 0");
     }
+    if (!includeDisposed) {
+      clauses.push("session_disposed_at IS NULL");
+    }
     const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     const rows = db.prepare(
@@ -953,7 +1008,7 @@ export function createStore(path) {
     ).all(limit);
   }
 
-  function search(query, { limit = 20, includeArchived = false } = {}) {
+  function search(query, { limit = 20, includeArchived = false, includeDisposed = false } = {}) {
     const q = String(query).trim();
     if (!q) return [];
     // Plain LIKE substring scan over title/content/tags (wildcards escaped so
@@ -962,9 +1017,10 @@ export function createStore(path) {
     const like = `%${escapeLike(q)}%`;
     const { limit: lim } = sanitizePage(limit, 0, 20);
     const archivedFilter = includeArchived ? "" : "archived = 0 AND ";
+    const disposedFilter = includeDisposed ? "" : "session_disposed_at IS NULL AND ";
     const rows = db.prepare(
       `SELECT * FROM memories
-       WHERE ${archivedFilter}forgotten = 0 AND (title LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\' OR tags LIKE ? ESCAPE '\\')
+       WHERE ${archivedFilter}${disposedFilter}forgotten = 0 AND (title LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\' OR tags LIKE ? ESCAPE '\\')
        ORDER BY
          CASE WHEN title LIKE ? ESCAPE '\\' THEN 0 ELSE 1 END,
          importance DESC,
@@ -995,12 +1051,13 @@ export function createStore(path) {
    * Brute-force cosine similarity over embedded rows. Returns rows decorated
    * with a `score` (0..1). Only rows with a stored embedding participate.
    */
-  function searchVector(vector, { limit = 20, includeArchived = false, threshold = 0 } = {}) {
+  function searchVector(vector, { limit = 20, includeArchived = false, includeDisposed = false, threshold = 0 } = {}) {
     if (!Array.isArray(vector) || !vector.length) return [];
     const archivedFilter = includeArchived ? "" : "archived = 0 AND ";
+    const disposedFilter = includeDisposed ? "" : "session_disposed_at IS NULL AND ";
     const rows = db.prepare(
       `SELECT * FROM memories
-       WHERE ${archivedFilter}forgotten = 0 AND embedding IS NOT NULL AND embedding != ''`
+       WHERE ${archivedFilter}${disposedFilter}forgotten = 0 AND embedding IS NOT NULL AND embedding != ''`
     ).all();
     const scored = [];
     for (const row of rows) {
@@ -1871,6 +1928,8 @@ export function createStore(path) {
     remove,
     setForget,
     setArchived,
+    listBySession,
+    setDisposedBySession,
     touchLastAccess,
     demoteToSummary,
     restoreContent,

package/src/tools.js

@@ -180,9 +180,10 @@ export function createTools(ctx, service, config, embedder) {
 
     defineTool({
       name: "memory_delete",
-      description: "Permanently delete a memory entry.",
+      description: "Permanently delete a memory entry. Pass id for exact delete, or query to delete the single best-matching entry by text — lets the agent honor 'delete the memory about X' without a prior list/search round trip.",
       parameters: {
-        id: { type: "string", required: true }
+        id: { type: "string", description: "Exact memory id to delete (from memory_list/memory_search output)" },
+        query: { type: "string", description: "Delete the best-matching entry for this text (searches title/content/tags; uses hybrid recall when an embedder is configured)" }
       },
       output: {
         schema: {
@@ -193,9 +194,19 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(value.deleted ? "Memory deleted." : "Memory not found.")
       },
       async execute(args) {
-        const existed = service.getById(args.id) !== undefined;
-        if (existed) service.remove(args.id);
-        return { deleted: existed };
+        if (args.id) {
+          const existed = service.getById(args.id) !== undefined;
+          if (existed) service.remove(args.id);
+          return { deleted: existed };
+        }
+        if (args.query) {
+          const [best] = await service.searchMemories(args.query, { mode: "auto", topK: 1, useRerank: true });
+          if (best) {
+            service.remove(best.id);
+            return { deleted: true };
+          }
+        }
+        return { deleted: false };
       }
     }),
 

package/test/hot-memory.test.js

@@ -1,174 +1,174 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { createHotMemory, estimateTokens } from "../src/hot-memory.js";
-import { createStore } from "../src/store.js";
-import { createService } from "../src/service.js";
-import { createVectorIndex } from "../src/vector-index.js";
-
-// --- hot memory buffer ---
-
-test("hot memory keeps the latest rounds within maxRounds", () => {
-  const hot = createHotMemory({ maxRounds: 2, maxTokens: 10000 });
-  hot.add({ query: "第一轮", response: "答一" });
-  hot.add({ query: "第二轮", response: "答二" });
-  hot.add({ query: "第三轮", response: "答三" });
-  assert.equal(hot.rounds().length, 2);
-  assert.ok(hot.getContext().includes("第三轮"));
-  assert.ok(!hot.getContext().includes("第一轮"));
-});
-
-test("hot memory enforces the token budget", () => {
-  const hot = createHotMemory({ maxRounds: 10, maxTokens: 30 });
-  hot.add({ query: "很长的第一轮问题".repeat(10), response: "很长的回答".repeat(10) });
-  hot.add({ query: "第二轮", response: "答二" });
-  // The first round alone blows the budget; the newest round survives and
-  // the buffer never empties completely.
-  const rounds = hot.rounds();
-  assert.ok(rounds.length >= 1);
-  assert.equal(rounds[rounds.length - 1].query, "第二轮");
-});
-
-test("hot memory getContext uses the Q/A round format", () => {
-  const hot = createHotMemory({ maxRounds: 5, maxTokens: 10000 });
-  hot.add({ query: "Q1", response: "A1" });
-  hot.add({ query: "Q2", response: "A2" });
-  assert.equal(hot.getContext(), "Q: Q1\nA: A1\n\nQ: Q2\nA: A2");
-});
-
-test("hot memory ignores empty rounds and clears", () => {
-  const hot = createHotMemory({ maxRounds: 5, maxTokens: 10000 });
-  hot.add({ query: "", response: "x" });
-  hot.add(null);
-  assert.equal(hot.rounds().length, 0);
-  hot.add({ query: "q" });
-  hot.clear();
-  assert.equal(hot.getContext(), "");
-});
-
-test("estimateTokens counts CJK heavier than ASCII", () => {
-  assert.ok(estimateTokens("中文内容") > estimateTokens("abcd"));
-});
-
-// --- entry defense: non-positive / non-integer bounds fall back to defaults ---
-// Bug: createHotMemory({ maxRounds: -1 }) made the eviction while-loop
-// `while (buffer.length > maxRounds)` unbounded — after the buffer emptied,
-// `0 > -1` stayed true and buffer.shift() on an empty array is a no-op, so
-// every add() spun forever. Non-integer values (1.5, NaN, null) were also
-// silently wrong. The fix clamps them to the 5/2000 defaults at the door.
-
-test("hot memory falls back to maxRounds=5 for non-positive/invalid values", () => {
-  for (const bad of [0, -1, 1.5, NaN, null]) {
-    const hot = createHotMemory({ maxRounds: bad, maxTokens: 10000 });
-    for (let i = 0; i < 8; i++) hot.add({ query: `第${i}轮`, response: "x" });
-    assert.equal(hot.rounds().length, 5, `maxRounds=${bad} must fall back to 5, no infinite loop`);
-    assert.ok(hot.getContext().includes("第7轮"), `maxRounds=${bad}: newest round survives`);
-    assert.ok(!hot.getContext().includes("第0轮"), `maxRounds=${bad}: oldest round evicted`);
-  }
-});
-
-test("hot memory falls back to maxTokens=2000 for non-positive/infinite values", () => {
-  for (const bad of [0, -1, Infinity]) {
-    const hot = createHotMemory({ maxRounds: 50, maxTokens: bad });
-    // 50 rounds at ~74 tokens each blow a 2000-token budget; the fallback must
-    // evict into (1, 50). A broken budget of 0/-1 would squeeze to 1 round and
-    // Infinity would keep all 50 — both are the pre-fix behavior.
-    for (let i = 0; i < 50; i++) hot.add({ query: `第${i}轮`, response: "长回答".repeat(40) });
-    const n = hot.rounds().length;
-    assert.ok(n > 1 && n < 50, `maxTokens=${bad} falls back to 2000 (kept ${n} rounds)`);
-  }
-});
-
-// --- service-level: BM25 fusion + semantic dedup + selective injection ---
-
-function toyVec(text) {
-  const v = new Array(64).fill(0);
-  for (const t of String(text).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean)) {
-    let h = 0;
-    for (const ch of t) h = (h * 31 + ch.codePointAt(0)) >>> 0;
-    v[h % 64] += 1;
-  }
-  const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1;
-  return v.map((x) => x / norm);
-}
-
-function setup(overrides = {}) {
-  const store = createStore(":memory:");
-  const config = {
-    entitySearchEnabled: false,
-    bm25SearchEnabled: true,
-    adaptiveThresholdEnabled: false,
-    searchSemanticDedup: true,
-    selectiveInjectEnabled: true,
-    ...overrides
-  };
-  const service = createService({ store, mirror: null, config, logger: null });
-  service.setVectorIndex(createVectorIndex({ store, logger: null }));
-  service.setEmbedder({ embedSingle: async (t) => toyVec(t) });
-  return { store, service };
-}
-
-test("searchMemories fuses BM25: scattered-term queries recall both rows", async () => {
-  const { store, service } = setup();
-  const a = store.save({ type: "project", title: "异步并发模式", content: "async runtime 选用 tokio", importance: 3 });
-  const b = store.save({ type: "decision", title: "语言迁移", content: "编译模块迁移到 Rust", importance: 3 });
-  store.save({ type: "project", title: "无关", content: "夜间 ETL 脚本", importance: 3 });
-
-  // "rust 异步" is not a substring of either row — LIKE misses both; BM25
-  // must surface both rows in the merged result.
-  const results = await service.searchMemories("rust 异步", { mode: "auto", topK: 5 });
-  const ids = results.map((r) => r.id);
-  assert.ok(ids.includes(a.id), "async row must be recalled via BM25");
-  assert.ok(ids.includes(b.id), "rust row must be recalled via BM25");
-  assert.equal(results.find((r) => r.id === a.id)?.source, "bm25");
-});
-
-test("bm25SearchEnabled=false restores the two-path behavior", async () => {
-  const { store, service } = setup({ bm25SearchEnabled: false });
-  const a = store.save({ type: "project", title: "异步并发模式", content: "async runtime 选用 tokio", importance: 3 });
-  const results = await service.searchMemories("rust 异步", { mode: "auto", topK: 5 });
-  assert.ok(!results.some((r) => r.id === a.id), "no BM25 → scattered-term miss is back");
-});
-
-test("search-time semantic dedup drops near-identical embeddings", async () => {
-  const { store, service } = setup();
-  const a = store.save({ type: "project", title: "偏好 A", content: "用户喜欢深色主题编辑器", importance: 3 });
-  const b = store.save({ type: "project", title: "偏好 A 备份", content: "用户喜欢深色主题编辑器（备份）", importance: 3 });
-  store.setEmbedding(a.id, toyVec("用户喜欢深色主题编辑器"));
-  store.setEmbedding(b.id, toyVec("用户喜欢深色主题编辑器"));
-
-  // auto (not keyword): keyword mode is the documented text-only path and is
-  // exempt from dedup by design; auto exercises the dedup the way production
-  // searches run.
-  const results = await service.searchMemories("深色主题", { mode: "auto", topK: 5 });
-  const ids = results.map((r) => r.id);
-  assert.ok(ids.includes(a.id) !== ids.includes(b.id), "one of the near-duplicate pair is dropped");
-});
-
-test("searchSemanticDedup=false keeps duplicate embeddings", async () => {
-  const { store, service } = setup({ searchSemanticDedup: false });
-  const a = store.save({ type: "project", title: "偏好 A", content: "用户喜欢深色主题编辑器", importance: 3 });
-  const b = store.save({ type: "project", title: "偏好 A 备份", content: "用户喜欢深色主题编辑器（备份）", importance: 3 });
-  store.setEmbedding(a.id, toyVec("用户喜欢深色主题编辑器"));
-  store.setEmbedding(b.id, toyVec("用户喜欢深色主题编辑器"));
-  const results = await service.searchMemories("深色主题", { mode: "keyword", topK: 5 });
-  assert.equal(results.length, 2);
-});
-
-test("selective injection re-orders candidates by query similarity", () => {
-  const { store, service } = setup();
-  const thesis = store.save({ type: "project", title: "湿地论文", content: "毕业论文研究城市湿地公园", importance: 5 });
-  const plugin = store.save({ type: "project", title: "插件项目", content: "dsh-mneme 记忆插件开发", importance: 5 });
-  store.setEmbedding(thesis.id, toyVec("毕业论文研究城市湿地公园"));
-  store.setEmbedding(plugin.id, toyVec("dsh-mneme 记忆插件开发"));
-
-  // Rule-based order would put both at equal importance; the query vector is
-  // about the thesis, so topic ranking must put the thesis memory first.
-  const picked = service.injectCandidates({
-    query: "论文写作",
-    queryVector: toyVec("毕业论文研究城市湿地公园"),
-    maxItems: 2,
-    threshold: 3
-  });
-  assert.equal(picked[0].id, thesis.id);
-  assert.ok(picked.some((m) => m.id === plugin.id));
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHotMemory, estimateTokens } from "../src/hot-memory.js";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createVectorIndex } from "../src/vector-index.js";
+
+// --- hot memory buffer ---
+
+test("hot memory keeps the latest rounds within maxRounds", () => {
+  const hot = createHotMemory({ maxRounds: 2, maxTokens: 10000 });
+  hot.add({ query: "第一轮", response: "答一" });
+  hot.add({ query: "第二轮", response: "答二" });
+  hot.add({ query: "第三轮", response: "答三" });
+  assert.equal(hot.rounds().length, 2);
+  assert.ok(hot.getContext().includes("第三轮"));
+  assert.ok(!hot.getContext().includes("第一轮"));
+});
+
+test("hot memory enforces the token budget", () => {
+  const hot = createHotMemory({ maxRounds: 10, maxTokens: 30 });
+  hot.add({ query: "很长的第一轮问题".repeat(10), response: "很长的回答".repeat(10) });
+  hot.add({ query: "第二轮", response: "答二" });
+  // The first round alone blows the budget; the newest round survives and
+  // the buffer never empties completely.
+  const rounds = hot.rounds();
+  assert.ok(rounds.length >= 1);
+  assert.equal(rounds[rounds.length - 1].query, "第二轮");
+});
+
+test("hot memory getContext uses the Q/A round format", () => {
+  const hot = createHotMemory({ maxRounds: 5, maxTokens: 10000 });
+  hot.add({ query: "Q1", response: "A1" });
+  hot.add({ query: "Q2", response: "A2" });
+  assert.equal(hot.getContext(), "Q: Q1\nA: A1\n\nQ: Q2\nA: A2");
+});
+
+test("hot memory ignores empty rounds and clears", () => {
+  const hot = createHotMemory({ maxRounds: 5, maxTokens: 10000 });
+  hot.add({ query: "", response: "x" });
+  hot.add(null);
+  assert.equal(hot.rounds().length, 0);
+  hot.add({ query: "q" });
+  hot.clear();
+  assert.equal(hot.getContext(), "");
+});
+
+test("estimateTokens counts CJK heavier than ASCII", () => {
+  assert.ok(estimateTokens("中文内容") > estimateTokens("abcd"));
+});
+
+// --- entry defense: non-positive / non-integer bounds fall back to defaults ---
+// Bug: createHotMemory({ maxRounds: -1 }) made the eviction while-loop
+// `while (buffer.length > maxRounds)` unbounded — after the buffer emptied,
+// `0 > -1` stayed true and buffer.shift() on an empty array is a no-op, so
+// every add() spun forever. Non-integer values (1.5, NaN, null) were also
+// silently wrong. The fix clamps them to the 5/2000 defaults at the door.
+
+test("hot memory falls back to maxRounds=5 for non-positive/invalid values", () => {
+  for (const bad of [0, -1, 1.5, NaN, null]) {
+    const hot = createHotMemory({ maxRounds: bad, maxTokens: 10000 });
+    for (let i = 0; i < 8; i++) hot.add({ query: `第${i}轮`, response: "x" });
+    assert.equal(hot.rounds().length, 5, `maxRounds=${bad} must fall back to 5, no infinite loop`);
+    assert.ok(hot.getContext().includes("第7轮"), `maxRounds=${bad}: newest round survives`);
+    assert.ok(!hot.getContext().includes("第0轮"), `maxRounds=${bad}: oldest round evicted`);
+  }
+});
+
+test("hot memory falls back to maxTokens=2000 for non-positive/infinite values", () => {
+  for (const bad of [0, -1, Infinity]) {
+    const hot = createHotMemory({ maxRounds: 50, maxTokens: bad });
+    // 50 rounds at ~74 tokens each blow a 2000-token budget; the fallback must
+    // evict into (1, 50). A broken budget of 0/-1 would squeeze to 1 round and
+    // Infinity would keep all 50 — both are the pre-fix behavior.
+    for (let i = 0; i < 50; i++) hot.add({ query: `第${i}轮`, response: "长回答".repeat(40) });
+    const n = hot.rounds().length;
+    assert.ok(n > 1 && n < 50, `maxTokens=${bad} falls back to 2000 (kept ${n} rounds)`);
+  }
+});
+
+// --- service-level: BM25 fusion + semantic dedup + selective injection ---
+
+function toyVec(text) {
+  const v = new Array(64).fill(0);
+  for (const t of String(text).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean)) {
+    let h = 0;
+    for (const ch of t) h = (h * 31 + ch.codePointAt(0)) >>> 0;
+    v[h % 64] += 1;
+  }
+  const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1;
+  return v.map((x) => x / norm);
+}
+
+function setup(overrides = {}) {
+  const store = createStore(":memory:");
+  const config = {
+    entitySearchEnabled: false,
+    bm25SearchEnabled: true,
+    adaptiveThresholdEnabled: false,
+    searchSemanticDedup: true,
+    selectiveInjectEnabled: true,
+    ...overrides
+  };
+  const service = createService({ store, mirror: null, config, logger: null });
+  service.setVectorIndex(createVectorIndex({ store, logger: null }));
+  service.setEmbedder({ embedSingle: async (t) => toyVec(t) });
+  return { store, service };
+}
+
+test("searchMemories fuses BM25: scattered-term queries recall both rows", async () => {
+  const { store, service } = setup();
+  const a = store.save({ type: "project", title: "异步并发模式", content: "async runtime 选用 tokio", importance: 3 });
+  const b = store.save({ type: "decision", title: "语言迁移", content: "编译模块迁移到 Rust", importance: 3 });
+  store.save({ type: "project", title: "无关", content: "夜间 ETL 脚本", importance: 3 });
+
+  // "rust 异步" is not a substring of either row — LIKE misses both; BM25
+  // must surface both rows in the merged result.
+  const results = await service.searchMemories("rust 异步", { mode: "auto", topK: 5 });
+  const ids = results.map((r) => r.id);
+  assert.ok(ids.includes(a.id), "async row must be recalled via BM25");
+  assert.ok(ids.includes(b.id), "rust row must be recalled via BM25");
+  assert.equal(results.find((r) => r.id === a.id)?.source, "bm25");
+});
+
+test("bm25SearchEnabled=false restores the two-path behavior", async () => {
+  const { store, service } = setup({ bm25SearchEnabled: false });
+  const a = store.save({ type: "project", title: "异步并发模式", content: "async runtime 选用 tokio", importance: 3 });
+  const results = await service.searchMemories("rust 异步", { mode: "auto", topK: 5 });
+  assert.ok(!results.some((r) => r.id === a.id), "no BM25 → scattered-term miss is back");
+});
+
+test("search-time semantic dedup drops near-identical embeddings", async () => {
+  const { store, service } = setup();
+  const a = store.save({ type: "project", title: "偏好 A", content: "用户喜欢深色主题编辑器", importance: 3 });
+  const b = store.save({ type: "project", title: "偏好 A 备份", content: "用户喜欢深色主题编辑器（备份）", importance: 3 });
+  store.setEmbedding(a.id, toyVec("用户喜欢深色主题编辑器"));
+  store.setEmbedding(b.id, toyVec("用户喜欢深色主题编辑器"));
+
+  // auto (not keyword): keyword mode is the documented text-only path and is
+  // exempt from dedup by design; auto exercises the dedup the way production
+  // searches run.
+  const results = await service.searchMemories("深色主题", { mode: "auto", topK: 5 });
+  const ids = results.map((r) => r.id);
+  assert.ok(ids.includes(a.id) !== ids.includes(b.id), "one of the near-duplicate pair is dropped");
+});
+
+test("searchSemanticDedup=false keeps duplicate embeddings", async () => {
+  const { store, service } = setup({ searchSemanticDedup: false });
+  const a = store.save({ type: "project", title: "偏好 A", content: "用户喜欢深色主题编辑器", importance: 3 });
+  const b = store.save({ type: "project", title: "偏好 A 备份", content: "用户喜欢深色主题编辑器（备份）", importance: 3 });
+  store.setEmbedding(a.id, toyVec("用户喜欢深色主题编辑器"));
+  store.setEmbedding(b.id, toyVec("用户喜欢深色主题编辑器"));
+  const results = await service.searchMemories("深色主题", { mode: "keyword", topK: 5 });
+  assert.equal(results.length, 2);
+});
+
+test("selective injection re-orders candidates by query similarity", () => {
+  const { store, service } = setup();
+  const thesis = store.save({ type: "project", title: "湿地论文", content: "毕业论文研究城市湿地公园", importance: 5 });
+  const plugin = store.save({ type: "project", title: "插件项目", content: "dsh-mneme 记忆插件开发", importance: 5 });
+  store.setEmbedding(thesis.id, toyVec("毕业论文研究城市湿地公园"));
+  store.setEmbedding(plugin.id, toyVec("dsh-mneme 记忆插件开发"));
+
+  // Rule-based order would put both at equal importance; the query vector is
+  // about the thesis, so topic ranking must put the thesis memory first.
+  const picked = service.injectCandidates({
+    query: "论文写作",
+    queryVector: toyVec("毕业论文研究城市湿地公园"),
+    maxItems: 2,
+    threshold: 3
+  });
+  assert.equal(picked[0].id, thesis.id);
+  assert.ok(picked.some((m) => m.id === plugin.id));
+});