claude-mem-lite 3.16.2 → 3.17.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.16.2",
+      "version": "3.17.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. 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,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.16.2",
+  "version": "3.17.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/adopt-content.mjs

@@ -43,6 +43,8 @@ PreToolUse hooks already run \`mem_recall\` for past lessons before Read/Edit/Wr
 | Deferring to a future session | \`mem_defer({title, priority:1|2|3, detail})\`; when fixed, add \`closes_deferred=[N]\` to \`mem_save\` |
 | Looking up past work / history | \`mem_search "keywords"\` · \`mem_recent\` · \`mem_timeline\` |
 
+Path cost is round-trips, not milliseconds: the PreToolUse hook above already recalls (0 calls) — prefer it. For an explicit query, if these \`mem_*\` tools are deferred behind ToolSearch this session, the Bash CLI (exact path in the detail doc) is one call vs two (ToolSearch + call).
+
 Full tool + CLI tables, citation/decay rules, and save discipline → \`.claude/plugin_claude_mem_lite.md\``;
 }
 
@@ -77,6 +79,16 @@ PreToolUse hook 在你 Read / Edit / Write 文件前已自动 \`mem_recall\` 该
 \`mem_search\` / \`mem_recent\` / \`mem_recall\` / \`mem_get\` / \`mem_save\` / \`mem_timeline\` +
 \`mem_defer\` / \`mem_defer_list\` / \`mem_defer_drop\`。
 
+### 选 MCP 还是 CLI：按 round-trip,不是执行毫秒
+
+真正的开销是模型往返次数,不是工具执行——暖 MCP 调用 ~25ms、CLI 冷启 ~90ms,在一次推理(秒级)面前都是噪声。按往返次数选路：
+
+1. **被动 hook（0 往返）**：上面的 PreToolUse recall 已自动跑,最快,优先采纳,别重复调。
+2. **CLI via Bash（1 往返）**：工具多的会话里 \`mem_*\` 会被 defer 到 ToolSearch 后面——这时一次 MCP 调用 = ToolSearch + call = **2 往返**,而 Bash 跑一条 CLI 只 **1 往返**。派出去的子 agent 通常也拿不到 \`mem_*\` 工具,CLI 是它唯一的 1-往返路径。用下面「CLI 速查」表里的命令。
+3. **MCP 直调（已加载时 1 往返）**：\`mem_*\` 已在上下文里(未被 defer)就直接调,暖进程执行最快、省掉 ToolSearch。
+
+一句话：能让 hook 代劳就别调；要显式查,若得先 ToolSearch 才能用 \`mem_*\`,改跑 CLI。
+
 | 时机 | 工具 | 关键参数 |
 |------|------|----------|
 | Edit / Write 前 | \`mem_recall\` | \`file="<路径>"\`（hook 通常已代劳） |

package/deep-search.mjs

@@ -34,6 +34,7 @@
 import { searchObservationsHybrid } from './search-engine.mjs';
 import { sanitizeFtsQuery } from './utils.mjs';
 import { RRF_K } from './tfidf.mjs';
+import { rrfAccumulate } from './lib/rrf.mjs';
 import { llmRerankOrder, defaultRerankLLM } from './rerank.mjs';
 
 // original + up to 3 rewrites (keyword / concept-expansion / HyDE).
@@ -350,28 +351,12 @@ export async function rewriteQuery(query, { llm = defaultLLM, retries = 1, cache
  *   match the hybrid path's convention) plus an rrfScore field.
  */
 export function rrfFuseN(rankedLists, k = RRF_K) {
-  const scores = new Map();
-  for (const list of rankedLists) {
-    if (!Array.isArray(list)) continue;
-    list.forEach((r, i) => {
-      if (!r || r.id === undefined || r.id === null) return;
-      const add = 1 / (k + i + 1);
-      const prev = scores.get(r.id);
-      if (prev) {
-        prev.score += add;
-        // Keep the row from the variant that ranked this id HIGHEST (lowest
-        // index). searchObservationsHybrid emits query-dependent fields per
-        // variant (notably the FTS snippet), so first-seen would often show the
-        // weaker original/keyword variant's context; the best-ranked appearance
-        // carries the most relevant snippet/match context (F10).
-        if (i < prev.bestRank) { prev.row = r; prev.bestRank = i; }
-      } else {
-        scores.set(r.id, { row: r, score: add, bestRank: i });
-      }
-    });
-  }
-  return [...scores.values()]
-    .sort((a, b) => b.score - a.score)
+  // Thin N-list adapter over the shared RRF core (lib/rrf.mjs). Emits full source
+  // rows with score = -rrfScore (negative = better, matching the hybrid path's
+  // convention) plus an rrfScore field. rrfAccumulate already keeps each id's
+  // best-ranked row, so query-dependent fields (notably the FTS snippet) come from
+  // the strongest variant rather than first-seen (F10).
+  return rrfAccumulate(rankedLists, k)
     .map(({ row, score }) => ({ ...row, score: -score, rrfScore: score }));
 }
 

package/format-utils.mjs

@@ -24,6 +24,32 @@ export function truncate(str, max = 80) {
   return str.slice(0, end) + '\u2026';
 }
 
+/**
+ * Render the PostToolUse error-recall hint block (hook.mjs::triggerErrorRecall).
+ * The single most-relevant hit (rows[0]) that carries a lesson_learned gets its
+ * lesson INLINED, so the agent can act with zero follow-up round-trips: the old
+ * "pointer + mem_get for details" form cost a deferred mem_get (2 model turns in
+ * tool-heavy sessions, where mem_* is gated behind ToolSearch) at the exact
+ * moment a fix is needed. Later rows stay as #ID pointers to keep the injected
+ * payload bounded (one body, not three). Upstream noise gating (low-signal title
+ * exclusion) is the SELECT's job (see triggerErrorRecall).
+ * @param {Array<{id:number,type:string,title:string,lesson_learned?:string}>} rows
+ * @returns {string} stdout block (trailing newline) or '' when there are no rows
+ */
+export function formatErrorRecallHints(rows) {
+  if (!rows || rows.length === 0) return '';
+  const lines = rows.map((r, i) => {
+    const head = `  #${r.id} [${r.type}] ${truncate(r.title, 60)}`;
+    // Inline the lesson body for the single most-relevant hit only (bounded payload).
+    if (i === 0 && typeof r.lesson_learned === 'string' && r.lesson_learned.trim()) {
+      return `${head} \u2014 ${truncate(r.lesson_learned.trim(), 200)}`;
+    }
+    return head;
+  });
+  const ids = rows.map(r => r.id).join(',');
+  return `[claude-mem-lite] Related memories found for this error:\n${lines.join('\n')}\n  \u2192 Use mem_get(ids=[${ids}]) for details.\n`;
+}
+
 /**
  * Map observation type to its display emoji icon.
  * @param {string} type Observation type (decision, bugfix, feature, etc.)

package/hook-context.mjs

@@ -244,7 +244,10 @@ export function cleanupClaudeMdLegacyBlock() {
 
   if (normalized === content) { dropMarker(); return; }
 
-  const tmp = claudeMdPath + '.mem-tmp';
+  // Per-pid temp suffix so two concurrent first-run SessionStarts in the same
+  // project (e.g. two terminals) can't rename each other's half-written temp
+  // onto the user's tracked CLAUDE.md. Matches the idiom in hook-shared.mjs.
+  const tmp = claudeMdPath + `.mem-tmp-${process.pid}`;
   try {
     writeFileSync(tmp, normalized);
     renameSync(tmp, claudeMdPath);

package/hook-llm.mjs

@@ -740,9 +740,15 @@ ${actionList}`;
           (parsed.type === 'bugfix' || parsed.type === 'decision') &&
           !process.env.CLAUDE_MEM_NO_LESSON_RETRY) {
         retryAttempted = true;
+        // The first callLLM released its slot in the finally above; this lesson
+        // retry is a SECOND LLM call and must re-acquire the semaphore or it
+        // bypasses LLM_SEM_MAX — a burst of bugfix/decision episodes would otherwise
+        // spawn unbounded concurrent Haiku calls. Under contention we skip the retry
+        // rather than exceed the limit (the lesson is an optional enhancement).
+        const retrySlot = await acquireLLMSlot();
         try {
           const retryPrompt = buildLessonRetryPrompt(episode, parsed);
-          const retryRaw = await callLLM(retryPrompt, 10000);
+          const retryRaw = retrySlot ? await callLLM(retryPrompt, 10000) : null;
           if (retryRaw) {
             const retry = parseJsonFromLLM(retryRaw);
             const retryLesson = typeof retry?.lesson === 'string' ? retry.lesson.trim() : '';
@@ -754,6 +760,7 @@ ${actionList}`;
             }
           }
         } catch (e) { debugCatch(e, 'lesson-retry'); }
+        finally { if (retrySlot) releaseLLMSlot(); }
       }
       // v2.57.x B2: persist retry outcome counters. The retry path costs
       // 1 extra Haiku call per bugfix/decision episode; if recovered/attempts

package/hook-memory.mjs

@@ -222,7 +222,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // Count original search terms (AND-separated groups), not expanded synonym tokens.
     const queryTokenCount = ftsQuery.includes(' AND ')
       ? ftsQuery.split(' AND ').length
-      : ftsQuery.split(/\s+/).filter(t => t && !t.startsWith('(') || !t.endsWith(')')).length;
+      : ftsQuery.split(/\s+/).filter(t => t && !t.startsWith('(') && !t.endsWith(')')).length;
     // CJK-dominant queries bypass the token-count gate: a single CJK word becomes
     // 2-N overlapping bigrams (优化召回率 → 优化/召回/回率), inflating
     // queryTokenCount past the gate, so the AND-too-strict query never gets the OR
@@ -385,7 +385,11 @@ export function recallForFile(db, filePath, project) {
     `).all(project, cutoff, filePath, likePattern, MAX_FILE_RECALL);
     const now = Date.now();
     const updateStmt = db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?');
-    for (const r of rows) updateStmt.run(now, r.id);
+    // Per-row try/catch for FTS trigger safety — mirror the injection-bump loop
+    // (searchRelevantMemories) and project_non_obvious.md. Without it, one
+    // SQLITE_CORRUPT_VTAB on the access_count UPDATE trigger throws to the outer
+    // catch and discards the ENTIRE file-recall result set.
+    for (const r of rows) { try { updateStmt.run(now, r.id); } catch {} }
     return rows;
   } catch (e) {
     debugCatch(e, 'recallForFile');

package/hook-semaphore.mjs

@@ -33,8 +33,15 @@ export async function acquireLLMSlot() {
         if (fd !== undefined) closeSync(fd);
       }
     } catch {
-      // Slot file already exists for this PID — stale cleanup should have removed it;
-      // retry and let O_CREAT|O_EXCL succeed on next iteration (avoid non-atomic fallback)
+      // Our own pid-named slot file already exists: a leftover from a prior acquire
+      // that never released (crash between acquire and releaseLLMSlot, or PID reuse).
+      // We are inside acquire and therefore do NOT currently hold a slot, so it is
+      // always stale — remove it and retry. The await is essential: a bare `continue`
+      // here re-hits the same EEXIST every iteration, a synchronous tight loop that
+      // pins a core until the 30s deadline (the age-based cleanup below is unreachable
+      // on this path — it only runs after a successful create).
+      try { unlinkSync(slotFile); } catch {}
+      await sleepMs(50 + Math.random() * 100);
       continue;
     }
 

package/hook.mjs

@@ -26,7 +26,7 @@ import {
   truncate, inferProject, detectBashSignificance,
   extractErrorKeywords, extractFilePaths, isRelatedToEpisode,
   makeEntryDesc, scrubSecrets, stripPrivate, EDIT_TOOLS, debugCatch, debugLog,
-  COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25,
+  COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25, notLowSignalTitleClause, formatErrorRecallHints,
 } from './utils.mjs';
 import {
   readEpisodeRaw, episodeFile,
@@ -363,19 +363,18 @@ function triggerErrorRecall(db, toolInput, response) {
 
     const nowR = Date.now();
     const rows = db.prepare(`
-      SELECT o.id, o.type, o.title
+      SELECT o.id, o.type, o.title, o.lesson_learned
       FROM observations_fts
       JOIN observations o ON observations_fts.rowid = o.id
       WHERE observations_fts MATCH ? AND o.project = ?
+        AND ${notLowSignalTitleClause('o')}
       ORDER BY ${OBS_BM25}
         * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / 1209600000.0))
       LIMIT 3
     `).all(ftsQuery, project, nowR);
 
-    if (rows.length > 0) {
-      const hints = rows.map(r => `  #${r.id} [${r.type}] ${truncate(r.title, 60)}`).join('\n');
-      process.stdout.write(`[claude-mem-lite] Related memories found for this error:\n${hints}\n  → Use mem_get(ids=[${rows.map(r => r.id).join(',')}]) for details.\n`);
-    }
+    const out = formatErrorRecallHints(rows);
+    if (out) process.stdout.write(out);
   } catch (e) { debugCatch(e, 'triggerErrorRecall'); }
 }
 

package/lib/citation-tracker.mjs

@@ -10,7 +10,8 @@
 // column UPDATE including access_count. Per-row UPDATEs wrapped in try-catch
 // to prevent SQLITE_CORRUPT_VTAB cascades from stopping the whole scan.
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
 import { debugCatch } from '../utils.mjs';
 
 // `#123` / `#45678` at a word boundary — matches the CLAUDE.md cite pattern.
@@ -155,6 +156,11 @@ export function bumpCitationAccess(db, ids, project) {
 // Bounded type list mirrors observations.type CHECK + the events table's allowed
 // event_type values these surfaces can emit.
 const INJECTED_RE = /#(\d{1,7})\s+\[(bugfix|decision|change|discovery|feature|refactor|lesson)\]/g;
+// Line-anchored variant: a genuine injected ROW begins (after its short indent) with
+// `#NN [type]`. pre-tool-recall AND error-recall inline a lesson_learned body into the
+// row; a body that quotes another obs ("same as #1234 [decision]") must NOT count as
+// injected: that id would pollute the citation-decay denominator and falsely demote.
+const INJECTED_ROW_RE = new RegExp('^\\s{0,6}' + INJECTED_RE.source);
 
 // Add a numeric obs id to `set` if it parses to a sane in-range positive int.
 function addObsId(set, raw) {
@@ -229,9 +235,10 @@ export function extractInjectedFromPreToolUse(transcriptPath, opts = {}) {
   const ids = new Set();
   eachHookAttachment(transcriptPath, ({ command, text }) => {
     if (!command.includes('pre-tool-recall')) return;
-    INJECTED_RE.lastIndex = 0;
-    let m;
-    while ((m = INJECTED_RE.exec(text))) addObsId(ids, m[1]);
+    for (const line of text.split('\n')) {
+      const m = INJECTED_ROW_RE.exec(line);
+      if (m) addObsId(ids, m[1]);
+    }
   }, opts);
   return ids;
 }
@@ -293,11 +300,14 @@ export function extractInjectedFromErrorRecall(transcriptPath, opts = {}) {
   eachHookAttachment(transcriptPath, ({ command, text }) => {
     if (!command.includes('post-tool-use')) return;
     if (!text.includes('Related memories found for this error')) return;
-    // INJECTED_RE requires `#NN [type]`, so the trailing
-    // `→ Use mem_get(ids=[7933,8455])` line (bare numbers) is not matched.
-    INJECTED_RE.lastIndex = 0;
-    let m;
-    while ((m = INJECTED_RE.exec(text))) addObsId(ids, m[1]);
+    // Per-line anchored: match only a row that STARTS with `#NN [type]` (after its
+    // indent), NOT every such token in the block. The inlined lesson body (v3.16.x)
+    // can quote another obs id, which must not enter the injected set; the trailing
+    // `Use mem_get(ids=[...])` line (bare numbers) is excluded too.
+    for (const line of text.split('\n')) {
+      const m = INJECTED_ROW_RE.exec(line);
+      if (m) addObsId(ids, m[1]);
+    }
   }, opts);
   return ids;
 }
@@ -353,6 +363,72 @@ export function extractAllInjected(transcriptPath, opts = {}) {
   ]);
 }
 
+/**
+ * Cite-recall over ONE transcript file, using the SAME methodology as the
+ * citation-decay loop: injected = extractAllInjected (OUR hook injections only),
+ * cited = #NN in assistant text, ratio = |injected ∩ cited| / |injected|.
+ *
+ * Thread is keyed by FILE LOCATION, not the isSidechain field. Claude Code writes
+ * each subagent's turns to a SEPARATE file (<session>/subagents/agent-*.jsonl),
+ * NOT inline in the parent transcript (verified empirically: 0 isSidechain records
+ * across 60 parent transcripts; the subagent files carry isSidechain=true). So a
+ * whole subagent file IS the sidechain — aggregateProjectCiteRecall splits by path.
+ *
+ * @param {string} transcriptPath
+ * @returns {{injected: number, cited: number, recalled: number, ratio: number}}
+ */
+export function computeThreadCiteRecall(transcriptPath) {
+  const injected = extractAllInjected(transcriptPath);
+  const cited = extractCitationsFromTranscript(transcriptPath);
+  let recalled = 0;
+  for (const id of injected) if (cited.has(id)) recalled++;
+  return {
+    injected: injected.size,
+    cited: cited.size,
+    recalled,
+    ratio: injected.size > 0 ? recalled / injected.size : 0,
+  };
+}
+
+/**
+ * Aggregate cite-recall across a project's transcripts, split MAIN vs SIDECHAIN
+ * by file location. `txDir` = ~/.claude/projects/<encoded>/. Main = the top-level
+ * <session>.jsonl files; sidechain = every <session>/subagents/agent-*.jsonl.
+ * Descends ONE level into the literal `subagents` subdir only — no unbounded
+ * recursion. mtime-gated by `cutoff` (epoch ms; 0 = no window).
+ *
+ * @param {string} txDir
+ * @param {{cutoff?: number}} [opts]
+ * @returns {{main: {injected:number,recalled:number,files:number}, sidechain: {injected:number,recalled:number,files:number,withInjections:number}}}
+ */
+export function aggregateProjectCiteRecall(txDir, { cutoff = 0 } = {}) {
+  const main = { injected: 0, recalled: 0, files: 0 };
+  const sidechain = { injected: 0, recalled: 0, files: 0, withInjections: 0 };
+  const within = (p) => { try { return statSync(p).mtimeMs >= cutoff; } catch { return false; } };
+  let entries;
+  try { entries = readdirSync(txDir, { withFileTypes: true }); } catch { return { main, sidechain }; }
+  for (const ent of entries) {
+    const full = join(txDir, ent.name);
+    if (ent.isFile() && ent.name.endsWith('.jsonl')) {
+      if (!within(full)) continue;
+      const r = computeThreadCiteRecall(full);
+      main.injected += r.injected; main.recalled += r.recalled; main.files++;
+    } else if (ent.isDirectory()) {
+      let subFiles;
+      try { subFiles = readdirSync(join(full, 'subagents')); } catch { continue; }
+      for (const sf of subFiles) {
+        if (!sf.endsWith('.jsonl')) continue;
+        const sp = join(full, 'subagents', sf);
+        if (!within(sp)) continue;
+        const r = computeThreadCiteRecall(sp);
+        sidechain.injected += r.injected; sidechain.recalled += r.recalled; sidechain.files++;
+        if (r.injected > 0) sidechain.withInjections++;
+      }
+    }
+  }
+  return { main, sidechain };
+}
+
 /**
  * True iff the transcript contains at least one non-whitespace text block from
  * a main-thread assistant turn. Gates the citation-decay loop so a tool-only

package/lib/maintain-core.mjs

@@ -13,7 +13,7 @@
 //   { projectFilter: 'AND project = ?' | '', baseParams: [project?] , staleAge, opCap }
 
 import { COMPRESSED_PENDING_PURGE, computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from '../utils.mjs';
-import { rebuildVocabulary, computeVector, _resetVocabCache } from '../tfidf.mjs';
+import { rebuildVocabulary, computeVector, _resetVocabCache, vectorsEnabled } from '../tfidf.mjs';
 import { DEDUP_JACCARD_THRESHOLD, MINHASH_PRE_THRESHOLD as MINHASH_PRE_THRESHOLD_SRC, FUZZY_DEDUP_THRESHOLD, FUZZY_BODY_THRESHOLD, MINHASH_PREFILTER } from './dedup-constants.mjs';
 
 export const STALE_AGE_MS = 30 * 86400000;
@@ -326,6 +326,7 @@ export function maintenanceStats(db, { projectFilter, baseParams, staleAge }) {
 
 /** Rebuild the TF-IDF vocabulary + every active observation vector (own transaction). */
 export function rebuildVectors(db) {
+  if (!vectorsEnabled()) return { ok: false, reason: 'vector arm disabled (set CLAUDE_MEM_VECTORS=1 to re-enable)', updated: 0, total: 0 };
   _resetVocabCache();
   const vocab = rebuildVocabulary(db);
   if (!vocab) return { ok: false, reason: 'no observations to build vocabulary from' };

package/lib/observation-write.mjs

@@ -8,7 +8,7 @@
 // Statement-only: callers own the transaction boundary (both wrap the row + files
 // + vector writes in one db.transaction so a failure can't leave a partial row).
 
-import { getVocabulary, computeVector } from '../tfidf.mjs';
+import { getVocabulary, computeVector, vectorsEnabled } from '../tfidf.mjs';
 import { debugCatch, cjkBigrams } from '../utils.mjs';
 
 // Canonical column order — must mirror the observations schema (schema.mjs).
@@ -56,6 +56,7 @@ export function insertObservationFiles(db, obsId, files) {
  * observation over a missing vector).
  */
 export function insertObservationVector(db, obsId, vecText) {
+  if (!vectorsEnabled()) return;  // Phase-1: vector arm disabled by default (audit 2026-06-27)
   try {
     const vocab = getVocabulary(db);
     if (!vocab) return;

package/lib/rrf.mjs

@@ -0,0 +1,42 @@
+// lib/rrf.mjs — Reciprocal Rank Fusion core (single source of truth, D#42).
+//
+// Both tfidf.rrfMerge (2-list, minimal { id, rrfScore } output) and
+// deep-search.rrfFuseN (N-list, full-row output with best-rank row selection)
+// are thin shape-adapters over rrfAccumulate below. Keeping the scoring math in
+// one dependency-free place prevents the two from silently drifting (different k
+// or formula — the prior state where each had its own hand-written loop). Callers
+// pass their own RRF_K default; 60 is the canonical value.
+
+/**
+ * Core Reciprocal Rank Fusion accumulator. For each id, sums 1/(k + rank + 1)
+ * across every ranked list it appears in, and keeps the source row from the list
+ * where the id ranked highest (lowest index) — query-dependent fields like an FTS
+ * snippet then come from the best-ranked appearance. Callers that only need the id
+ * ignore the row.
+ *
+ * @param {Array<Array<{id:any}>>} rankedLists one entry per ranked list; each list
+ *   is ordered best-first. Non-array entries and rows with null/undefined id are skipped.
+ * @param {number} [k=60] RRF constant.
+ * @returns {Array<{ id:any, row:object, score:number }>} descending by fused score;
+ *   ties preserve first-list-first insertion order (stable sort).
+ */
+export function rrfAccumulate(rankedLists, k = 60) {
+  const scores = new Map();
+  for (const list of rankedLists) {
+    if (!Array.isArray(list)) continue;
+    list.forEach((r, i) => {
+      if (!r || r.id === undefined || r.id === null) return;
+      const add = 1 / (k + i + 1);
+      const prev = scores.get(r.id);
+      if (prev) {
+        prev.score += add;
+        if (i < prev.bestRank) { prev.row = r; prev.bestRank = i; }
+      } else {
+        scores.set(r.id, { row: r, score: add, bestRank: i });
+      }
+    });
+  }
+  return [...scores.values()]
+    .sort((a, b) => b.score - a.score)
+    .map(({ row, score }) => ({ id: row.id, row, score }));
+}

package/mem-cli.mjs

@@ -15,6 +15,7 @@ import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { computeFunnel, formatFunnel, computeSweep, formatSweep, DEFAULT_SWEEP_FLOORS, DEFAULT_SWEEP_MARGINS } from './registry-recommend.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
+import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
@@ -26,8 +27,9 @@ import { buildSessionContextLines } from './hook-context.mjs';
 import { cmdAdopt, cmdUnadopt } from './adopt-cli.mjs';
 import { parseIntFlag, isNumericToken } from './lib/cli-flags.mjs';
 import { auditMemdir, memdirPath } from './memdir.mjs';
+import { aggregateProjectCiteRecall } from './lib/citation-tracker.mjs';
 import { probeOtherSources as probeIdSources, bucketIdTokens } from './lib/id-routing.mjs';
-import { join, sep } from 'path';
+import { join, sep, dirname } from 'path';
 import { readFileSync, existsSync, readdirSync } from 'fs';
 
 // v2.41: shared CLI helpers extracted to cli/common.mjs. Keep this file as the
@@ -1097,6 +1099,18 @@ async function cmdStats(db, args) {
       AND created_at_epoch < ? ${projectFilter}
   `).get(thirtyDaysAgo, ...baseParams);
   const noiseRatio = obsTotal.c > 0 ? lowVal.c / obsTotal.c : 0;
+  // Low-signal-title population: template / tool-log titles (Modified, Worked on,
+  // Error while working, Error:, node/npm/npx …) that the retrieval layer already
+  // filters out by default. The imp=1 "Low-value" metric above structurally can't
+  // see these — they often carry inflated importance and recent access — so the
+  // health gauge under-reports real noise without this line. Same LOW_SIGNAL
+  // pattern source as the read-side filter (lib/low-signal-patterns.mjs).
+  const lowSignalTitle = db.prepare(`
+    SELECT COUNT(*) as c FROM observations
+    WHERE NOT ${buildNotLowSignalSql()}
+      AND COALESCE(compressed_into, 0) = 0 ${projectFilter}
+  `).get(...baseParams);
+  const lowSignalRatio = obsTotal.c > 0 ? lowSignalTitle.c / obsTotal.c : 0;
   const compressedCount = db.prepare(
     `SELECT COUNT(*) as c FROM observations WHERE compressed_into IS NOT NULL ${projectFilter}`
   ).get(...baseParams);
@@ -1142,6 +1156,8 @@ async function cmdStats(db, args) {
         avg_importance: Number((avgImp.v ?? 1).toFixed(2)),
         low_value_count: lowVal.c,
         noise_ratio: Number(noiseRatio.toFixed(4)),
+        low_signal_titles: lowSignalTitle.c,
+        low_signal_ratio: Number(lowSignalRatio.toFixed(4)),
         compressed: compressedCount.c,
         superseded_only: supersededOnlyCount.c,
         hook_errors_24h: hookErrors24h,
@@ -1178,6 +1194,7 @@ async function cmdStats(db, args) {
   out(`  Est. tokens: ${tokenEst.t ?? 0}`);
   out(`  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`);
   out(`  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
+  out(`  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`);
   out(`  Compressed: ${compressedCount.c}`);
   out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
   // Tier-1 firing counters for ① file-intel + ② reread-guard (recorded by
@@ -1187,7 +1204,7 @@ async function cmdStats(db, args) {
   const rrN = featAgg.reread_warn?.count ?? 0;
   const metricsOn = process.env.CLAUDE_MEM_METRICS === '1';
   out(`  Feature injections (7d): 📄 file-intel ${fiN} · 🔁 reread-warn ${rrN}${(!metricsOn && fiN + rrN === 0) ? '  (set CLAUDE_MEM_METRICS=1 to record)' : ''}`);
-  if (noiseRatio > 0.6) out('  ⚠️ High noise ratio — consider running mem compress');
+  if (noiseRatio > 0.6 || lowSignalRatio > 0.3) out('  ⚠️ High noise ratio — consider running mem maintain / compress');
   out('');
   // Tier counts only live (uncompressed, non-superseded) observations — surface the
   // full decomposition so live + compressed + superseded = Total adds up cleanly.
@@ -1901,7 +1918,23 @@ function cmdMaintain(db, args) {
     }
 
     if (ops.includes('purge_stale')) {
-      const retainDays = parseInt(flags['retain-days'], 10) || 30;
+      // --retain-days: default 30 when absent; reject negative / 0 / NaN / out-of-range.
+      // A negative value made retainCutoff a FUTURE timestamp → purged the entire
+      // pending-purge backlog regardless of age; 0/garbage silently became 30 and
+      // masked typos. Parity with the mem_maintain MCP zod bound [7, 365].
+      let retainDays = 30;
+      if (flags['retain-days'] !== undefined) {
+        // Number + isInteger (not parseInt) so "7.5"/"30x" are rejected rather than
+        // silently truncated to 7/30 — parity with the mem_maintain zod .int() bound.
+        const parsed = Number(flags['retain-days']);
+        if (!Number.isInteger(parsed) || parsed < 7 || parsed > 365) {
+          // fail() only sets exitCode + writes stderr; it does NOT throw, so we
+          // MUST return or execution falls through to the DELETE with the bad value.
+          fail(`[mem] --retain-days must be an integer in [7, 365] (got "${flags['retain-days']}")`);
+          return;
+        }
+        retainDays = parsed;
+      }
       const retainCutoff = Date.now() - retainDays * 86400000;
       // T2-P0-A (CLI parity): purge_stale is the only DELETE in this code path — require
       // --confirm so a mis-typed `maintain execute --ops purge_stale` can't wipe rows silently.
@@ -2210,20 +2243,61 @@ function cmdMemdirAudit(args) {
   if (nonCompliant > 0) process.exitCode = 1;
 }
 
+// `citation-stats --sidechain`: subagent (sidechain) cite-recall, the blind spot the
+// main decay loop excludes (it runs mainOnly). aggregateProjectCiteRecall scans THIS
+// project's transcripts: top-level <session>.jsonl = main, and
+// <session>/subagents/agent-*.jsonl = sidechain (descends ONE level into the literal
+// subagents/ dir only, no unbounded recursion). Same methodology, so comparable.
+function _reportSidechainCiteRecall({ days, json }) {
+  const cutoff = Date.now() - days * 86400 * 1000;
+  // memdir = ~/.claude/projects/<encoded>/memory; transcripts are its siblings.
+  const txDir = dirname(memdirPath(process.cwd()));
+  const { main, sidechain } = aggregateProjectCiteRecall(txDir, { cutoff });
+  const rate = b => (b.injected > 0 ? (100 * b.recalled / b.injected) : null);
+  const sideRate = rate(sidechain), mainRate = rate(main);
+
+  if (json) {
+    out(JSON.stringify({
+      window_days: days,
+      main: { ...main, rate: mainRate },
+      sidechain: { ...sidechain, rate: sideRate },
+    }));
+    return;
+  }
+
+  const pct = r => (r === null ? '—' : `${r.toFixed(1)}%`);
+  out(`Sidechain (subagent) cite-recall — last ${days}d:`);
+  out(`  main        ${pct(mainRate).padStart(6)}   recalled ${main.recalled} / injected ${main.injected}   (${main.files} transcript(s))`);
+  out(`  sidechain   ${pct(sideRate).padStart(6)}   recalled ${sidechain.recalled} / injected ${sidechain.injected}   (${sidechain.files} subagent file(s), ${sidechain.withInjections} with injections)`);
+  if (sidechain.files > 0 && sidechain.injected === 0) {
+    out('  → subagent transcripts exist but received ZERO memory injections: claude-mem-lite');
+    out('    hooks do NOT fire inside subagents (no PreToolUse/PostToolUse recall, no');
+    out('    SessionStart block, no mem_* tools). Subagents are memory-blind — giving them');
+    out('    memory needs a NEW surface (inject at Agent/Task dispatch), not deepening.');
+  } else if (sidechain.files === 0) {
+    out('  → no subagent transcripts in window.');
+  }
+}
+
 /**
  * `citation-stats` — visualize the citation-decay feedback loop:
  * per-project cite rate + active decay queue + recently promoted.
  * Read-only over observations.
  *
  * Flags:
- *   --json      machine-readable output
- *   --days N    project cite-rate window (default 7)
+ *   --json       machine-readable output
+ *   --days N     project cite-rate window (default 7)
+ *   --sidechain  subagent (sidechain) cite-recall vs main — the decay-loop blind spot
  */
 function cmdCitationStats(db, args) {
   const { flags } = parseArgs(args);
   const json = flags.json === true || flags.json === 'true';
   const days = parseIntFlag(flags.days, { name: '--days', defaultValue: 7, max: 365 });
 
+  if (flags.sidechain === true || flags.sidechain === 'true') {
+    return _reportSidechainCiteRecall({ days, json });
+  }
+
   const cutoff = Date.now() - days * 86400 * 1000;
   const perProject = db.prepare(`
     SELECT project,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.16.2",
+  "version": "3.17.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",
@@ -81,6 +81,7 @@
     "lib/recall-core.mjs",
     "lib/timeline-core.mjs",
     "lib/search-core.mjs",
+    "lib/rrf.mjs",
     "lib/compress-core.mjs",
     "lib/maintain-core.mjs",
     "lib/dedup-constants.mjs",

package/search-engine.mjs

@@ -11,7 +11,7 @@ import {
   notLowSignalTitleClause, LOW_SIGNAL_TITLE,
   relaxFtsQueryToOr, debugLog, debugCatch, estimateTokens,
 } from './utils.mjs';
-import { getVocabulary, computeVector, vectorSearch, rrfMerge } from './tfidf.mjs';
+import { getVocabulary, computeVector, vectorSearch, rrfMerge, vectorsEnabled } from './tfidf.mjs';
 import { extractPRFTerms, expandQueryByConcepts } from './search-scoring.mjs';
 
 // Scoring expressions — full adds project boost + access bonus; simple is for
@@ -395,6 +395,7 @@ export function searchObservationsHybrid(db, ctx) {
 
   // Vector search + RRF hybrid merge
   try {
+    if (!vectorsEnabled()) return results;  // Phase-1: vector arm disabled → BM25-only path (audit 2026-06-27)
     const vocab = getVocabulary(db);
     if (!vocab) return results;
     const queryText = ftsQuery.replace(/['"()]/g, ' ');

package/search-scoring.mjs

@@ -15,9 +15,14 @@ import { CLI_INVOKE } from './cli-path.mjs';
 // Decision-rules sections; keeps the irreducible CLI/MCP tool list. Intended
 // for users who adopted invited-memory (MEMORY.md sentinel carries the same
 // triggers at higher authority). Default false preserves v2.31.2 behavior.
+// The CLI-vs-MCP round-trip routing rule lives in BASE (not VERBOSE) on purpose:
+// it must reach adopted (quiet) projects too, where tool-heavy sessions defer the
+// mem_* tools behind ToolSearch (CLI via Bash = 1 model round-trip; ToolSearch +
+// call = 2). Execution latency is NOT the lever — warm MCP (~25ms) actually beats
+// CLI cold-start (~90ms); both are noise against one model turn. Round-trips are.
 
 const INSTRUCTIONS_BASE = [
-  'Long-term memory across sessions. Hooks auto-inject context; CLI preferred for explicit queries.',
+  'Long-term memory across sessions. Hooks auto-inject context (0 round-trips) — prefer adopting that over any call. For an explicit query, pick the path with fewer model round-trips (CLI vs MCP below).',
   '',
   `CLI (via Bash) — invoke as \`${CLI_INVOKE} <cmd>\` (resolves on any install shape; the bare \`claude-mem-lite\` shorthand works only after an optional global \`npm i -g claude-mem-lite\`):`,
   `  ${CLI_INVOKE} search "query"  — FTS5 full-text search`,
@@ -27,7 +32,7 @@ const INSTRUCTIONS_BASE = [
   `  ${CLI_INVOKE} get 42,43  — full details by ID`,
   `  ${CLI_INVOKE} timeline --anchor 42  — chronological context`,
   '',
-  'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline for programmatic access (always available — no PATH/CLI install needed).',
+  'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline. If already loaded, call directly (warm server, fastest path). In tool-heavy sessions these are deferred behind ToolSearch — if using one would cost a ToolSearch load first, run the Bash CLI above instead: one call, not two. Neither needs a PATH/CLI install.',
   'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',
   'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
 ];

package/server.mjs

@@ -12,6 +12,7 @@ import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, b
 import { searchObservationsHybrid } from './search-engine.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
+import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
 import { buildSearchFtsQuery, parseDateBounds, coreRunSearchPipeline } from './lib/search-core.mjs';
 import {
@@ -864,6 +865,15 @@ server.registerTool(
     `).get(thirtyDaysAgo, ...baseParams);
 
     const noiseRatio = obsTotal.c > 0 ? lowVal.c / obsTotal.c : 0;
+    // Low-signal-title population (template / tool-log titles the read-side filter
+    // already excludes). The imp=1 "Low-value" metric can't see these, so the
+    // gauge under-reports real noise without it. See lib/low-signal-patterns.mjs.
+    const lowSignalTitle = db.prepare(`
+      SELECT COUNT(*) as c FROM observations
+      WHERE NOT ${buildNotLowSignalSql()}
+        AND COALESCE(compressed_into, 0) = 0 ${projectFilter}
+    `).get(...baseParams);
+    const lowSignalRatio = obsTotal.c > 0 ? lowSignalTitle.c / obsTotal.c : 0;
     const compressedCount = db.prepare(`
       SELECT COUNT(*) as c FROM observations WHERE compressed_into IS NOT NULL ${projectFilter}
     `).get(...baseParams);
@@ -900,8 +910,9 @@ server.registerTool(
       `  Est. tokens: ${tokenEst.t ?? 0}`,
       `  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`,
       `  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`,
+      `  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`,
       `  Compressed: ${compressedCount.c}`,
-      ...(noiseRatio > 0.6 ? ['  ⚠️ High noise ratio — consider running mem_compress'] : []),
+      ...((noiseRatio > 0.6 || lowSignalRatio > 0.3) ? ['  ⚠️ High noise ratio — consider running mem_compress / maintain'] : []),
       '',
       // Tier counts only live (uncompressed, non-superseded) observations — surface
       // the full decomposition so live + compressed + superseded = Total adds up cleanly.

package/source-files.mjs

@@ -114,6 +114,9 @@ export const SOURCE_FILES = [
   // `timeline`/`search` and mem_timeline/mem_search on auto-update.
   'lib/timeline-core.mjs',
   'lib/search-core.mjs',
+  // Reciprocal Rank Fusion core (D#42 single source-of-truth); transitively
+  // reached via tfidf.mjs (rrfMerge) and deep-search.mjs (rrfFuseN).
+  'lib/rrf.mjs',
   // Shared "compress old low-value observations into weekly summaries" core.
   // Statically imported by mem-cli.mjs (cmdCompress), server.mjs (mem_compress),
   // and hook.mjs (handleAutoCompress) — same single-source-of-truth pattern as

package/tfidf.mjs

@@ -6,6 +6,7 @@
 import { cjkBigrams } from './utils.mjs';
 import { BASE_STOP_WORDS } from './stop-words.mjs';
 import { createHash } from 'crypto';
+import { rrfAccumulate } from './lib/rrf.mjs';
 
 export const VOCAB_DIM = 512;
 export const MIN_COSINE_SIMILARITY = 0.05;
@@ -15,6 +16,21 @@ export const VECTOR_SCAN_LIMIT = 500;
 // dominate. 60 is the de-facto RRF default and balances the two retrievers here.
 export const RRF_K = 60;
 
+// Phase-1 disable of the TF-IDF vector arm (memory-quality audit 2026-06-27).
+// The arm reads ~0 benchmark lift (ci-gate hybrid_over_bm25 = 0), pays a
+// computeVector on every observation write, only scans the most-recent
+// VECTOR_SCAN_LIMIT rows (misses older memories), and drifted unnoticed for
+// months. Default OFF. To re-enable: set CLAUDE_MEM_VECTORS=1 AND run
+// `claude-mem-lite maintain execute --ops rebuild_vectors` to repopulate vectors for
+// observations created while disabled — re-enabling WITHOUT a rebuild leaves a
+// partially-populated index (the primary + enrich/compress/optimize write paths all
+// stopped writing while off) → silently degraded hybrid recall until the next
+// rebuild. Tables + code are retained pending Phase-2 removal. Read at call time (not
+// import) so tests + the benchmark A/B can toggle it via env.
+export function vectorsEnabled() {
+  return process.env.CLAUDE_MEM_VECTORS === '1';
+}
+
 const VOCAB_STOP_WORDS = new Set([
   ...BASE_STOP_WORDS,
   'now','only','still','here','there','up','out','am',
@@ -275,6 +291,14 @@ export function rebuildVocabulary(db, opts) {
  * @returns {object|null} vocabulary
  */
 export function getVocabulary(db) {
+  // Phase-1 choke point: when the vector arm is disabled there is no vocabulary to
+  // serve. Returning null here makes EVERY vector write/read path skip via its
+  // existing `if (vocab)` guard — including the enrich (hook-llm), compress
+  // (compress-core) and optimize (hook-optimize) write paths that don't go through
+  // insertObservationVector — so no path can be "missed" and observation_vectors
+  // stays uniformly stale (not half-populated) while disabled. computeVector is
+  // null-safe, so even a caller that skips its guard no-ops rather than crashes.
+  if (!vectorsEnabled()) return null;
   if (_vocabCache) return _vocabCache;
 
   // Try loading from persisted vocab_state
@@ -423,14 +447,9 @@ export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit
  * @returns {{ id: number, rrfScore: number }[]}
  */
 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));
-  });
-  vectorResults.forEach((r, i) => {
-    scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (k + i + 1));
-  });
-  return [...scores.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .map(([id, score]) => ({ id, rrfScore: score }));
+  // Thin 2-list adapter over the shared RRF core (lib/rrf.mjs). Emits the minimal
+  // { id, rrfScore } shape this module's callers (search-engine.mjs) expect; the
+  // accumulator's best-rank row tracking is irrelevant here and ignored.
+  return rrfAccumulate([bm25Results, vectorResults], k)
+    .map(({ id, score }) => ({ id, rrfScore: score }));
 }

package/utils.mjs

@@ -14,7 +14,7 @@ export { cjkBigrams, extractCjkSynonymTokens, extractCjkKeywords, extractCjkLike
 export { resolveProject, _resetProjectCache } from './project-utils.mjs';
 export { scrubSecrets, SECRET_PATTERNS } from './secret-scrub.mjs';
 export { stripPrivate } from './lib/private-strip.mjs';
-export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey } from './format-utils.mjs';
+export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey, formatErrorRecallHints } from './format-utils.mjs';
 export { computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from './hash-utils.mjs';
 export { detectBashSignificance, extractErrorKeywords, extractFilePaths, stripTestSuffix } from './bash-utils.mjs';