claude-mem-lite 2.88.0 → 2.89.0

package/.claude-plugin/marketplace.json

@@ -10,9 +10,9 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.88.0",
+      "version": "2.89.0",
       "source": "./",
-      "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. Alternative to claude-mem with 600x lower cost."
+      "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.88.0",
-  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. Alternative to claude-mem with 600x lower cost.",
+  "version": "2.89.0",
+  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"
   },

package/README.md

@@ -4,7 +4,7 @@
 
 `claude-mem-lite` is a **persistent memory** (also called *long-term memory* or *cross-session context*) system for **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — Anthropic's CLI coding agent. It runs as an **[MCP](https://modelcontextprotocol.io/) server** plus a set of Claude Code hooks, automatically capturing coding observations, decisions, and bug fixes during sessions, then providing hybrid full-text + semantic search to recall them later.
 
-Compared to general-purpose LLM memory frameworks like [`mem0`](https://github.com/mem0ai/mem0) or the MCP reference [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) server, claude-mem-lite is purpose-built for Claude Code's hook lifecycle: episode batching cuts LLM calls 7–10× vs the original [claude-mem](https://github.com/thedotmack/claude-mem) (600× lower total cost), and the hybrid FTS5 + TF-IDF retriever benchmarks at 0.88 Recall@10 / 0.96 Precision@10.
+Compared to general-purpose LLM memory frameworks like [`mem0`](https://github.com/mem0ai/mem0) or the MCP reference [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) server, claude-mem-lite is purpose-built for Claude Code's hook lifecycle: episode batching cuts LLM calls 7–10× vs the original [claude-mem](https://github.com/thedotmack/claude-mem) (an estimated ~600× lower total cost — see the cost model below; this is an architecture estimate, not a measured benchmark), while the hybrid FTS5 + TF-IDF retriever benchmarks at 0.88 Recall@10 / 0.96 Precision@10.
 
 > 中文简介：claude-mem-lite 是 Claude Code 的轻量级**持久化记忆 / 长期记忆 / 跨会话上下文**插件，基于 MCP 协议 + 钩子机制，自动捕获编码会话中的决策、修复和上下文，并通过 FTS5 + TF-IDF 混合检索召回。详见 [中文 README](README.zh-CN.md)。
 
@@ -29,15 +29,17 @@ A ground-up redesign of [claude-mem](https://github.com/thedotmack/claude-mem),
 
 ### Token & cost efficiency
 
-For a typical 50-tool-call session:
+For a typical 50-tool-call session (illustrative cost model — the ratios below are
+architecture estimates derived from batch size, token counts, and model pricing, **not**
+a measured end-to-end benchmark):
 
-| | claude-mem | claude-mem-lite | Ratio |
+| | claude-mem | claude-mem-lite | Ratio (estimated) |
 |---|---|---|---|
-| LLM calls | ~50 (every tool use) | ~5-8 (per episode) | **7-10x fewer** |
-| Tokens per call | 1,000-5,000 (raw JSON + history) | 200-500 (summaries only) | **5-10x smaller** |
-| Total tokens | ~100K-250K | ~1K-4K | **50-100x less** |
-| Model cost | Sonnet ($3/$15 per M) | Haiku ($0.25/$1.25 per M) | **12x cheaper** |
-| Combined savings | | | **600x+ lower cost** |
+| LLM calls | ~50 (every tool use) | ~5-8 (per episode) | **~7-10x fewer** |
+| Tokens per call | 1,000-5,000 (raw JSON + history) | 200-500 (summaries only) | **~5-10x smaller** |
+| Total tokens | ~100K-250K | ~1K-4K | **~50-100x less** |
+| Model cost | Sonnet ($3/$15 per M) | Haiku ($0.25/$1.25 per M) | **~12x cheaper** |
+| Combined savings | | | **~600x lower cost (estimated)** |
 
 ### Quality comparison
 
@@ -681,7 +683,7 @@ No. Claude Code's `CLAUDE.md` and `MEMORY.md` files act as static instruction me
 
 ### Why "lite"? What did the original claude-mem do differently?
 
-The original called an LLM on every tool use with raw JSON inputs. claude-mem-lite batches 5–10 operations per LLM call, uses a smaller model (Haiku), and runs a deterministic code-level filter before sending anything to the model. Net result: ~600× lower cost with equivalent search quality. See the [Architecture comparison](#architecture-comparison) above.
+The original called an LLM on every tool use with raw JSON inputs. claude-mem-lite batches 5–10 operations per LLM call, uses a smaller model (Haiku), and runs a deterministic code-level filter before sending anything to the model. Net result: an estimated ~600× lower cost (an architecture estimate from the cost model above, not a measured benchmark) with equivalent search quality. See the [Architecture comparison](#architecture-comparison) above.
 
 ### Does this work cross-project? Cross-machine?
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 `claude-mem-lite` 是 **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)**（Anthropic 官方 CLI 编程代理）的 **持久化记忆系统**（也称 **长期记忆 / 跨会话上下文 / Claude Code 记忆插件**）。它以 **[MCP](https://modelcontextprotocol.io/) 服务器** + Claude Code 钩子（hooks）的形式运行，在编码会话中自动捕获观察记录、决策、bug 修复，并通过 FTS5 全文检索 + TF-IDF 向量的混合检索召回历史上下文。
 
-与 [`mem0`](https://github.com/mem0ai/mem0)、MCP 官方参考实现的 [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 服务器等通用 LLM 记忆框架相比，claude-mem-lite 专为 Claude Code 的钩子生命周期定制：episode 批处理把 LLM 调用量相比原版 [claude-mem](https://github.com/thedotmack/claude-mem) 减少 7-10 倍（综合成本下降 600 倍），FTS5 + TF-IDF 混合检索在 30 个查询的基准上达到 **Recall@10 = 0.88 / Precision@10 = 0.96**。
+与 [`mem0`](https://github.com/mem0ai/mem0)、MCP 官方参考实现的 [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 服务器等通用 LLM 记忆框架相比，claude-mem-lite 专为 Claude Code 的钩子生命周期定制：episode 批处理把 LLM 调用量相比原版 [claude-mem](https://github.com/thedotmack/claude-mem) 减少 7-10 倍（综合成本估算下降约 600 倍 —— 见下方成本模型，属架构估算而非实测基准）；FTS5 + TF-IDF 混合检索在 30 个查询的基准上达到 **Recall@10 = 0.88 / Precision@10 = 0.96**。
 
 无需外部服务。单一 SQLite 数据库。开销极低。
 
@@ -27,15 +27,15 @@
 
 ### Token 与成本效率
 
-以典型的 50 次工具调用的会话为例：
+以典型的 50 次工具调用的会话为例（成本模型示意 —— 下列比率由批大小、token 量与模型定价**估算**得出，并非端到端实测）：
 
-| | claude-mem | claude-mem-lite | 比率 |
+| | claude-mem | claude-mem-lite | 比率（估算） |
 |---|---|---|---|
-| LLM 调用次数 | ~50（每次工具使用） | ~5-8（按 episode） | **减少 7-10 倍** |
-| 每次调用 token | 1,000-5,000（原始 JSON + 历史） | 200-500（仅摘要） | **减少 5-10 倍** |
-| 总 token 量 | ~100K-250K | ~1K-4K | **减少 50-100 倍** |
-| 模型成本 | Sonnet ($3/$15 每百万) | Haiku ($0.25/$1.25 每百万) | **便宜 12 倍** |
-| 综合节省 | | | **成本降低 600 倍+** |
+| LLM 调用次数 | ~50（每次工具使用） | ~5-8（按 episode） | **约减少 7-10 倍** |
+| 每次调用 token | 1,000-5,000（原始 JSON + 历史） | 200-500（仅摘要） | **约减少 5-10 倍** |
+| 总 token 量 | ~100K-250K | ~1K-4K | **约减少 50-100 倍** |
+| 模型成本 | Sonnet ($3/$15 每百万) | Haiku ($0.25/$1.25 每百万) | **约便宜 12 倍** |
+| 综合节省 | | | **成本降低约 600 倍（估算）** |
 
 ### 质量对比
 

package/haiku-client.mjs

@@ -20,6 +20,14 @@ const MODEL_MAP = {
   sonnet: 'claude-sonnet-4-5-20250929',
 };
 
+// Every background LLM call here is fixed-schema extraction / classification
+// (episode→JSON, type/merge classification, synonym + metadata extraction) whose
+// output is consumed deterministically (JSON.parse, MinHash dedup). Pin temperature
+// to 0 so the provider default (~1.0) doesn't inject wording variance that breaks
+// JSON parsing or defeats the wording-sensitive MinHash near-duplicate detector.
+// A call that genuinely needs sampling can pass opts.temperature to override.
+const DEFAULT_LLM_TEMPERATURE = 0;
+
 /**
  * Resolve the LLM model to use for background calls.
  * Reads CLAUDE_MEM_MODEL env var, defaults to 'haiku'.
@@ -143,7 +151,7 @@ export function flattenForCLI(input) {
  * @param {number} [opts.maxTokens=500] Max tokens in response
  * @returns {Promise<{text: string}|null>} Response or null on failure
  */
-export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500 } = {}) {
+export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500, temperature = DEFAULT_LLM_TEMPERATURE } = {}) {
   if (!prompt) return null;
 
   const mode = detectMode();
@@ -160,8 +168,8 @@ export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500 } = {
   let primary = null;
   try {
     primary = mode === 'api'
-      ? await callHaikuAPI(prompt, { timeout, maxTokens })
-      : await callOpenRouterAPI(prompt, resolveModel().cli, { timeout, maxTokens });
+      ? await callHaikuAPI(prompt, { timeout, maxTokens, temperature })
+      : await callOpenRouterAPI(prompt, resolveModel().cli, { timeout, maxTokens, temperature });
   } catch (e) {
     debugCatch(e, `callHaiku:${mode}`);
   }
@@ -198,7 +206,7 @@ export async function callHaikuJSON(prompt, opts) {
  * @param {number} [opts.maxTokens=1000] Max tokens in response
  * @returns {Promise<{text: string}|null>} Response or null on failure
  */
-export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 15000, maxTokens = 1000 } = {}) {
+export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 15000, maxTokens = 1000, temperature = DEFAULT_LLM_TEMPERATURE } = {}) {
   if (!prompt) return null;
   const resolvedModel = MODEL_MAP[model] ? model : 'haiku';
   const mode = detectMode();
@@ -214,8 +222,8 @@ export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 1500
   let primary = null;
   try {
     primary = mode === 'api'
-      ? await callModelAPI(prompt, resolvedModel, { timeout, maxTokens })
-      : await callOpenRouterAPI(prompt, resolvedModel, { timeout, maxTokens });
+      ? await callModelAPI(prompt, resolvedModel, { timeout, maxTokens, temperature })
+      : await callOpenRouterAPI(prompt, resolvedModel, { timeout, maxTokens, temperature });
   } catch (e) {
     debugCatch(e, `callLLMWithModel:${mode}:${resolvedModel}`);
   }
@@ -239,7 +247,7 @@ export async function callModelJSON(prompt, model = 'haiku', opts) {
   return parseJsonFromLLM(result.text);
 }
 
-async function callModelAPI(prompt, model, { timeout, maxTokens }) {
+async function callModelAPI(prompt, model, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) return null;
 
@@ -252,6 +260,7 @@ async function callModelAPI(prompt, model, { timeout, maxTokens }) {
     const body = {
       model: modelId,
       max_tokens: maxTokens,
+      temperature,
       messages: [{ role: 'user', content: user }],
     };
     // System slot is constant per call type (instructions, schema, type taxonomy)
@@ -312,7 +321,7 @@ function callModelCLI(prompt, model, { timeout }) {
 
 // ─── API Mode ────────────────────────────────────────────────────────────────
 
-async function callHaikuAPI(prompt, { timeout, maxTokens }) {
+async function callHaikuAPI(prompt, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) return null;
 
@@ -325,6 +334,7 @@ async function callHaikuAPI(prompt, { timeout, maxTokens }) {
     const body = {
       model: modelId,
       max_tokens: maxTokens,
+      temperature,
       messages: [{ role: 'user', content: user }],
     };
     // See callModelAPI: cache_control on the constant system slot.
@@ -365,7 +375,7 @@ async function callHaikuAPI(prompt, { timeout, maxTokens }) {
 // `cache_control` field has no OpenAI-format equivalent and is omitted.
 // `tier` is the resolved model tier ('haiku'|'sonnet'); OPENROUTER_MODEL can
 // override the resulting slug entirely (see resolveOpenRouterModel).
-async function callOpenRouterAPI(prompt, tier, { timeout, maxTokens }) {
+async function callOpenRouterAPI(prompt, tier, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
   const apiKey = process.env.OPENROUTER_API_KEY;
   if (!apiKey) return null;
 
@@ -387,7 +397,7 @@ async function callOpenRouterAPI(prompt, tier, { timeout, maxTokens }) {
         // Optional OpenRouter attribution headers (ignored by the API if absent).
         'X-Title': 'claude-mem-lite',
       },
-      body: JSON.stringify({ model, max_tokens: maxTokens, messages }),
+      body: JSON.stringify({ model, max_tokens: maxTokens, temperature, messages }),
       signal: controller.signal,
     });
 

package/hook-llm.mjs

@@ -12,6 +12,7 @@ import {
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector } from './tfidf.mjs';
+import { DEDUP_JACCARD_THRESHOLD, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
   sessionFile, getSessionId, openDb, callLLM, sleep,
@@ -148,7 +149,7 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       ORDER BY created_at_epoch DESC LIMIT 10
     `).all(project, fiveMinAgo);
 
-    if (obs.title && recent.some(r => jaccardSimilarity(r.title, obs.title) > 0.7)) {
+    if (obs.title && recent.some(r => jaccardSimilarity(r.title, obs.title) > DEDUP_JACCARD_THRESHOLD)) {
       return null; // dedup: Jaccard title match
     }
 
@@ -173,8 +174,8 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
         WHERE project = ? AND created_at_epoch > ? AND created_at_epoch <= ?
         ORDER BY created_at_epoch DESC LIMIT 60
       `).all(project, threeDaysAgo, fiveMinAgo);
-      if (extRecent.some(r => jaccardSimilarity(r.title, obs.title) > 0.85)) {
-        return null; // dedup: low-signal Jaccard match
+      if (extRecent.some(r => jaccardSimilarity(r.title, obs.title) > AUTO_MERGE_THRESHOLD)) {
+        return null; // dedup: low-signal Jaccard match (stricter cutoff for degraded titles)
       }
     }
 

package/hook-optimize.mjs

@@ -13,6 +13,7 @@ import { callModelJSON } from './haiku-client.mjs';
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector, cosineSimilarity } from './tfidf.mjs';
+import { MERGE_JACCARD_LOW, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { DB_DIR } from './schema.mjs';
 
 const RUNTIME_DIR = join(DB_DIR, 'runtime');
@@ -331,8 +332,9 @@ export async function executeNormalize(db, force = false, { project } = {}) {
 // ─── Task 3: Cluster-merge ─────────────────────────────────────────────────
 
 const MERGE_TIME_WINDOW_MS = 30 * 86400000;
-const MERGE_JACCARD_LOW = 0.4;
-const MERGE_JACCARD_HIGH = 0.85;
+// Merge-review band [MERGE_JACCARD_LOW, AUTO_MERGE_THRESHOLD): titles in this
+// Jaccard range are LLM-reviewed for merge; at/above AUTO_MERGE_THRESHOLD they'd
+// already auto-merge elsewhere, below MERGE_JACCARD_LOW they're too dissimilar.
 
 export function findMergeCandidates(db, maxClusters = 5, { project } = {}) {
   const cutoff = Date.now() - MERGE_TIME_WINDOW_MS;
@@ -363,12 +365,14 @@ export function findMergeCandidates(db, maxClusters = 5, { project } = {}) {
       if (Math.abs(rows[i].created_at_epoch - rows[j].created_at_epoch) > MERGE_TIME_WINDOW_MS) continue;
 
       if (rows[i].minhash_sig && rows[j].minhash_sig) {
+        // 0.8 slack: the MinHash estimate is noisy, so pre-filter a band below
+        // MERGE_JACCARD_LOW rather than at it, to avoid dropping true candidates.
         const est = estimateJaccardFromMinHash(rows[i].minhash_sig, rows[j].minhash_sig);
         if (est < MERGE_JACCARD_LOW * 0.8) continue;
       }
 
       const titleSim = jaccardSimilarity(rows[i].title, rows[j].title);
-      if (titleSim >= MERGE_JACCARD_LOW && titleSim < MERGE_JACCARD_HIGH) {
+      if (titleSim >= MERGE_JACCARD_LOW && titleSim < AUTO_MERGE_THRESHOLD) {
         cluster.push(rows[j]);
         used.add(rows[j].id);
       }

package/hook.mjs

@@ -63,7 +63,8 @@ import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-
 import { handleLLMOptimize } from './hook-optimize.mjs';
 import { silentAutoAdopt, hasAutoAdoptMarker } from './adopt-cli.mjs';
 import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
-import { loadCiteBackForEpisode, buildUnsavedBugfixHint, countUnsavedBugfixShape, buildCiteRecallNudge as libBuildCiteRecallNudge, nextCiteLowStreak } from './lib/cite-back-hint.mjs';
+import { loadCiteBackForEpisode, extractCiteBackSignals, buildUnsavedBugfixHint, countUnsavedBugfixShape, buildCiteRecallNudge as libBuildCiteRecallNudge, nextCiteLowStreak } from './lib/cite-back-hint.mjs';
+import { MINHASH_PREFILTER, FUZZY_DEDUP_THRESHOLD } from './lib/dedup-constants.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
 // crash on static import. Degrade gracefully to no-op when the module is absent.
@@ -542,6 +543,12 @@ async function handleStop() {
           // contract test in tests/citation-tracker-userprompt.test.mjs covers it.
           try {
             const injected = extractAllInjected(transcriptPath);
+            // P5 ①: cite-back signals — observations whose warned file the agent
+            // edited this session. Union into injected so they're resolved (they
+            // were injected via pre-tool-recall) and, below, into cited so the
+            // edit promotes them even without a literal #NN in text.
+            const citeBackIds = extractCiteBackSignals(transcriptPath);
+            for (const id of citeBackIds) injected.add(id);
             if (injected.size > 0) {
               // Text-floor gate: skip decay on tool-only Stops. Without this,
               // a turn that ends on tool_use locks every injected obs as
@@ -554,6 +561,7 @@ async function handleStop() {
                 debugLog('DEBUG', 'handleStop', `citation-decay: skipped (no main-thread assistant text yet, injected=${injected.size})`);
               } else {
                 const citedMain = extractCitationsFromTranscript(transcriptPath, { mainOnly: true });
+                for (const id of citeBackIds) citedMain.add(id);
                 const r = applyCitationDecay(db, project, injected, citedMain, sessionId);
                 debugLog('DEBUG', 'handleStop', `citation-decay: touched=${r.touched} promoted=${r.promoted} demoted=${r.demoted}`);
               }
@@ -864,8 +872,6 @@ async function handleSessionStart() {
         if (!process.env.CLAUDE_MEM_SKIP_AUTO_DEDUP_FUZZY) {
           const SCAN_LIMIT = 500;
           const FUZZY_MAX_MERGES = 20;
-          const FUZZY_THRESHOLD = 0.95;
-          const MINHASH_PREFILTER = 0.7;
           const recent = db.prepare(`
             SELECT id, title, importance, created_at_epoch
             FROM observations
@@ -885,7 +891,7 @@ async function handleSessionStart() {
               for (let j = i + 1; j < recent.length; j++) {
                 if (!minhashes[j] || removed.has(recent[j].id)) continue;
                 if (estimateJaccardFromMinHash(minhashes[i], minhashes[j]) < MINHASH_PREFILTER) continue;
-                if (jaccardSimilarity(titles[i], titles[j]) < FUZZY_THRESHOLD) continue;
+                if (jaccardSimilarity(titles[i], titles[j]) < FUZZY_DEDUP_THRESHOLD) continue;
                 // Keep the higher-importance row; tiebreak by older (lower id wins access history)
                 const keep = (recent[i].importance ?? 1) >= (recent[j].importance ?? 1) ? recent[i] : recent[j];
                 const remove = keep === recent[i] ? recent[j] : recent[i];

package/lib/citation-tracker.mjs

@@ -387,6 +387,42 @@ const IMPORTANCE_CAP = 3;
 const IMPORTANCE_FLOOR = 0;
 const UNCITED_STREAK_THRESHOLD = 3;
 
+// Adoption-rate gate (P5 ②). A project's cite-rate is SUM(cited_count) /
+// SUM(decay_seen_count) over its non-superseded observations: of every decay
+// resolution this project has ever produced, what fraction were citations.
+// Below ADOPTION_THRESHOLD with at least ADOPTION_MIN_SEEN resolutions on record,
+// the project has demonstrably not adopted the #NN convention, so we suppress
+// DEMOTION (never promotion) — see the construct-validity note on
+// applyCitationDecay. MIN_SEEN keeps the gate dormant for low-data projects so
+// the established behavior is preserved until there's enough signal to judge.
+const ADOPTION_THRESHOLD = 0.02;
+const ADOPTION_MIN_SEEN = 8;
+
+/**
+ * Compute a project's citation-adoption snapshot: total citations vs total decay
+ * resolutions on record, and their ratio. Read-only; safe to call before the
+ * decay transaction (the gate decision is made on the pre-mutation snapshot).
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} project
+ * @returns {{cited: number, seen: number, rate: number}}
+ */
+export function computeCitationAdoption(db, project) {
+  const empty = { cited: 0, seen: 0, rate: 0 };
+  if (!db || !project) return empty;
+  try {
+    const row = db.prepare(`
+      SELECT COALESCE(SUM(cited_count), 0)       AS cited,
+             COALESCE(SUM(decay_seen_count), 0)  AS seen
+        FROM observations
+       WHERE project = ? AND superseded_at IS NULL
+    `).get(project);
+    const cited = row?.cited || 0;
+    const seen = row?.seen || 0;
+    return { cited, seen, rate: seen > 0 ? cited / seen : 0 };
+  } catch (e) { debugCatch(e, 'computeCitationAdoption'); return empty; }
+}
+
 /**
  * Apply the citation-feedback loop for one session: for each injected obs id,
  * decide cited vs uncited and mutate importance/streak/cited_count per spec.
@@ -398,6 +434,20 @@ const UNCITED_STREAK_THRESHOLD = 3;
  * - cross-project IDs are silently ignored by the WHERE clause.
  * - MEM_DISABLE_CITATION_DECAY=1 disables all writes; returns zeros.
  *
+ * CONSTRUCT-VALIDITY ASSUMPTION (P5): a "citation" is operationally two signals,
+ * neither of which is ground-truth behavioral impact:
+ *   1. the literal `#NN` token appears in main-thread assistant text (citedIds), and
+ *   2. (cite-back) the agent edited a file a prior lesson #NN had warned about —
+ *      unioned into citedIds by the Stop handler before this call.
+ * Signal 2 was added because signal 1 alone penalizes projects that act on a
+ * lesson without typing its id. Even so, both are proxies. For a project that has
+ * never cited anything (cite-rate below ADOPTION_THRESHOLD over ≥ADOPTION_MIN_SEEN
+ * resolutions), demotion is suppressed: absent any positive signal we cannot
+ * distinguish "useless lesson" from "useful lesson in a project that doesn't use
+ * the #NN convention," and a false demotion is the costlier error. The gate trades
+ * missed demotions (stale lessons linger) for avoided false demotions. Promotion
+ * is never gated — a single citation lifts the project's rate and re-enables decay.
+ *
  * @param {import('better-sqlite3').Database} db
  * @param {string} project
  * @param {Set<number>|Iterable<number>} injectedIds
@@ -413,6 +463,13 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   if (injected.size === 0) return empty;
   const cited = citedIds instanceof Set ? citedIds : new Set(citedIds || []);
 
+  // Adoption gate (snapshot taken before any mutation this run). Suppress only
+  // demotion; promotion always proceeds. Threshold overridable via env.
+  const adoption = computeCitationAdoption(db, project);
+  const envThreshold = Number.parseFloat(process.env.CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD);
+  const adoptionThreshold = Number.isFinite(envThreshold) && envThreshold >= 0 ? envThreshold : ADOPTION_THRESHOLD;
+  const suppressDemotion = adoption.seen >= ADOPTION_MIN_SEEN && adoption.rate < adoptionThreshold;
+
   const selectStmt = db.prepare(
     'SELECT id, importance, uncited_streak, last_decided_session_id FROM observations WHERE id = ? AND project = ?'
   );
@@ -457,7 +514,10 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
         promoted++;
       } else {
         const nextStreak = (row.uncited_streak || 0) + 1;
-        if (nextStreak >= UNCITED_STREAK_THRESHOLD) {
+        // Demote only when the streak is up AND the project has demonstrably
+        // adopted citations. A non-adopting project advances the streak (idempotent
+        // bookkeeping) but never loses importance — see construct-validity note.
+        if (nextStreak >= UNCITED_STREAK_THRESHOLD && !suppressDemotion) {
           updateDemote.run(IMPORTANCE_FLOOR, sessionId, Date.now(), id);
           demoted++;
         } else {

package/lib/cite-back-hint.mjs

@@ -17,6 +17,11 @@ import { EDIT_TOOLS } from '../utils.mjs';
 
 const MAX_FILES = 2;
 
+// Leader literal for the cite-back hint. Shared by the builder (below) and the
+// Stop-time signal extractor (extractCiteBackSignals) so the two can never drift
+// — the extractor finds hint emissions by this exact prefix.
+const CITE_BACK_HINT_LEADER = '[mem] ⚠ Cite-back:';
+
 export function buildCiteBackHint(episode, cooldown) {
   if (!episode || !cooldown) return null;
   const entries = episode.entries;
@@ -48,7 +53,7 @@ export function buildCiteBackHint(episode, cooldown) {
   // numeric framing is measurably harder to dismiss than a hedged hint.
   const totalLessons = matches.reduce((sum, m) => sum + m.ids.length, 0);
   const lines = [
-    `[mem] ⚠ Cite-back: edited ${matches.length} file(s) with ${totalLessons} prior lesson(s) this session. Save now if any was the root cause:`,
+    `${CITE_BACK_HINT_LEADER} edited ${matches.length} file(s) with ${totalLessons} prior lesson(s) this session. Save now if any was the root cause:`,
   ];
   for (const m of matches) {
     const fname = basename(m.file);
@@ -242,3 +247,36 @@ export function loadCiteBackForEpisode(episode, runtimeDir) {
   }
   return buildCiteBackHint(episode, cooldown);
 }
+
+// ─── extractCiteBackSignals (P5 ①) ──────────────────────────────────────────
+// Stop-time positive-citation signal. Scans the transcript for cite-back hint
+// emissions (PostToolUse attachment.stdout carrying CITE_BACK_HINT_LEADER — the
+// same source countUnsavedBugfixShape reads) and collects the `#NN` lesson ids
+// they name. Each id is an observation whose warned file the agent actually
+// EDITED this session — a behavioral citation even when the agent never typed
+// #NN. The Stop handler unions these into the cited set passed to
+// applyCitationDecay (lib/citation-tracker.mjs), so acting on a lesson promotes
+// it and lifts the project's adoption rate. Returns an empty set on missing path.
+const CITE_BACK_ID_RE = /#(\d{1,7})\b/g;
+
+export function extractCiteBackSignals(transcriptPath) {
+  const ids = new Set();
+  if (!transcriptPath || !existsSync(transcriptPath)) return ids;
+  let raw;
+  try { raw = readFileSync(transcriptPath, 'utf8'); } catch { return ids; }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (entry.type !== 'attachment') continue;
+    const stdout = entry.attachment?.stdout || '';
+    if (!stdout.includes(CITE_BACK_HINT_LEADER)) continue;
+    CITE_BACK_ID_RE.lastIndex = 0;
+    let m;
+    while ((m = CITE_BACK_ID_RE.exec(stdout))) {
+      const id = Number(m[1]);
+      if (Number.isInteger(id) && id > 0 && id < 1e7) ids.add(id);
+    }
+  }
+  return ids;
+}

package/lib/compress-core.mjs

@@ -10,11 +10,15 @@
 // granularity (CLI/MCP wrap all groups in one transaction; the hook transacts
 // each group). They no longer re-implement the mutation.
 //
-// NOTE: the summary INSERT still omits the observation_vectors write, matching
-// pre-extraction behavior. Fixing that (audit P5) is now a single change here
-// instead of three — but it is a behavior change, intentionally NOT bundled.
+// The summary INSERT also writes its TF-IDF observation_vectors row in the same
+// (caller-owned) transaction — fixed once here rather than in all three call
+// sites. Without it, FTS-miss queries that fall back to vector recall (CJK /
+// concept / paraphrase) could never reach compressed summaries; the LLM
+// smart-compress path already wrote vectors, so the deterministic path was the
+// sole gap (audit P6).
 
-import { isoWeekKey, COMPRESSED_AUTO } from '../utils.mjs';
+import { isoWeekKey, COMPRESSED_AUTO, debugCatch } from '../utils.mjs';
+import { getVocabulary, computeVector } from '../tfidf.mjs';
 import { scrubRecord } from './scrub-record.mjs';
 
 /**
@@ -90,6 +94,22 @@ export function compressGroup(db, proj, obs) {
   `).run(sessionId, proj, safe.text, dominantType, safe.title, safe.narrative, medianDate.toISOString(), medianEpoch);
   const summaryId = Number(summaryResult.lastInsertRowid);
 
+  // TF-IDF vector for the summary so it is reachable by vector recall (parity
+  // with save-observation.mjs and the LLM smart-compress path). Best-effort:
+  // vocab may be uninitialized on a fresh DB — a failure here must not abort the
+  // compression the caller is transacting.
+  try {
+    const vocab = getVocabulary(db);
+    if (vocab) {
+      const vec = computeVector(`${safe.title} ${safe.narrative}`, vocab);
+      if (vec) {
+        db.prepare(
+          'INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)'
+        ).run(summaryId, Buffer.from(vec.buffer), vocab.version, medianEpoch);
+      }
+    }
+  } catch (e) { debugCatch(e, 'compress-vector'); }
+
   const obsIds = obs.map((o) => o.id);
   const obsPh = obsIds.map(() => '?').join(',');
   db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${obsPh})`).run(summaryId, ...obsIds);

package/lib/dedup-constants.mjs

@@ -0,0 +1,35 @@
+// Dedup / merge similarity thresholds — single source of truth (P10).
+//
+// All values are Jaccard-space (word-set overlap, 0..1) unless noted. They were
+// scattered as bare literals and duplicate local consts across save-observation,
+// maintain-core, hook-llm, hook-optimize, mem-cli, server, and hook; converging
+// them here removes the drift risk and gives the P7 benchmark named knobs.
+// Vector-side constants (VOCAB_DIM / MIN_COSINE_SIMILARITY / RRF_K) deliberately
+// stay in tfidf.mjs next to the search engine that consumes them.
+//
+// Pure constants only — no imports, so nothing can import-cycle through this.
+
+// 0.7: near-duplicate cutoff for save-time dedup (5-min window, lib/save-observation)
+// and the hook-llm tier-1 title dedup. Catches "Modified X" / "Fixed X" restatements
+// (~70% word overlap) without collapsing distinct-but-related observations.
+export const DEDUP_JACCARD_THRESHOLD = 0.7;
+
+// 0.85: high-confidence auto-merge cutoff (maintain + optimize cluster-merge, CLI/MCP
+// dedup preview). Pairs at or above this merge without an LLM merge-decision call.
+export const AUTO_MERGE_THRESHOLD = 0.85;
+
+// 0.4: low bound of the LLM-review merge band [0.4, 0.85) in hook-optimize. Below it,
+// a pair is too dissimilar to be worth a merge-decision call.
+export const MERGE_JACCARD_LOW = 0.4;
+
+// 0.5: MinHash estimated-Jaccard pre-filter for the maintain O(n²) scan — skip the
+// exact-Jaccard compare when the cheap signature estimate is already below this.
+export const MINHASH_PRE_THRESHOLD = 0.5;
+
+// 0.7: MinHash pre-filter for the hook post-inject fuzzy-dedup pass. Stricter than
+// maintain's 0.5 to keep the inline inject path cheap (it runs in the hot Stop path).
+export const MINHASH_PREFILTER = 0.7;
+
+// 0.95: strict title-Jaccard cutoff for the hook post-inject fuzzy-dedup pass — only
+// collapse near-identical titles inline; anything softer waits for the maintain sweep.
+export const FUZZY_DEDUP_THRESHOLD = 0.95;

package/lib/maintain-core.mjs

@@ -14,13 +14,16 @@
 
 import { COMPRESSED_PENDING_PURGE, computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from '../utils.mjs';
 import { rebuildVocabulary, computeVector, _resetVocabCache } from '../tfidf.mjs';
+import { DEDUP_JACCARD_THRESHOLD, MINHASH_PRE_THRESHOLD as MINHASH_PRE_THRESHOLD_SRC } from './dedup-constants.mjs';
 
 export const STALE_AGE_MS = 30 * 86400000;
 export const OP_CAP = 1000;
 export const SCAN_LIMIT = 500;
 export const DUPLICATE_LIMIT = 50;
-export const SIMILARITY_THRESHOLD = 0.7;
-export const MINHASH_PRE_THRESHOLD = 0.5;
+// Back-compat: maintain-core historically exported these names; both now source
+// their value from the single canonical lib/dedup-constants.mjs.
+export const SIMILARITY_THRESHOLD = DEDUP_JACCARD_THRESHOLD;
+export const MINHASH_PRE_THRESHOLD = MINHASH_PRE_THRESHOLD_SRC;
 // A memory injected this many times with zero citations is "pinned noise" that
 // the regular decay op can't touch (decay protects injection_count>0).
 export const PINNED_INJ_THRESHOLD = 8;

package/lib/save-observation.mjs

@@ -13,10 +13,10 @@
 
 import { jaccardSimilarity, scrubSecrets, computeMinHash, cjkBigrams, getCurrentBranch, debugCatch } from '../utils.mjs';
 import { getVocabulary, computeVector } from '../tfidf.mjs';
+import { DEDUP_JACCARD_THRESHOLD } from './dedup-constants.mjs';
 
 const DEDUP_WINDOW_MS = 5 * 60 * 1000;
 const DEDUP_RECENT_LIMIT = 50;
-const DEDUP_JACCARD_THRESHOLD = 0.7;
 
 /**
  * Save a new observation if it isn't a near-duplicate of one saved within the

package/mem-cli.mjs

@@ -34,6 +34,7 @@ import { readFileSync, existsSync, readdirSync } from 'fs';
 // move each cmdXxx into its own cli/<cmd>.mjs; mem-cli.mjs becomes pure dispatch.
 import { parseArgs, out, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints } from './cli/common.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
+import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
@@ -1845,7 +1846,6 @@ function cmdMaintain(db, args) {
     out(`  Pinned-but-uncited (inj>=${PINNED_INJ_THRESHOLD}, cited=0, imp>1): ${stats.pinned} — run: maintain execute --ops demote_pinned`);
     out(`  Pending purge: ${stats.pendingPurge} (compressed originals awaiting cleanup)`);
     if (duplicates.length > 0) {
-      const AUTO_MERGE_THRESHOLD = 0.85;
       const autoMergeable = duplicates.filter(d => parseFloat(d.similarity) >= AUTO_MERGE_THRESHOLD);
       const manualReview = duplicates.filter(d => parseFloat(d.similarity) < AUTO_MERGE_THRESHOLD);
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.88.0",
-  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. Alternative to claude-mem with 600x lower cost.",
+  "version": "2.89.0",
+  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",
   "engines": {
@@ -69,6 +69,7 @@
     "lib/save-observation.mjs",
     "lib/compress-core.mjs",
     "lib/maintain-core.mjs",
+    "lib/dedup-constants.mjs",
     "lib/deferred-work.mjs",
     "lib/upgrade-banner.mjs",
     "lib/scrub-record.mjs",

package/schema.mjs

@@ -54,7 +54,14 @@ export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
 // re-runs the v28 observation_vectors cleanup) to clear the backlog leaked while
 // the warm-start fast-path left foreign_keys OFF. LATEST_MIGRATION_COLUMN is
 // unchanged (no new column) — decay_seen_count still exists at v35.
-export const CURRENT_SCHEMA_VERSION = 35;
+// v36 (v2.89.0): no DDL — narrows events_fts_au to `AFTER UPDATE OF title, body`.
+// The events FTS triggers (v2.31) were hand-written inline and inherited the
+// pre-v27 broad `AFTER UPDATE ON events` form, so every importance / accessed_count
+// / citation-decay bump thrashed events_fts (delete+reinsert) and reintroduced the
+// SQLITE_CORRUPT_VTAB blast radius v27 fixed for the other FTS tables. Version
+// bumped to force one migration pass; the conditional drop below replaces the
+// legacy trigger on existing DBs. LATEST_MIGRATION_COLUMN unchanged (no new column).
+export const CURRENT_SCHEMA_VERSION = 36;
 
 // Sentinel column for the LATEST migration set. The fast-path uses this to
 // self-heal half-migrated DBs — schema_version bumped but column ALTERs rolled
@@ -399,6 +406,20 @@ export function initSchema(db) {
     }
   } catch { /* non-critical */ }
 
+  // v36 migration: narrow events_fts_au like the v27 fix above. The events FTS
+  // triggers were hand-written inline (below) rather than via ensureFTS, so
+  // events_fts_au inherited the broad `AFTER UPDATE ON events` form and fires on
+  // every non-indexed bump (importance / accessed_count / citation-decay). Drop
+  // the legacy trigger when its stored DDL lacks the scoped `UPDATE OF` clause so
+  // the CREATE TRIGGER IF NOT EXISTS below reinstates the scoped form (handles
+  // re-run + fresh-DB: undefined row on a fresh DB is a no-op).
+  try {
+    const row = db.prepare(`SELECT sql FROM sqlite_master WHERE type='trigger' AND name='events_fts_au'`).get();
+    if (row && row.sql && !/\bAFTER\s+UPDATE\s+OF\s+/i.test(row.sql)) {
+      db.exec(`DROP TRIGGER IF EXISTS events_fts_au`);
+    }
+  } catch { /* non-critical — recreated below */ }
+
   // ─── v2.31 T6: events table + FTS5 (activity namespace) ───────────────────
   // Independent namespace for bugfix/lesson/bug/discovery/refactor/feature/
   // observation/decision types. Isolated from observations to avoid polluting
@@ -443,7 +464,9 @@ export function initSchema(db) {
       VALUES ('delete', old.id, COALESCE(old.title,''), COALESCE(old.body,''), old.event_type, old.project);
     END;
 
-    CREATE TRIGGER IF NOT EXISTS events_fts_au AFTER UPDATE ON events BEGIN
+    -- v36: scoped to title, body (the FTS-indexed columns) so non-indexed bumps
+    -- (importance / accessed_count / citation-decay) no longer thrash events_fts.
+    CREATE TRIGGER IF NOT EXISTS events_fts_au AFTER UPDATE OF title, body ON events BEGIN
       INSERT INTO events_fts(events_fts, rowid, title, body, event_type, project)
       VALUES ('delete', old.id, COALESCE(old.title,''), COALESCE(old.body,''), old.event_type, old.project);
       INSERT INTO events_fts(rowid, title, body, event_type, project)

package/search-engine.mjs

@@ -257,11 +257,12 @@ export function searchObservationsHybrid(db, ctx) {
       project: args.project ?? null,
       type: args.obs_type ?? null,
       vocabVersion: vocab.version,
+      minCosine: ctx.minCosine,   // undefined → MIN_COSINE_SIMILARITY (benchmark sweep override)
     });
     if (vecResults.length === 0) return results;
 
     if (results.length > 0) {
-      const rrfRanking = rrfMerge(results, vecResults);
+      const rrfRanking = rrfMerge(results, vecResults, ctx.rrfK);  // undefined → RRF_K
       const resultMap = new Map(results.map(r => [r.id, r]));
       for (const vr of vecResults) {
         if (!resultMap.has(vr.id)) {

package/server.mjs

@@ -36,6 +36,7 @@ import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { probeOtherSources as probeIdSources, parseIdToken, bucketIdTokens } from './lib/id-routing.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
+import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
   resolveDeferredIds, closeDeferredItems,
@@ -1250,7 +1251,6 @@ server.registerTool(
         `  Pending purge (idle-marked): ${stats.pendingPurge}`,
       ];
       if (duplicates.length > 0) {
-        const AUTO_MERGE_THRESHOLD = 0.85;
         const autoMergeable = duplicates.filter(d => parseFloat(d.similarity) >= AUTO_MERGE_THRESHOLD);
         const manualReview = duplicates.filter(d => parseFloat(d.similarity) < AUTO_MERGE_THRESHOLD);
 

package/source-files.mjs

@@ -86,6 +86,11 @@ export const SOURCE_FILES = [
   // Statically imported by mem-cli.mjs (cmdMaintain), server.mjs (mem_maintain),
   // and hook.mjs (handleAutoMaintain) — missing it would break maintain on auto-update.
   'lib/maintain-core.mjs',
+  // P10 dedup/merge threshold constants — single source of truth for the Jaccard
+  // dedup/merge cutoffs. Statically imported by hook.mjs, hook-llm.mjs,
+  // hook-optimize.mjs, mem-cli.mjs, server.mjs, and the save/maintain cores;
+  // missing it from the manifest would break those paths on auto-update.
+  'lib/dedup-constants.mjs',
   // v2.70 deferred-work: carry-forward TODO primitives. Statically imported by
   // server.mjs (mem_defer family) and mem-cli.mjs (defer subcommand).
   'lib/deferred-work.mjs',

package/tfidf.mjs

@@ -10,6 +10,10 @@ import { createHash } from 'crypto';
 export const VOCAB_DIM = 512;
 export const MIN_COSINE_SIMILARITY = 0.05;
 export const VECTOR_SCAN_LIMIT = 500;
+// Reciprocal Rank Fusion constant. Higher k flattens the rank-position weighting
+// (BM25 and vector lists contribute more equally); lower k lets the top few ranks
+// dominate. 60 is the de-facto RRF default and balances the two retrievers here.
+export const RRF_K = 60;
 
 const VOCAB_STOP_WORDS = new Set([
   ...BASE_STOP_WORDS,
@@ -192,7 +196,7 @@ export function _resetVocabCache() { _vocabCache = null; }
  * @param {object} db - better-sqlite3 database
  * @returns {{ terms: Map<string, {index: number, idf: number}>, version: string, dim: number } | null}
  */
-export function buildVocabulary(db) {
+export function buildVocabulary(db, { dim = VOCAB_DIM } = {}) {
   const rows = db.prepare(`
     SELECT title, narrative, concepts FROM observations
     WHERE COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL
@@ -217,7 +221,7 @@ export function buildVocabulary(db) {
     .filter(([term, freq]) => !isNoiseTerm(term) && freq >= 2)
     .map(([term, freq]) => ({ term, df: freq, idf: idf(freq), ig: freq * idf(freq) }))
     .sort((a, b) => b.ig - a.ig)
-    .slice(0, VOCAB_DIM);
+    .slice(0, dim);
 
   // Build terms map with index and IDF
   const terms = new Map();
@@ -229,7 +233,7 @@ export function buildVocabulary(db) {
   const termList = sortedTerms.map(e => e.term).join(',');
   const version = createHash('md5').update(termList).digest('hex').slice(0, 12);
 
-  const vocab = { terms, version, dim: VOCAB_DIM };
+  const vocab = { terms, version, dim };
   _vocabCache = vocab;
   return vocab;
 }
@@ -239,8 +243,8 @@ export function buildVocabulary(db) {
  * @param {object} db - better-sqlite3 database
  * @returns {object|null} The new vocabulary
  */
-export function rebuildVocabulary(db) {
-  const vocab = buildVocabulary(db);
+export function rebuildVocabulary(db, opts) {
+  const vocab = buildVocabulary(db, opts);
   if (!vocab) return null;
 
   const insertStmt = db.prepare(
@@ -358,7 +362,7 @@ export function cosineSimilarity(a, b) {
 const VECTOR_TIME_WINDOW_MS = 90 * 24 * 60 * 60 * 1000; // 90 days
 const VECTOR_MIN_RESULTS = 50; // fallback to full scan if time-window yields fewer
 
-export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit = VECTOR_SCAN_LIMIT }) {
+export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit = VECTOR_SCAN_LIMIT, minCosine = MIN_COSINE_SIMILARITY }) {
   if (!queryVec) return [];
 
   const now = Date.now();
@@ -403,7 +407,7 @@ export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit
   for (const row of rows) {
     const vec = new Float32Array(row.vector.buffer.slice(row.vector.byteOffset, row.vector.byteOffset + row.vector.byteLength));
     const sim = cosineSimilarity(queryVec, vec);
-    if (sim > MIN_COSINE_SIMILARITY) results.push({ id: row.observation_id, similarity: sim });
+    if (sim > minCosine) results.push({ id: row.observation_id, similarity: sim });
   }
   results.sort((a, b) => b.similarity - a.similarity);
   return results.slice(0, 20);
@@ -418,7 +422,7 @@ export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit
  * @param {number} k - RRF constant (default 60)
  * @returns {{ id: number, rrfScore: number }[]}
  */
-export function rrfMerge(bm25Results, vectorResults, k = 60) {
+export function rrfMerge(bm25Results, vectorResults, k = RRF_K) {
   const scores = new Map();
   bm25Results.forEach((r, i) => {
     scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (k + i + 1));