claude-mem-lite 2.34.5 → 2.35.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.34.5",
+      "version": "2.35.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.34.5",
+  "version": "2.35.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/hook-llm.mjs

@@ -371,8 +371,9 @@ export function buildDegradedTitle(episode) {
   }
 
   if (files.length > 0) {
-    const names = files.map(f => basename(f)).slice(0, 3).join(', ');
-    const suffix = files.length > 3 ? ` +${files.length - 3} more` : '';
+    const uniqueNames = [...new Set(files.map(f => basename(f)))];
+    const names = uniqueNames.slice(0, 3).join(', ');
+    const suffix = uniqueNames.length > 3 ? ` +${uniqueNames.length - 3} more` : '';
     if (hasError) {
       // Include the triggering command for richer context: "Error: dispatch.mjs — npm test failed"
       const errEntry = episode.entries.find(e => e.isError);

package/hooks/hooks.json

@@ -20,7 +20,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Edit|Write|NotebookEdit",
+        "matcher": "Edit|Write|NotebookEdit|Read",
         "hooks": [
           {
             "type": "command",

package/install.mjs

@@ -489,7 +489,10 @@ async function install() {
   };
 
   const memPreToolRecall = {
-    matcher: 'Edit|Write|NotebookEdit',
+    // v2.34.6: Read added to cover planning-Read (pre-Edit exploration).
+    // Read-path uses a tighter filter (lesson_learned required, top-1,
+    // 120-char truncation, silent-on-empty) — see scripts/pre-tool-recall.js.
+    matcher: 'Edit|Write|NotebookEdit|Read',
     hooks: [
       {
         type: 'command',
@@ -1062,11 +1065,13 @@ async function doctor() {
   }
 
   // Dependencies
-  const bsPath = join(INSTALL_DIR, 'node_modules', 'better-sqlite3');
-  if (existsSync(bsPath)) {
-    ok('better-sqlite3: installed');
-  } else {
-    fail('better-sqlite3: not installed (run install again)');
+  try {
+    const Database = (await import('better-sqlite3')).default;
+    const probe = new Database(':memory:');
+    probe.close();
+    ok('better-sqlite3: verified (import + open OK)');
+  } catch (e) {
+    fail(`better-sqlite3: import/init failed (${e.message})`);
     issues++;
   }
 
@@ -1190,6 +1195,26 @@ async function doctor() {
     warn('Update state: failed to read');
   }
 
+  // Dev drift: in dev-mode installs, all SOURCE_FILES entries should be
+  // symlinks. A plain file means an earlier install (or manual cp) copied it,
+  // so edits in the repo won't propagate to INSTALL_DIR — hook runtime and
+  // test runtime silently diverge.
+  try {
+    const { checkDevDrift } = await import('./lib/doctor-drift.mjs');
+    const r = checkDevDrift(INSTALL_DIR, SOURCE_FILES);
+    if (r.drift) {
+      const names = r.details.join(', ');
+      const suffix = r.plainCount > r.details.length ? ` +${r.plainCount - r.details.length} more` : '';
+      warn(`Dev drift: ${r.plainCount} non-symlink file(s) in dev install: ${names}${suffix} (re-run: node install.mjs install --dev)`);
+      issues++;
+    } else if (r.devMode) {
+      ok(`Dev drift: clean (${r.symlinkCount} symlinks, 0 plain)`);
+    }
+    // Prod (all plain) install: no message — dev-drift is a dev-only concern.
+  } catch (e) {
+    warn('Dev drift: check failed — ' + e.message);
+  }
+
   // Stale temp files
   try {
     const runtimeDir = join(INSTALL_DIR, 'runtime');
@@ -1222,7 +1247,8 @@ async function doctor() {
       const Database = (await import('better-sqlite3')).default;
       const db = new Database(DB_PATH, { readonly: true });
       const obsCount = db.prepare('SELECT COUNT(*) as cnt FROM observations').get()?.cnt || 0;
-      const sessCount = db.prepare('SELECT COUNT(*) as cnt FROM sdk_sessions').get()?.cnt || 0;
+      // Align with stats / MCP mem_stats: session_summaries, not sdk_sessions
+      const sessCount = db.prepare('SELECT COUNT(*) as cnt FROM session_summaries').get()?.cnt || 0;
       db.close();
       ok(`DB stats: ${sizeMB}MB, ${obsCount} observations, ${sessCount} sessions`);
     } catch (e) {

package/lib/doctor-drift.mjs

@@ -0,0 +1,46 @@
+// Dev-drift check: in dev-mode installs (symlinked to project repo), every
+// managed source file in INSTALL_DIR should be a symlink. A regular file
+// means an earlier install copied it (e.g. install.mjs before it was added
+// to SOURCE_FILES) or someone ran `cp` manually — edits won't propagate
+// from the repo, testing vs runtime will silently diverge.
+//
+// Returns: { devMode, drift, details } — devMode=false when no symlinks
+// detected (prod copy install), drift=true when in dev-mode AND at least
+// one SOURCE_FILES entry is a plain file.
+
+import { existsSync, lstatSync } from 'fs';
+import { join } from 'path';
+
+export function checkDevDrift(installDir, sourceFiles) {
+  if (!existsSync(installDir)) {
+    return { devMode: false, drift: false, symlinkCount: 0, plainCount: 0, plainFiles: [], missingCount: 0, details: [] };
+  }
+  const symlinkFiles = [];
+  const plainFiles = [];
+  const missing = [];
+  for (const rel of sourceFiles) {
+    const p = join(installDir, rel);
+    if (!existsSync(p)) { missing.push(rel); continue; }
+    try {
+      const st = lstatSync(p);
+      if (st.isSymbolicLink()) symlinkFiles.push(rel);
+      else plainFiles.push(rel);
+    } catch {
+      missing.push(rel);
+    }
+  }
+  // devMode detection: if ≥1 symlink exists among source files, consider
+  // this a dev install. (Prod install is all plain files → drift=false
+  // because there's nothing to drift from.)
+  const devMode = symlinkFiles.length > 0;
+  const drift = devMode && plainFiles.length > 0;
+  return {
+    devMode,
+    drift,
+    symlinkCount: symlinkFiles.length,
+    plainCount: plainFiles.length,
+    plainFiles,
+    missingCount: missing.length,
+    details: plainFiles.slice(0, 5),
+  };
+}

package/lib/low-signal-patterns.mjs

@@ -0,0 +1,60 @@
+// Single source of truth for LOW_SIGNAL title patterns.
+//
+// "LOW_SIGNAL" = hook-llm fallback titles written when Haiku summarization
+// is unavailable or skipped ("Modified X", "Worked on X", "Reviewed N files:",
+// raw "Error: ..." logs, bare "node/npm/npx <cmd>" etc.). Empirical data:
+// ~544 such entries in production, 18 ever accessed (3.3% retrieval rate).
+//
+// Three consumers must stay in sync (pre-β: by hand-mirrored comments);
+// post-β: all three derive from this module.
+//   1. utils.mjs::LOW_SIGNAL_TITLE       — regex for write-side importance cap
+//   2. scoring-sql.mjs::notLowSignalTitleClause — SQL NOT LIKE chain for read-side filter
+//   3. scripts/pre-tool-recall.js         — inline SQL (standalone cold-start script)
+//
+// This module is intentionally dependency-free so scripts/pre-tool-recall.js can
+// import it without inflating the ~30ms cold-start budget.
+
+/**
+ * Each entry has:
+ *   - like:  SQLite LIKE pattern (anchored; % = any chars)
+ *   - regex: JS regex source fragment (MUST match the same title set as `like`)
+ *
+ * Adding/removing entries requires updating the sync test (tests/low-signal-sync.test.mjs).
+ */
+export const LOW_SIGNAL_PATTERNS = [
+  { like: 'Modified %',              regex: '^Modified ' },
+  { like: 'Worked on %',             regex: '^Worked on ' },
+  { like: 'Reviewed % files:%',      regex: '^Reviewed \\d+ files:' },
+  { like: 'Codebase exploration%',   regex: '^Codebase exploration' },
+  { like: 'Error while working%',    regex: '^Error while working' },
+  { like: 'Error in %',              regex: '^Error in ' },
+  { like: 'Error: %',                regex: '^Error: ' },
+  { like: '# %',                     regex: '^# ' },
+  { like: 'node %',                  regex: '^node ' },
+  { like: 'npm %',                   regex: '^npm ' },
+  { like: 'npx %',                   regex: '^npx ' },
+  { like: '(no description)%',       regex: '^\\(no description\\)' },
+  { like: '%(error)',                regex: '\\(error\\)$' },
+];
+
+/**
+ * Build the combined regex that matches ANY LOW_SIGNAL pattern.
+ * Equivalent to the hand-written `LOW_SIGNAL_TITLE` before β refactor.
+ */
+export function buildLowSignalRegex() {
+  const src = LOW_SIGNAL_PATTERNS.map(p => `(?:${p.regex})`).join('|');
+  return new RegExp(src);
+}
+
+/**
+ * Build the SQL NOT LIKE clause chain, optionally prefixed with a table alias.
+ * Output is a single parenthesized AND-chain — safe to combine with other AND/OR.
+ *
+ * @param {string} [alias=''] Table alias (e.g. 'o') — empty for unqualified.
+ * @returns {string} SQL boolean expression
+ */
+export function buildNotLowSignalSql(alias = '') {
+  const p = alias ? `${alias}.` : '';
+  const clauses = LOW_SIGNAL_PATTERNS.map(({ like }) => `${p}title NOT LIKE '${like}'`);
+  return '(\n    ' + clauses.join('\n    AND ') + '\n  )';
+}

package/lib/stats-quality.mjs

@@ -0,0 +1,130 @@
+// Shared quality-dashboard computation — used by both mem-cli.mjs (CLI
+// `stats --quality`) and server.mjs (MCP `mem_stats({quality: true})`).
+// Splits pure data aggregation from text rendering so MCP handlers don't
+// collide with CLI's `out()` stdout-write pattern.
+
+import { notLowSignalTitleClause } from '../scoring-sql.mjs';
+import { truncate } from '../format-utils.mjs';
+
+export function computeQualityStats(db, { project, days }) {
+  const projectFilter = project ? 'AND project = ?' : '';
+  const baseParams = project ? [project] : [];
+  const cutoff = Date.now() - days * 86400000;
+
+  // LOW_SIGNAL match = NOT notLowSignal. Shared helper keeps SQL in sync
+  // with scoring-sql.mjs and pre-tool-recall.js Edit-fallback filter.
+  const lowSignalIsMatchExpr = `NOT ${notLowSignalTitleClause('')}`;
+
+  // Narrative-text proxy for bugfix investigations that never landed a fix.
+  const unresolvedNarrativeExpr = `(
+    LOWER(COALESCE(narrative,'')) LIKE '%not yet identified%'
+    OR LOWER(COALESCE(narrative,'')) LIKE '%not yet resolved%'
+    OR LOWER(COALESCE(narrative,'')) LIKE '%not yet fixed%'
+    OR LOWER(COALESCE(narrative,'')) LIKE '%root cause not%'
+    OR LOWER(COALESCE(narrative,'')) LIKE '%still fail%'
+    OR LOWER(COALESCE(narrative,'')) LIKE '%errors persisted%'
+    OR LOWER(COALESCE(narrative,'')) LIKE '%persisted on retry%'
+  )`;
+
+  const windowRow = db.prepare(`
+    SELECT
+      COUNT(*) as total,
+      SUM(CASE WHEN lesson_learned IS NOT NULL AND lesson_learned != '' THEN 1 ELSE 0 END) as with_lesson,
+      SUM(CASE WHEN ${lowSignalIsMatchExpr} THEN 1 ELSE 0 END) as low_signal,
+      SUM(CASE WHEN type = 'bugfix' THEN 1 ELSE 0 END) as bugfix_total,
+      SUM(CASE WHEN type = 'bugfix' AND ${unresolvedNarrativeExpr} THEN 1 ELSE 0 END) as bugfix_unresolved
+    FROM observations
+    WHERE created_at_epoch >= ? ${projectFilter}
+  `).get(cutoff, ...baseParams);
+
+  const allTimeRow = db.prepare(`
+    SELECT
+      COUNT(*) as total,
+      SUM(CASE WHEN lesson_learned IS NOT NULL AND lesson_learned != '' THEN 1 ELSE 0 END) as with_lesson,
+      SUM(CASE WHEN ${lowSignalIsMatchExpr} THEN 1 ELSE 0 END) as low_signal
+    FROM observations
+    WHERE 1=1 ${projectFilter}
+  `).get(...baseParams);
+
+  const typeRows = db.prepare(`
+    SELECT
+      type,
+      COUNT(*) as total,
+      SUM(CASE WHEN COALESCE(access_count, 0) > 0 THEN 1 ELSE 0 END) as accessed,
+      SUM(CASE WHEN lesson_learned IS NOT NULL AND lesson_learned != '' THEN 1 ELSE 0 END) as with_lesson
+    FROM observations
+    WHERE created_at_epoch >= ? ${projectFilter}
+    GROUP BY type
+    ORDER BY total DESC
+  `).all(cutoff, ...baseParams);
+
+  const topLessons = db.prepare(`
+    SELECT id, type, title, lesson_learned, COALESCE(access_count, 0) as ac
+    FROM observations
+    WHERE lesson_learned IS NOT NULL AND lesson_learned != ''
+      AND COALESCE(access_count, 0) > 0
+      AND COALESCE(compressed_into, 0) = 0
+      ${projectFilter}
+    ORDER BY ac DESC
+    LIMIT 5
+  `).all(...baseParams);
+
+  return { windowRow, allTimeRow, typeRows, topLessons, project, days };
+}
+
+export function formatQualityReport(data) {
+  const { windowRow, allTimeRow, typeRows, topLessons, project, days } = data;
+  const pct = (n, d) => d > 0 ? (100 * n / d).toFixed(1) : '0.0';
+  const scope = project ? ` — ${project}` : '';
+  const lines = [];
+  lines.push(`[mem] Quality snapshot${scope} — window: ${days}d`);
+  lines.push('────────────────────────────────────────────────────');
+  lines.push(`  Writes (${days}d):     ${windowRow.total} observations`);
+
+  const lessonPct = pct(windowRow.with_lesson, windowRow.total);
+  const allLessonPct = pct(allTimeRow.with_lesson, allTimeRow.total);
+  lines.push(`  Lesson rate:      ${windowRow.with_lesson} / ${windowRow.total} (${lessonPct}%)    [all-time: ${allTimeRow.with_lesson} / ${allTimeRow.total} = ${allLessonPct}%]`);
+
+  const noisePct = pct(windowRow.low_signal, windowRow.total);
+  const allNoisePct = pct(allTimeRow.low_signal, allTimeRow.total);
+  lines.push(`  LOW_SIGNAL:       ${windowRow.low_signal} / ${windowRow.total} (${noisePct}%)    [all-time: ${allTimeRow.low_signal} / ${allTimeRow.total} = ${allNoisePct}%]`);
+
+  if (windowRow.bugfix_total > 0) {
+    const unresolvedPct = pct(windowRow.bugfix_unresolved, windowRow.bugfix_total);
+    lines.push(`  Unresolved bugfix: ${windowRow.bugfix_unresolved} / ${windowRow.bugfix_total} (${unresolvedPct}%)    [investigation-only narratives — should trend ↓ with R-6 manual-save contract]`);
+  }
+  lines.push('');
+
+  if (typeRows.length > 0) {
+    lines.push(`  Type breakdown (${days}d):`);
+    for (const r of typeRows) {
+      const hit = pct(r.accessed, r.total);
+      const lp = pct(r.with_lesson, r.total);
+      const typeLabel = r.type.padEnd(10);
+      lines.push(`    ${typeLabel}${String(r.total).padStart(5)}   hit ${hit.padStart(5)}%   lesson ${lp.padStart(5)}%`);
+    }
+    lines.push('');
+  }
+
+  if (topLessons.length > 0) {
+    lines.push('  Top accessed lessons (all-time):');
+    for (const l of topLessons) {
+      const t = truncate(l.lesson_learned, 80);
+      lines.push(`    #${l.id} [${l.type}] (${l.ac}x) ${t}`);
+    }
+    lines.push('');
+  }
+
+  // R-2 watchdog — format matches historical cmdStats for test stability
+  const lessonNum = parseFloat(lessonPct);
+  const noiseNum = parseFloat(noisePct);
+  const lessonGap = (lessonNum - 15).toFixed(1);
+  const noiseGap = (noiseNum - 30).toFixed(1);
+  const lessonStatus = lessonNum >= 15 ? '✅' : '🔴';
+  const noiseStatus = noiseNum <= 30 ? '✅' : '🔴';
+  lines.push('  Targets (R-2 watchdog):');
+  lines.push(`    ${lessonStatus} Lesson rate ≥ 15%    → currently ${lessonPct}%  (gap ${lessonGap >= 0 ? '+' : ''}${lessonGap}pp)`);
+  lines.push(`    ${noiseStatus} LOW_SIGNAL  ≤ 30%    → currently ${noisePct}%  (gap ${noiseGap >= 0 ? '+' : ''}${noiseGap}pp)`);
+
+  return lines.join('\n');
+}

package/mem-cli.mjs

@@ -902,132 +902,17 @@ function cmdSave(db, args) {
 // Targets (aspirational, not enforced):
 //   - Lesson rate ≥ 15%      (current baseline ~4.4%)
 //   - LOW_SIGNAL rate ≤ 30%  (current baseline ~49.4%)
-function renderQualityReport(db, { project, days }) {
-  const projectFilter = project ? 'AND project = ?' : '';
-  const baseParams = project ? [project] : [];
-  const now = Date.now();
-  const cutoff = now - days * 86400000;
-
-  // LOW_SIGNAL is the inverse of notLowSignalTitleClause() — inline a SUM(CASE)
-  // that flips the sign so we count titles that DO match the LOW_SIGNAL regex.
-  const lowSignalIsMatchExpr = `NOT ${notLowSignalTitleClause('')}`;
-
-  // Unresolved-bugfix detection: narrative-text proxies for "investigation in progress,
-  // never reached a fix". Heuristic — false positives possible (e.g. a real lesson noting
-  // "the bug persists in legacy clients"), but the directional signal is what we care about.
-  // R-7 micro-experiment surfaced this pollution: ~3/5 of randomly-sampled bugfix narratives
-  // explicitly ended with "root cause not yet identified".
-  const unresolvedNarrativeExpr = `(
-    LOWER(COALESCE(narrative,'')) LIKE '%not yet identified%'
-    OR LOWER(COALESCE(narrative,'')) LIKE '%not yet resolved%'
-    OR LOWER(COALESCE(narrative,'')) LIKE '%not yet fixed%'
-    OR LOWER(COALESCE(narrative,'')) LIKE '%root cause not%'
-    OR LOWER(COALESCE(narrative,'')) LIKE '%still fail%'
-    OR LOWER(COALESCE(narrative,'')) LIKE '%errors persisted%'
-    OR LOWER(COALESCE(narrative,'')) LIKE '%persisted on retry%'
-  )`;
-
-  // In-window aggregates
-  const windowRow = db.prepare(`
-    SELECT
-      COUNT(*) as total,
-      SUM(CASE WHEN lesson_learned IS NOT NULL AND lesson_learned != '' THEN 1 ELSE 0 END) as with_lesson,
-      SUM(CASE WHEN ${lowSignalIsMatchExpr} THEN 1 ELSE 0 END) as low_signal,
-      SUM(CASE WHEN type = 'bugfix' THEN 1 ELSE 0 END) as bugfix_total,
-      SUM(CASE WHEN type = 'bugfix' AND ${unresolvedNarrativeExpr} THEN 1 ELSE 0 END) as bugfix_unresolved
-    FROM observations
-    WHERE created_at_epoch >= ? ${projectFilter}
-  `).get(cutoff, ...baseParams);
-
-  // All-time aggregates (context for recent numbers)
-  const allTimeRow = db.prepare(`
-    SELECT
-      COUNT(*) as total,
-      SUM(CASE WHEN lesson_learned IS NOT NULL AND lesson_learned != '' THEN 1 ELSE 0 END) as with_lesson,
-      SUM(CASE WHEN ${lowSignalIsMatchExpr} THEN 1 ELSE 0 END) as low_signal
-    FROM observations
-    WHERE 1=1 ${projectFilter}
-  `).get(...baseParams);
-
-  // Per-type: count, hit rate (access_count > 0), lesson rate
-  const typeRows = db.prepare(`
-    SELECT
-      type,
-      COUNT(*) as total,
-      SUM(CASE WHEN COALESCE(access_count, 0) > 0 THEN 1 ELSE 0 END) as accessed,
-      SUM(CASE WHEN lesson_learned IS NOT NULL AND lesson_learned != '' THEN 1 ELSE 0 END) as with_lesson
-    FROM observations
-    WHERE created_at_epoch >= ? ${projectFilter}
-    GROUP BY type
-    ORDER BY total DESC
-  `).all(cutoff, ...baseParams);
-
-  // Top-5 most-accessed lessons (all-time, this project scope)
-  const topLessons = db.prepare(`
-    SELECT id, type, title, lesson_learned, COALESCE(access_count, 0) as ac
-    FROM observations
-    WHERE lesson_learned IS NOT NULL AND lesson_learned != ''
-      AND COALESCE(access_count, 0) > 0
-      AND COALESCE(compressed_into, 0) = 0
-      ${projectFilter}
-    ORDER BY ac DESC
-    LIMIT 5
-  `).all(...baseParams);
-
-  const pct = (n, d) => d > 0 ? (100 * n / d).toFixed(1) : '0.0';
-  const scope = project ? ` — ${project}` : '';
-  out(`[mem] Quality snapshot${scope} — window: ${days}d`);
-  out('────────────────────────────────────────────────────');
-  out(`  Writes (${days}d):     ${windowRow.total} observations`);
-
-  const lessonPct = pct(windowRow.with_lesson, windowRow.total);
-  const allLessonPct = pct(allTimeRow.with_lesson, allTimeRow.total);
-  out(`  Lesson rate:      ${windowRow.with_lesson} / ${windowRow.total} (${lessonPct}%)    [all-time: ${allTimeRow.with_lesson} / ${allTimeRow.total} = ${allLessonPct}%]`);
-
-  const noisePct = pct(windowRow.low_signal, windowRow.total);
-  const allNoisePct = pct(allTimeRow.low_signal, allTimeRow.total);
-  out(`  LOW_SIGNAL:       ${windowRow.low_signal} / ${windowRow.total} (${noisePct}%)    [all-time: ${allTimeRow.low_signal} / ${allTimeRow.total} = ${allNoisePct}%]`);
-
-  if (windowRow.bugfix_total > 0) {
-    const unresolvedPct = pct(windowRow.bugfix_unresolved, windowRow.bugfix_total);
-    out(`  Unresolved bugfix: ${windowRow.bugfix_unresolved} / ${windowRow.bugfix_total} (${unresolvedPct}%)    [investigation-only narratives — should trend ↓ with R-6 manual-save contract]`);
-  }
-  out('');
-
-  if (typeRows.length > 0) {
-    out(`  Type breakdown (${days}d):`);
-    for (const r of typeRows) {
-      const hit = pct(r.accessed, r.total);
-      const lp = pct(r.with_lesson, r.total);
-      const typeLabel = r.type.padEnd(10);
-      // padStart(5) on count so rows align up to 5-digit totals (99999).
-      out(`    ${typeLabel}${String(r.total).padStart(5)}   hit ${hit.padStart(5)}%   lesson ${lp.padStart(5)}%`);
-    }
-    out('');
-  }
-
-  if (topLessons.length > 0) {
-    out('  Top accessed lessons (all-time):');
-    for (const l of topLessons) {
-      const t = truncate(l.lesson_learned, 80);
-      out(`    #${l.id} [${l.type}] (${l.ac}x) ${t}`);
-    }
-    out('');
-  }
-
-  // R-2 watchdog — explicit targets make progress legible.
-  const lessonNum = parseFloat(lessonPct);
-  const noiseNum = parseFloat(noisePct);
-  const lessonGap = (lessonNum - 15).toFixed(1);
-  const noiseGap = (noiseNum - 30).toFixed(1);
-  const lessonStatus = lessonNum >= 15 ? '✅' : '🔴';
-  const noiseStatus = noiseNum <= 30 ? '✅' : '🔴';
-  out('  Targets (R-2 watchdog):');
-  out(`    ${lessonStatus} Lesson rate ≥ 15%    → currently ${lessonPct}%  (gap ${lessonGap >= 0 ? '+' : ''}${lessonGap}pp)`);
-  out(`    ${noiseStatus} LOW_SIGNAL  ≤ 30%    → currently ${noisePct}%  (gap ${noiseGap >= 0 ? '+' : ''}${noiseGap}pp)`);
+// Batch A CLI↔MCP alignment: CLI `stats --quality` and MCP `mem_stats({quality:true})`
+// share the same computation + formatting via lib/stats-quality.mjs. This wrapper
+// keeps the cmdStats call-site unchanged (stays sync-compatible) by delegating
+// to a dynamic import + sync function chain inside an async caller.
+async function renderQualityReport(db, { project, days }) {
+  const { computeQualityStats, formatQualityReport } = await import('./lib/stats-quality.mjs');
+  out(formatQualityReport(computeQualityStats(db, { project, days })));
 }
 
-function cmdStats(db, args) {
+
+async function cmdStats(db, args) {
   const { flags } = parseArgs(args);
   const project = flags.project ? resolveProject(db, flags.project) : null;
   const days = parseInt(flags.days, 10) || 30;
@@ -1036,7 +921,7 @@ function cmdStats(db, args) {
   // the baseline metric dashboard for the future Haiku prompt A/B test.
   const quality = flags.quality === true || flags.quality === 'true';
   if (quality) {
-    renderQualityReport(db, { project, days });
+    await renderQualityReport(db, { project, days });
     return;
   }
 
@@ -2025,6 +1910,7 @@ Commands:
     --tier T            Filter by tier (working|active|archive, observations only)
     --sort S            Sort: relevance (default), time, importance
     --or                Use OR instead of AND between search terms
+    --include-noise     Include hook-llm fallback titles ("Modified X", raw error logs)
 
   recent [N]            Show N most recent observations (default 10)
     --project P         Filter by project
@@ -2467,7 +2353,7 @@ export async function run(argv) {
       case 'maintain':  cmdMaintain(db, cmdArgs); break;
       case 'optimize':  await cmdOptimize(db, cmdArgs); break;
       case 'fts-check': cmdFtsCheck(db, cmdArgs); break;
-      case 'stats':     cmdStats(db, cmdArgs); break;
+      case 'stats':     await cmdStats(db, cmdArgs); break;
       case 'context':   cmdContext(db, cmdArgs); break;
       case 'browse':    cmdBrowse(db, cmdArgs); break;
       case 'registry':  cmdRegistry(db, cmdArgs); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.34.5",
+  "version": "2.35.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -47,6 +47,9 @@
     "lib/plan-reader.mjs",
     "lib/startup-dashboard.mjs",
     "lib/doctor-benchmark.mjs",
+    "lib/doctor-drift.mjs",
+    "lib/stats-quality.mjs",
+    "lib/low-signal-patterns.mjs",
     "registry.mjs",
     "registry-retriever.mjs",
     "registry-indexer.mjs",

package/scoring-sql.mjs

@@ -1,6 +1,8 @@
 // scoring-sql.mjs — SQL constants for BM25 scoring and temporal decay.
 // Extracted from utils.mjs for focused module boundaries.
 
+import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
+
 // ─── Type-Differentiated Recency Decay ──────────────────────────────────────
 
 /** Recency half-life per observation type (in milliseconds) */
@@ -74,25 +76,10 @@ export const TYPE_QUALITY_CASE = `(
  * @param {string} [alias='o'] Table alias for the observations row. Use '' for unqualified.
  * @returns {string} SQL boolean expression (already parenthesized; safe to combine with AND/OR)
  */
+// β refactor (#7877 applied): delegated to lib/low-signal-patterns.mjs.
+// The SQL path (this), the regex path (utils.mjs::LOW_SIGNAL_TITLE), and the
+// pre-tool-recall.js inline SQL now all derive from one authoritative
+// pattern list. Previously hand-mirrored with "keep in sync" comments.
 export function notLowSignalTitleClause(alias = 'o') {
-  const p = alias ? `${alias}.` : '';
-  // Bug #2 fix: replace `title != '(error)'` (exact match only) with
-  // `title NOT LIKE '%(error)'` (suffix match) so titles like
-  // "gh release list ... (error)" — produced when makeEntryDesc tags a failed
-  // tool invocation — are excluded too. The LIKE form subsumes the exact match.
-  // Keep in sync with LOW_SIGNAL_TITLE regex in utils.mjs.
-  return `(
-    ${p}title NOT LIKE 'Modified %'
-    AND ${p}title NOT LIKE 'Worked on %'
-    AND ${p}title NOT LIKE 'Reviewed % files:%'
-    AND ${p}title NOT LIKE 'Error while working%'
-    AND ${p}title NOT LIKE 'Error in %'
-    AND ${p}title NOT LIKE 'Error: %'
-    AND ${p}title NOT LIKE '# %'
-    AND ${p}title NOT LIKE 'node %'
-    AND ${p}title NOT LIKE 'npm %'
-    AND ${p}title NOT LIKE 'npx %'
-    AND ${p}title NOT LIKE '(no description)%'
-    AND ${p}title NOT LIKE '%(error)'
-  )`;
+  return buildNotLowSignalSql(alias);
 }

package/scripts/pre-skill-bridge.js

@@ -70,10 +70,11 @@ try {
     // (notably sdscc) silently drop plain-text stdout from PreToolUse — the previous
     // console.log() form would render on stock CC but no-op on those variants.
     // Token budget: ~4 chars per token, 4000 token limit = 16000 chars.
+    const portablePath = resolvedPath.startsWith(homedir()) ? '~' + resolvedPath.slice(homedir().length) : resolvedPath;
     let additionalContext;
     if (content.length > 16000) {
       const summary = content.slice(0, 800);
-      additionalContext = `<skill-bridge name="${row.name}" source="managed" truncated="true">\n${summary}\n...\n</skill-bridge>\n\nSkill content truncated. Use mem_use(name="${row.name}") to load full content.`;
+      additionalContext = `<skill-bridge name="${row.name}" source="managed" truncated="true">\n${summary}\n...\n</skill-bridge>\n\nSkill content truncated. Read("${portablePath}") to load full content.`;
     } else {
       additionalContext = `<skill-bridge name="${row.name}" source="managed">\n${content}\n</skill-bridge>\n\nThis skill was loaded from the managed registry. Follow the instructions above.`;
     }

package/scripts/pre-tool-recall.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 // claude-mem-lite: PreToolUse file recall — injects lessons before Edit/Write
-// Lightweight standalone (~30ms): only imports better-sqlite3, fs, path, os
+// Lightweight standalone (~30ms): only imports better-sqlite3, fs, path, os,
+// and the pure-data lib/low-signal-patterns.mjs (zero runtime deps, ~1ms overhead).
 // Safety: readonly DB, exit 0 always, 3s timeout
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'fs';
 import { basename, join } from 'path';
 import { homedir } from 'os';
+import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 
 // CLAUDE_MEM_DB_PATH / CLAUDE_MEM_RUNTIME_DIR env overrides allow tests and debug tools to
 // point the hook at an isolated DB + cooldown dir without touching the user's real state.
@@ -91,14 +93,23 @@ try {
   // Parse event
   let filePath;
   let sessionId;
+  let toolName;
   try {
     const event = JSON.parse(input);
     filePath = event.tool_input?.file_path;
     sessionId = event.session_id || null;
+    toolName = event.tool_name || null;
   } catch { process.exit(0); }
 
   if (!filePath) process.exit(0);
 
+  // v2.34.6 Gap 3: Read-side recall with asymmetric quiet-mode. Reads have
+  // lower per-event information value than Edits (passive observation, may
+  // not lead to action), so inject less per Read. Cooldown is shared with
+  // Edit via per-filePath session state — Read→Edit in the same session is
+  // not double-injected. See CHANGELOG v2.34.6 for the data behind 120/1/no-nudge.
+  const isRead = toolName === 'Read';
+
   // v2.33.1: session-scoped cooldown. Within one session, same file recalls
   // once; cross-session, each session gets fresh nudges. Legacy 5-min global
   // cooldown only applies when no session_id is present.
@@ -135,6 +146,26 @@ try {
     // Priority: 1) observations with lesson_learned (most actionable for preventing repeat bugs)
     //           2) bugfix/decision types with importance>=2 (contextual history)
     // Skip pure change/discovery without lessons — they add noise without actionable value.
+    //
+    // v2.34.6: Read tightens the filter to require lesson_learned (drops type-OR
+    // fallback — decision/bugfix WITHOUT lesson add context noise to passive Reads
+    // where the agent isn't committed to a change). Edit/Write keep the wider
+    // filter for decision-point context.
+    // LOW_SIGNAL title patterns — auto-generated hook-llm fallback titles carry
+    // no actionable guidance. β refactor (#7877 applied): derived from
+    // lib/low-signal-patterns.mjs so this cold-start script, utils.mjs regex,
+    // and scoring-sql.mjs SQL share one authoritative list.
+    const notLowSignalSql = buildNotLowSignalSql('o');
+    // Edit: bugfix/decision without lesson_learned is admitted only when the
+    // title isn't a LOW_SIGNAL auto-fallback (those carry pipe-delimited raw
+    // output or filename-stubs, no guidance value for the about-to-Edit agent).
+    const typeFallback = isRead
+      ? 'AND o.lesson_learned IS NOT NULL AND o.lesson_learned != \'\''
+      : `AND (
+          (o.lesson_learned IS NOT NULL AND o.lesson_learned != '')
+          OR (o.type IN ('bugfix', 'decision') AND ${notLowSignalSql})
+        )`;
+    const obsLimit = isRead ? 1 : 2;
     const rows = db.prepare(`
       SELECT DISTINCT o.id, o.type, o.title, o.lesson_learned
       FROM observations o
@@ -145,14 +176,11 @@ try {
         AND o.superseded_at IS NULL
         AND o.created_at_epoch > ?
         AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
-        AND (
-          (o.lesson_learned IS NOT NULL AND o.lesson_learned != '')
-          OR o.type IN ('bugfix', 'decision')
-        )
+        ${typeFallback}
       ORDER BY
         CASE WHEN o.lesson_learned IS NOT NULL AND o.lesson_learned != '' THEN 0 ELSE 1 END,
         o.created_at_epoch DESC
-      LIMIT 2
+      LIMIT ${obsLimit}
     `).all(project, cutoff, filePath, likePattern);
 
     // T9: also query the `events` table — after T9, bugfix/lesson/decision/etc.
@@ -163,6 +191,11 @@ try {
     // matching "myfoo.mjs".
     const fnameEscaped = fname.replace(/%/g, '\\%').replace(/_/g, '\\_');
     const filePathEscaped = filePath.replace(/%/g, '\\%').replace(/_/g, '\\_');
+    // v2.34.6: Read also tightens the events query — only rows with a non-empty
+    // body (= lesson equivalent). Edit path keeps the wider net since the agent
+    // is about to change the file and benefits from any contextual signal.
+    const eventsBodyFilter = isRead ? "AND body IS NOT NULL AND body != ''" : '';
+    const eventsLimit = isRead ? 1 : 2;
     let eventRows = [];
     try {
       eventRows = db.prepare(`
@@ -173,25 +206,29 @@ try {
           AND superseded_at_epoch IS NULL
           AND created_at_epoch > ?
           AND (file_paths LIKE ? ESCAPE '\\' OR file_paths LIKE ? ESCAPE '\\')
+          ${eventsBodyFilter}
         ORDER BY created_at_epoch DESC
-        LIMIT 2
+        LIMIT ${eventsLimit}
       `).all(project, cutoff, `%"${fnameEscaped}"%`, `%"${filePathEscaped}"%`);
     } catch { /* events table may not exist on pre-v2.31 DBs — silent */ }
 
-    // Merge: observations first (they carry richer lesson_learned), then events,
-    // capped at 3 total so the injected context stays small per Edit/Write.
-    const allRows = [...rows, ...eventRows].slice(0, 3);
+    // Merge: observations first (they carry richer lesson_learned), then events.
+    // Edit/Write caps at 3 total; Read caps at 1 (single most-actionable hit).
+    const mergeCap = isRead ? 1 : 3;
+    const allRows = [...rows, ...eventRows].slice(0, mergeCap);
 
     // v2.31 T2: emit JSON with hookSpecificOutput.additionalContext so the message
     // reliably renders across CC variants (sdscc drops plain-text stdout from PreToolUse).
     // suppressOutput:true hides it from transcript mode per CC hook docs.
     const lines = [];
+    // v2.34.6: Read mode uses 120-char truncation (Edit mode keeps the 240-char
+    // cap from R3-UX). Rationale: Read is a one-shot nudge with 1 lesson max;
+    // Edit is a 3-lesson decision-support injection where the fuller lesson tail
+    // carries the actionable "Fix:" guidance — short enough per-lesson at 240,
+    // but the total payload is bounded by the 3-row limit and the cooldown.
+    const LESSON_MAX = isRead ? 120 : 240;
     if (allRows.length > 0) {
       lines.push(`[mem] Lessons for ${fname}:`);
-      // R3-UX: raised from 120 → 240 after measuring 97% of lessons exceed 120 chars
-      // (p50=218, avg=247). Previous limit truncated the actionable "Fix:" tail in 80%
-      // of lessons containing it. 3 × 240 ≈ 180 tokens/Edit — negligible context cost.
-      const LESSON_MAX = 240;
       for (const r of allRows) {
         if (r.lesson_learned) {
           const lesson = r.lesson_learned.length > LESSON_MAX
@@ -205,22 +242,29 @@ try {
           lines.push(`  #${r.id} [${r.type}] ${title}`);
         }
       }
-    } else {
-      // R-4: emit a short backfill reminder instead of staying silent.
-      // Two goals: (1) Claude sees that the system actually ran, (2) Claude is
-      // nudged to save a lesson when solving a non-obvious bug. The reminder
-      // is one line to minimize per-Edit context cost.
+    } else if (!isRead) {
+      // R-4: Edit/Write empty → short backfill reminder. Two goals: (1) Claude
+      // sees that the system actually ran, (2) Claude is nudged to save a lesson
+      // after a non-obvious bug. Reminder is one line to keep per-Edit cost low.
+      //
+      // v2.34.6: Read does NOT emit this nudge. Read is passive — the agent
+      // isn't necessarily about to solve anything, so /lesson prompts are noise.
+      // Empty Reads exit silently, saving ~60 tokens × (every empty-file Read).
       lines.push(`[mem] No prior lessons for ${fname} — if you solve a non-obvious bug here, run: /lesson --file ${fname} "<root cause + fix>"`);
     }
 
-    process.stdout.write(JSON.stringify({
-      suppressOutput: true,
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        additionalContext: lines.join('\n'),
-      },
-    }));
-    // Cooldown applies to BOTH branches so the reminder doesn't spam every Edit.
+    if (lines.length > 0) {
+      process.stdout.write(JSON.stringify({
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext: lines.join('\n'),
+        },
+      }));
+    }
+    // Cooldown applies on ALL branches (including silent-Read) so subsequent
+    // calls on the same file in the same session don't re-query — preserving
+    // the per-filePath invariant that underpins Read→Edit dedup.
     cooldown[filePath] = now;
     writeCooldown(cooldownPath, cooldown, isSessionScoped);
   } catch {

package/server.mjs

@@ -105,9 +105,22 @@ const RECENCY_HALF_LIFE_MS = DEFAULT_DECAY_HALF_LIFE_MS;
 
 // ─── MCP Server ─────────────────────────────────────────────────────────────
 
+// Emit one-line instructions-mode trace on stderr so debugging the "why did
+// the server send BASE instead of BASE+VERBOSE?" path doesn't require reading
+// three files (server.mjs → hook-shared.mjs → memdir.mjs). CLAUDE_MEM_QUIET_TRACE=0
+// opts out. stderr doesn't pollute the MCP stdio protocol channel.
+const _quiet = effectiveQuiet();
+if (process.env.CLAUDE_MEM_QUIET_TRACE !== '0') {
+  const reason = process.env.MEM_QUIET_HOOKS === '1'
+    ? 'env:MEM_QUIET_HOOKS=1'
+    : _quiet ? 'adopted:MEMORY.md-sentinel' : 'none';
+  const mode = _quiet ? 'BASE' : 'BASE+VERBOSE';
+  process.stderr.write(`[mem] instructions: ${mode} reason=${reason}\n`);
+}
+
 const server = new McpServer(
   { name: 'claude-mem-lite', version: PKG_VERSION },
-  { instructions: buildServerInstructions(effectiveQuiet()) },
+  { instructions: buildServerInstructions(_quiet) },
 );
 
 // Track MCP request activity for idle-time cleanup (see idle timer below)
@@ -558,7 +571,13 @@ server.registerTool(
     if (args.project) args = { ...args, project: resolveProject(args.project) };
     const limit = args.limit ?? 20;
     const offset = args.offset ?? 0;
-    const ftsQuery = sanitizeFtsQuery(args.query);
+    // args.or (Batch A CLI↔MCP alignment): force OR from start, matching
+    // CLI `search --or`. The default path still does AND with OR-fallback
+    // inside searchObservations when AND returns 0.
+    let ftsQuery = sanitizeFtsQuery(args.query);
+    if (ftsQuery && args.or) {
+      ftsQuery = relaxFtsQueryToOr(ftsQuery) || ftsQuery;
+    }
     const searchType = args.type;
     const currentProject = inferProject();
 
@@ -1083,6 +1102,16 @@ server.registerTool(
   safeHandler(async (args) => {
     if (args.project) args = { ...args, project: resolveProject(args.project) };
     const days = args.days ?? 30;
+
+    // Batch A CLI↔MCP alignment: quality:true → quality dashboard (lesson
+    // rate, LOW_SIGNAL rate, per-type hit/lesson %, top lessons, R-2 watchdog).
+    // Same computation + format as CLI `stats --quality` via lib/stats-quality.mjs.
+    if (args.quality) {
+      const { computeQualityStats, formatQualityReport } = await import('./lib/stats-quality.mjs');
+      const data = computeQualityStats(db, { project: args.project, days });
+      return { content: [{ type: 'text', text: formatQualityReport(data) }] };
+    }
+
     const cutoff = Date.now() - days * 86400000;
     const projectFilter = args.project ? 'AND project = ?' : '';
     const baseParams = args.project ? [args.project] : [];

package/source-files.mjs

@@ -34,6 +34,9 @@ export const SOURCE_FILES = [
   'lib/git-state.mjs',
   'lib/startup-dashboard.mjs',
   'lib/doctor-benchmark.mjs',
+  'lib/doctor-drift.mjs',
+  'lib/stats-quality.mjs',
+  'lib/low-signal-patterns.mjs',
   // v2.32 invited-memory: memdir primitives + adopt/unadopt CLI
   'memdir.mjs',
   'adopt-content.mjs',

package/tool-schemas.mjs

@@ -42,6 +42,7 @@ export const memSearchSchema = {
   offset: coerceInt.pipe(z.number().int().min(0)).optional().describe('Offset for pagination'),
   sort: z.enum(['relevance', 'time', 'importance']).optional().describe('Sort order: relevance (default, BM25), time (newest first), importance (highest first)'),
   include_noise: z.boolean().optional().describe('Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default as they have ~3% access rate'),
+  or: coerceBool.optional().describe('Force OR semantics between query terms from the start (default: AND with automatic OR-fallback when AND returns 0). Aligns with CLI --or.'),
 };
 
 export const memRecentSchema = {
@@ -81,6 +82,7 @@ export const memSaveSchema = {
 export const memStatsSchema = {
   project: z.string().optional().describe('Filter by project'),
   days: coerceInt.pipe(z.number().int().min(1).max(365)).optional().describe('Look back N days (default 30)'),
+  quality: coerceBool.optional().describe('Return quality dashboard (lesson rate, LOW_SIGNAL rate, per-type hit/lesson %, top-accessed lessons, R-2 watchdog) instead of default stats. Aligns with CLI --quality.'),
 };
 
 export const memCompressSchema = {

package/utils.mjs

@@ -4,6 +4,7 @@
 
 import { basename, dirname, resolve, sep } from 'path';
 import { execSync } from 'child_process';
+import { buildLowSignalRegex } from './lib/low-signal-patterns.mjs';
 
 // ─── Re-exports from extracted modules ──────────────────────────────────────
 // Backward compatibility: all consumers import from utils.mjs
@@ -94,8 +95,12 @@ export const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit']);
 //   2. \(error\)$              — title ends with '(error)' (Bug #2 fix: previously this was
 //      inside the prefix group with a meaningless $, so only the exact title '(error)' matched.
 //      Tool-fragment titles like 'gh release list ... (error)' leaked through.)
-// Keep in sync with notLowSignalTitleClause() in scoring-sql.mjs.
-export const LOW_SIGNAL_TITLE = /^(Error (while working|in)|Error: |Modified |Worked on |Reviewed \d+ files:|# |node |npm |npx |\(no description\))|\(error\)$/;
+//
+// β refactor (#7877 applied): derived from lib/low-signal-patterns.mjs so the
+// regex path (this) and the SQL NOT LIKE path (scoring-sql.mjs::notLowSignalTitleClause)
+// and pre-tool-recall.js inline SQL all share one authoritative pattern list.
+// Previously these were hand-mirrored via "keep in sync" comments.
+export const LOW_SIGNAL_TITLE = buildLowSignalRegex();
 
 export function computeRuleImportance(episode) {
   let importance = 1;