claude-mem-lite 2.40.0 → 2.41.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.40.0",
+      "version": "2.41.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.40.0",
+  "version": "2.41.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/cli/activity.mjs

@@ -0,0 +1,113 @@
+// cli/activity.mjs — `claude-mem-lite activity <save|search|recent|show>`.
+// Extracted from mem-cli.mjs (v2.41, god-module split). Thin wrapper over
+// lib/activity.mjs pure functions.
+//
+// Events namespace is separate from observations (schema.mjs v2.31 T6): the
+// activity table stores bugfix/lesson/bug/discovery/refactor/feature/observation/
+// decision events with their own FTS5 index. All mutations go through
+// lib/activity.mjs::saveEvent, which enforces the type CHECK and populates
+// events_fts via triggers.
+
+import { inferProject } from '../utils.mjs';
+import { resolveProject } from '../project-utils.mjs';
+import { parseArgs, out, fail } from './common.mjs';
+
+function formatActivityResults(rows) {
+  if (!rows || rows.length === 0) return '(no events)';
+  return rows.map(r => `#${r.id} [${r.event_type}] ${r.title}`).join('\n');
+}
+
+export async function cmdActivity(db, args) {
+  const sub = args[0];
+  if (!sub) {
+    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show> ...');
+    return;
+  }
+
+  const { positional, flags } = parseArgs(args.slice(1));
+  const { saveEvent, searchEvents, recentEvents, getEvent, EVENT_TYPES } = await import('../lib/activity.mjs');
+  const VALID_EVENT_TYPES = new Set(EVENT_TYPES);
+  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
+
+  if (sub === 'save') {
+    const type = flags.type || 'observation';
+    if (!VALID_EVENT_TYPES.has(type)) {
+      fail(`[mem] activity save: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
+      return;
+    }
+    const title = flags.title || positional.join(' ').trim();
+    if (!title) {
+      fail('[mem] activity save: --title or positional text required');
+      return;
+    }
+    const body = flags.body || null;
+    // Accept both --file (singular, backward compat) and --files (plural,
+    // comma-split, preferred — matches cmdSave). Merge both sources.
+    const filesFromPlural = flags.files && typeof flags.files === 'string'
+      ? flags.files.split(',').map(s => s.trim()).filter(Boolean)
+      : [];
+    const filesFromSingular = flags.file && typeof flags.file === 'string' ? [flags.file] : [];
+    const file_paths_merged = [...filesFromSingular, ...filesFromPlural];
+    const file_paths = file_paths_merged.length > 0 ? file_paths_merged : null;
+    const rawImp = flags.importance !== undefined ? parseInt(flags.importance, 10) : 2;
+    if (flags.importance !== undefined && (isNaN(rawImp) || rawImp < 1 || rawImp > 3)) {
+      fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
+      return;
+    }
+    const id = saveEvent(db, {
+      project,
+      event_type: type,
+      title,
+      body,
+      importance: rawImp,
+      file_paths,
+    });
+    out(JSON.stringify({ ok: true, id }));
+    return;
+  }
+
+  if (sub === 'search') {
+    const q = positional.join(' ');
+    if (!q) {
+      fail('[mem] activity search: query required');
+      return;
+    }
+    const type = flags.type || null;
+    if (type !== null && !VALID_EVENT_TYPES.has(type)) {
+      fail(`[mem] activity search: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
+      return;
+    }
+    const limit = flags.limit !== undefined ? parseInt(flags.limit, 10) : 10;
+    const rows = searchEvents(db, q, { project, type, limit });
+    out(formatActivityResults(rows));
+    return;
+  }
+
+  if (sub === 'recent') {
+    // Accept either `activity recent 5` or `activity recent --limit 5`.
+    const posLimit = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
+    const flagLimit = flags.limit !== undefined ? parseInt(flags.limit, 10) : NaN;
+    const limit = Number.isFinite(posLimit) ? posLimit : (Number.isFinite(flagLimit) ? flagLimit : 20);
+    const type = flags.type || null;
+    if (type !== null && !VALID_EVENT_TYPES.has(type)) {
+      fail(`[mem] activity recent: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
+      return;
+    }
+    const rows = recentEvents(db, { project, type, limit });
+    out(formatActivityResults(rows));
+    return;
+  }
+
+  if (sub === 'show') {
+    const id = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
+    if (!Number.isFinite(id)) {
+      fail('[mem] activity show: numeric id required');
+      return;
+    }
+    const row = getEvent(db, id);
+    out(row ? JSON.stringify(row, null, 2) : 'Not found');
+    return;
+  }
+
+  fail(`[mem] Unknown activity subcommand: ${sub}`);
+}

package/cli/common.mjs

@@ -0,0 +1,105 @@
+// cli/common.mjs — shared helpers used by every per-command file under cli/.
+// Extracted from mem-cli.mjs (v2.41) as first step in the god-module split.
+//
+// Scope: pure utilities only. No DB, no imports from other cli/ files. This
+// module is the single source of truth for stdout/stderr framing, arg parsing,
+// ID-token parsing, and relative-time formatting — every command imports from
+// here so the CLI stays consistent.
+
+// ─── Argument Parsing ────────────────────────────────────────────────────────
+
+/**
+ * Parse argv-style array into { positional, flags }.
+ * `--key value` → flags.key = value; `--flag` (no value) → flags.key = true.
+ * `-h` → flags.help = true.
+ */
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--') && (!next.startsWith('-') || /^-\d/.test(next))) {
+        flags[key] = next;
+        i += 2;
+      } else {
+        flags[key] = true;
+        i++;
+      }
+    } else if (arg === '-h') {
+      flags.help = true;
+      i++;
+    } else {
+      positional.push(arg);
+      i++;
+    }
+  }
+  return { positional, flags };
+}
+
+// ─── Output Helpers ──────────────────────────────────────────────────────────
+
+/** Write a line to stdout. */
+export function out(text) {
+  process.stdout.write(text + '\n');
+}
+
+/** Write a line to stderr and mark process for non-zero exit. */
+export function fail(text) {
+  process.stderr.write(text + '\n');
+  process.exitCode = 1;
+}
+
+// ─── Time Formatting ─────────────────────────────────────────────────────────
+
+/** "just now" / "5m ago" / "3h ago" / "2d ago" relative to now. */
+export function relativeTime(epochMs) {
+  const diff = Date.now() - epochMs;
+  if (diff < 0) return 'just now';
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+/** ISO date string → "YYYY-MM-DD" prefix. */
+export function fmtDateShort(iso) {
+  if (!iso) return '';
+  return iso.slice(0, 10);
+}
+
+// ─── ID Token Parsing ────────────────────────────────────────────────────────
+
+/**
+ * Parse an ID token from a command positional argument.
+ * Accepts: `123`, `#123`, `P#123` / `p123` (prompt), `S#123` / `s123` (session).
+ * @returns {{ source: 'obs'|'session'|'prompt'|null, id: number } | null}
+ *   source===null means no explicit prefix — caller picks default (typically 'obs').
+ */
+export function parseIdToken(raw) {
+  const m = /^([PpSs]?)#?(\d+)$/.exec(String(raw).trim());
+  if (!m) return null;
+  const p = m[1].toUpperCase();
+  const id = parseInt(m[2], 10);
+  if (!Number.isFinite(id) || id <= 0) return null;
+  const source = p === 'P' ? 'prompt' : p === 'S' ? 'session' : null;
+  return { source, id };
+}
+
+/**
+ * Format the shared `probeIdSources` output as CLI hint strings.
+ * Example: ["#5419 (obs)", "P#5417 (prompt)"] — callers join with "; ".
+ */
+export function formatProbeHints(probe) {
+  const hints = [];
+  if (probe.obs.length > 0)     hints.push(`#${probe.obs.join(', #')} (obs)`);
+  if (probe.session.length > 0) hints.push(`S#${probe.session.join(', S#')} (session)`);
+  if (probe.prompt.length > 0)  hints.push(`P#${probe.prompt.join(', P#')} (prompt)`);
+  return hints;
+}

package/cli/doctor.mjs

@@ -0,0 +1,41 @@
+// cli/doctor.mjs — `claude-mem-lite doctor --benchmark|--metrics`.
+// Extracted from mem-cli.mjs (v2.41, god-module split).
+//
+// `doctor` without flags is handled upstream by cli.mjs (routed to install.mjs
+// for install health checks). With --benchmark or --metrics it is routed to
+// mem-cli which delegates to this handler.
+
+import { inferProject } from '../utils.mjs';
+import { out } from './common.mjs';
+
+export async function cmdDoctor(db, args) {
+  if (args.includes('--benchmark')) {
+    const { runBenchmark } = await import('../lib/doctor-benchmark.mjs');
+    const project = inferProject();
+    const result = runBenchmark(db, { project });
+    out(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (args.includes('--metrics')) {
+    // v2.41: aggregate CLAUDE_MEM_METRICS=1 JSONL rows from last N days.
+    // Read-side has no env gate — you can inspect whatever was recorded even
+    // when metrics are currently off. Default window 7 days; --days N override.
+    const { aggregateMetrics, formatSummary, DEFAULT_WINDOW_DAYS } = await import('../lib/metrics.mjs');
+    const { DB_DIR } = await import('../schema.mjs');
+    const daysIdx = args.indexOf('--days');
+    let days = DEFAULT_WINDOW_DAYS;
+    if (daysIdx >= 0 && args[daysIdx + 1]) {
+      const parsed = parseInt(args[daysIdx + 1], 10);
+      if (Number.isFinite(parsed) && parsed > 0 && parsed <= 90) days = parsed;
+    }
+    const agg = aggregateMetrics(DB_DIR, days);
+    if (args.includes('--json')) {
+      out(JSON.stringify(agg, null, 2));
+    } else {
+      out(formatSummary(agg, days));
+    }
+    return;
+  }
+  out('[mem] doctor: supported flags: --benchmark, --metrics [--days N] [--json]');
+  process.exitCode = 1;
+}

package/cli/fts-check.mjs

@@ -0,0 +1,34 @@
+// cli/fts-check.mjs — `claude-mem-lite fts-check <check|rebuild>`.
+// Extracted from mem-cli.mjs (v2.41, god-module split).
+
+import { checkFTSIntegrity, rebuildFTS } from '../schema.mjs';
+import { parseArgs, out, fail } from './common.mjs';
+
+export function cmdFtsCheck(db, args) {
+  const { positional } = parseArgs(args);
+  const action = positional[0];
+  if (!action || !['check', 'rebuild'].includes(action)) {
+    fail('[mem] Usage: mem fts-check <check|rebuild>');
+    return;
+  }
+
+  if (action === 'check') {
+    const result = checkFTSIntegrity(db);
+    if (result.healthy) {
+      out('[mem] FTS5 indexes are healthy — all integrity checks passed.');
+    } else {
+      out(`[mem] FTS5 issues found:`);
+      for (const d of result.details) out(`  ${d}`);
+    }
+    return;
+  }
+
+  if (action === 'rebuild') {
+    const result = rebuildFTS(db);
+    if (result.errors.length > 0) {
+      out(`[mem] Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`);
+    } else {
+      out(`[mem] Successfully rebuilt: ${result.rebuilt.join(', ')}`);
+    }
+  }
+}

package/cli.mjs

@@ -13,9 +13,10 @@ if (cmd === '--version' || cmd === '-v') {
 } else if (cmd === '--help' || cmd === '-h') {
   const { run } = await import('./mem-cli.mjs');
   await run(['help']);
-} else if (cmd === 'doctor' && process.argv.slice(3).includes('--benchmark')) {
-  // doctor --benchmark is a baseline-capture tool, routed through mem-cli (DB layer);
-  // plain `doctor` continues to run the install health-check below.
+} else if (cmd === 'doctor' && (process.argv.slice(3).includes('--benchmark') || process.argv.slice(3).includes('--metrics'))) {
+  // doctor --benchmark / --metrics are DB/metrics inspection tools — routed
+  // through mem-cli (DB layer). Plain `doctor` continues to run the install
+  // health-check below.
   const { run } = await import('./mem-cli.mjs');
   await run(process.argv.slice(2));
 } else if (CLI_COMMANDS.has(cmd)) {

package/hook-memory.mjs

@@ -2,6 +2,8 @@
 // Search past observations for relevant memories to inject as context at user-prompt time.
 
 import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords } from './utils.mjs';
+import { recordMetric } from './lib/metrics.mjs';
+import { DB_DIR } from './schema.mjs';
 
 const MAX_MEMORY_INJECTIONS = 3;
 const MEMORY_LOOKBACK_MS = 60 * 86400000; // 60 days
@@ -29,6 +31,17 @@ function getCoverageThreshold() {
   const n = parseFloat(raw);
   return Number.isFinite(n) && n >= 0 && n <= 1 ? n : 0.4;
 }
+
+// v2.41: cross-project boost (applied to decisions/discoveries from other
+// projects). Default 0.7 = 30% penalty vs same-project hits — tuned for multi-
+// project installs where transferable insights are the minority of matches.
+// Env override `MEM_CROSS_PROJECT_BOOST` ∈ [0, 1]; clamped, invalid → default.
+function getCrossProjectBoost() {
+  const raw = process.env.MEM_CROSS_PROJECT_BOOST;
+  if (raw === undefined || raw === '') return 0.7;
+  const n = parseFloat(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? n : 0.7;
+}
 function extractQueryTerms(text) {
   if (!text) return [];
   const ascii = tokenizeHandoff(text).filter(t => !HANDOFF_STOP_WORDS.has(t));
@@ -36,9 +49,18 @@ function extractQueryTerms(text) {
   try { cjk = extractCjkKeywords(text) || []; } catch { /* CJK extraction best-effort */ }
   return [...new Set([...ascii, ...cjk.map(t => String(t).toLowerCase())])];
 }
+// v2.41: hay spans every FTS column whose BM25 weight is >=5 in OBS_BM25
+// (title=10, subtitle=5, narrative=5, lesson_learned=8). Pre-v2.41 was only
+// title + lesson_learned — rows that matched on narrative but happened to
+// omit the term from title/lesson were dropped by the 0.4 threshold even
+// though FTS ranked them strongly. Narrative is clipped to its first 400 chars
+// because coverage is a membership check, not a frequency count; the tail
+// rarely adds new terms and the worst-case string concatenation stays small.
+const COVERAGE_NARRATIVE_PREFIX = 400;
 function candidateCoverage(row, queryTerms) {
   if (queryTerms.length === 0) return 1.0;
-  const hay = `${row.title || ''} ${row.lesson_learned || ''}`.toLowerCase();
+  const narrativeHead = (row.narrative || '').slice(0, COVERAGE_NARRATIVE_PREFIX);
+  const hay = `${row.title || ''} ${row.subtitle || ''} ${row.lesson_learned || ''} ${narrativeHead}`.toLowerCase();
   let hits = 0;
   for (const t of queryTerms) {
     if (/[^ -~]/.test(t)) {
@@ -68,6 +90,23 @@ const MAX_FILE_RECALL = 2;
 export function searchRelevantMemories(db, userPrompt, project, excludeIds = []) {
   if (!db || !userPrompt || userPrompt.length < 5) return [];
 
+  // v2.41 metrics: record timing + candidate/filter/return counts per call.
+  // Gated by CLAUDE_MEM_METRICS=1 — no-op when disabled (zero hot-path cost).
+  const _t0 = Date.now();
+  let _candidates = 0, _aboveThreshold = 0, _returned = 0, _orFired = false;
+  const _emit = () => {
+    try {
+      recordMetric(DB_DIR, {
+        event: 'inject',
+        durationMs: Date.now() - _t0,
+        candidates: _candidates,
+        aboveThreshold: _aboveThreshold,
+        returned: _returned,
+        orFallback: _orFired,
+      });
+    } catch { /* metric record must not crash the caller */ }
+  };
+
   try {
     const ftsQuery = sanitizeFtsQuery(userPrompt);
     if (!ftsQuery) return [];
@@ -84,7 +123,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // in JS (scored.sort). SELECT exposes both raw BM25 (for sort) and the
     // penalty factor (for the final JS score).
     const selectStmt = db.prepare(`
-      SELECT o.id, o.type, o.title, o.importance, o.lesson_learned, o.project,
+      SELECT o.id, o.type, o.title, o.subtitle, o.narrative, o.importance, o.lesson_learned, o.project,
              ${OBS_BM25} as relevance,
              ${noisePenaltyClause('o')} as noise_penalty
       FROM observations_fts
@@ -121,7 +160,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     let crossUsedOr = false;
     try {
       const crossStmt = db.prepare(`
-        SELECT o.id, o.type, o.title, o.importance, o.lesson_learned, o.project,
+        SELECT o.id, o.type, o.title, o.subtitle, o.narrative, o.importance, o.lesson_learned, o.project,
                ${OBS_BM25} as relevance,
                ${noisePenaltyClause('o')} as noise_penalty
         FROM observations_fts
@@ -146,14 +185,21 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       }
     } catch (e) { debugCatch(e, 'crossProjectSearch'); }
 
-    // Merge and score: same-project full weight, cross-project 0.7x
+    // Merge and score: same-project full weight, cross-project (default 0.7x).
+    // v2.41: cross-project penalty is env-overridable via MEM_CROSS_PROJECT_BOOST
+    // (0..1). Default 0.7 — tuned for typical multi-project installs where
+    // transferable decisions/discoveries are a minority of matches. Set to 1.0
+    // for single-project users (no effective penalty); set lower to tighten
+    // same-project focus in noisy cross-project environments.
+    //
     // OR-fallback results get 0.4x penalty — they matched individual words, not the full intent
     // v26 P0: noise_penalty (from SQL) shrinks high-inject/low-cite rows.
+    const crossPenalty = getCrossProjectBoost();
     const allRows = [...rows.map(r => ({ ...r, _or: usedOrFallback })), ...crossRows.map(r => ({ ...r, _or: crossUsedOr }))];
     const scored = allRows
       .filter(r => !excludeSet.has(r.id))
       .map(r => {
-        const crossProjectPenalty = r.project === project ? 1.0 : 0.7;
+        const crossProjectPenalty = r.project === project ? 1.0 : crossPenalty;
         const orFallbackPenalty = r._or ? 0.4 : 1.0;
         const noisePenalty = typeof r.noise_penalty === 'number' ? r.noise_penalty : 1.0;
         return {
@@ -176,8 +222,11 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     ).get(project)?.c || 0;
     const { TINY, SMALL, MEDIUM, LARGE } = BM25_THRESHOLD;
     const threshold = obsCount < 5 ? TINY : obsCount < 100 ? SMALL : obsCount < 500 ? MEDIUM : LARGE;
+    _candidates = scored.length;
+    _orFired = usedOrFallback || crossUsedOr;
     const aboveThreshold = scored.filter(r => r.score >= threshold);
-    if (aboveThreshold.length === 0) return [];
+    _aboveThreshold = aboveThreshold.length;
+    if (aboveThreshold.length === 0) { _emit(); return []; }
 
     // v27: term-coverage filter — drop candidates whose title+lesson_learned
     // covers <threshold of the query's significant terms. Skipped for
@@ -189,7 +238,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       const queryTerms = extractQueryTerms(userPrompt);
       if (queryTerms.length >= COVERAGE_MIN_QUERY_TERMS) {
         coverageFiltered = aboveThreshold.filter(r => candidateCoverage(r, queryTerms) >= coverageThreshold);
-        if (coverageFiltered.length === 0) return [];
+        if (coverageFiltered.length === 0) { _emit(); return []; }
       }
     }
 
@@ -208,9 +257,12 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       try { bumpStmt.run(now, r.id); } catch {}
     }
 
+    _returned = result.length;
+    _emit();
     return result;
   } catch (e) {
     debugCatch(e, 'searchRelevantMemories');
+    _emit();
     return [];
   }
 }

package/lib/err-sampler.mjs

@@ -0,0 +1,65 @@
+// lib/err-sampler.mjs — sampled append-only log of swallowed errors.
+//
+// Rationale: debugCatch previously only surfaced errors when CLAUDE_MEM_DEBUG
+// was on. In production, silent catches have caused real bugs to slip by —
+// e.g. rebuildVector writing to the wrong column name (`computed_at` vs
+// `created_at_epoch`) was caught by the `catch` in optimize/vector and stayed
+// invisible until R-7 surfaced it (see hook-optimize.mjs header comment and
+// #7556 in project memory).
+//
+// Sampling is per-call Math.random() — no state, no rate limiter. At sample
+// rate 0.01 each debugCatch has a 1% chance to append one JSONL line. Callers
+// don't need to know about it; debugCatch imports this lazily so the fs-less
+// hot path doesn't pay for the module.
+//
+// Gated entirely by CLAUDE_MEM_CATCH_SAMPLE env (0..1). Default off. All
+// failures inside the sampler are swallowed — never crash the caller.
+
+import { appendFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const DAY_MS = 86400000;
+
+function today() {
+  // UTC date string; sharding daily keeps files bounded even at high sample rates.
+  return new Date(Date.now()).toISOString().slice(0, 10);
+}
+
+function parseSampleRate(raw) {
+  if (raw === undefined || raw === '') return 0;
+  const n = parseFloat(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? n : 0;
+}
+
+/**
+ * Sample one caught error into the daily JSONL log.
+ * @param {Error|unknown} e    Caught error
+ * @param {string}        ctx  Context label passed to debugCatch
+ * @param {string}        dbDir ~/.claude-mem-lite (or CLAUDE_MEM_DIR)
+ */
+export function maybeSampleError(e, ctx, dbDir) {
+  try {
+    const rate = parseSampleRate(process.env.CLAUDE_MEM_CATCH_SAMPLE);
+    if (rate <= 0) return;
+    if (Math.random() >= rate) return;
+    if (!dbDir) return;
+
+    const errDir = join(dbDir, 'errors');
+    if (!existsSync(errDir)) mkdirSync(errDir, { recursive: true, mode: 0o700 });
+
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      ctx: String(ctx || '').slice(0, 120),
+      msg: String(e?.message ?? e ?? '').slice(0, 500),
+      stack: typeof e?.stack === 'string' ? e.stack.split('\n').slice(0, 6).join('\n') : undefined,
+    }) + '\n';
+
+    appendFileSync(join(errDir, `${today()}.jsonl`), line, { mode: 0o600 });
+  } catch { /* sampler must never throw */ }
+}
+
+/** Exposed for tests — returns the resolved sample rate in [0,1]. */
+export function _sampleRate() { return parseSampleRate(process.env.CLAUDE_MEM_CATCH_SAMPLE); }
+
+/** Exposed for tests — return daily retention cutoff in ms (14 days). */
+export const SAMPLE_LOG_RETENTION_MS = 14 * DAY_MS;

package/lib/metrics.mjs

@@ -0,0 +1,161 @@
+// lib/metrics.mjs — optional time-series metric sink.
+//
+// Rationale: mem_stats --quality gives a snapshot, not a trend. If search
+// latency degrades or the coverage filter's pass-rate shifts over time, there
+// is no record. Users operating claude-mem-lite in earnest need to see trends.
+//
+// Design:
+//   • CLAUDE_MEM_METRICS=1 enables; default OFF (no fs writes, no overhead).
+//   • Per-event JSONL rows appended to `$DB_DIR/metrics/YYYY-MM-DD.jsonl`.
+//   • Schema is open-ended: { ts, event, durationMs?, ...payload } — each
+//     call-site picks its own payload keys. Readers filter by `event`.
+//   • Read path walks last N days (default 7), parses per-line, aggregates
+//     p50/p95/p99 latencies and count-only metrics per event.
+//
+// All writes best-effort (mkdirSync + appendFileSync wrapped in try). Reads
+// skip malformed lines silently. The module imports nothing heavy so hook
+// cold-start pays near-zero when metrics are disabled.
+
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const DAY_MS = 86400000;
+
+function today() { return new Date(Date.now()).toISOString().slice(0, 10); }
+
+function metricsEnabled() {
+  return process.env.CLAUDE_MEM_METRICS === '1';
+}
+
+/**
+ * Append one metric row to the daily JSONL. No-op when env disabled.
+ * @param {string} dbDir       Claude-mem data dir (DB_DIR).
+ * @param {object} payload     { event: 'inject'|'search'|'save'|..., durationMs?, ...custom }
+ */
+export function recordMetric(dbDir, payload) {
+  if (!metricsEnabled()) return;
+  if (!dbDir || !payload || !payload.event) return;
+  try {
+    const dir = join(dbDir, 'metrics');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const row = { ts: new Date().toISOString(), ...payload };
+    appendFileSync(join(dir, `${today()}.jsonl`), JSON.stringify(row) + '\n', { mode: 0o600 });
+  } catch { /* metrics sink must never crash the caller */ }
+}
+
+/**
+ * Helper: time a synchronous function and record the duration.
+ * Returns the function's return value; on throw, still records durationMs
+ * + error key, then re-throws.
+ *
+ * @template T
+ * @param {string} dbDir
+ * @param {string} event
+ * @param {() => T} fn
+ * @param {object} [extra] Extra keys merged into the metric row
+ * @returns {T}
+ */
+export function timed(dbDir, event, fn, extra = {}) {
+  if (!metricsEnabled()) return fn();
+  const t0 = Date.now();
+  try {
+    const out = fn();
+    recordMetric(dbDir, { event, durationMs: Date.now() - t0, ...extra });
+    return out;
+  } catch (e) {
+    recordMetric(dbDir, { event, durationMs: Date.now() - t0, error: String(e?.message || 'unknown'), ...extra });
+    throw e;
+  }
+}
+
+/** Count of days to aggregate by default in readMetrics / aggregate. */
+export const DEFAULT_WINDOW_DAYS = 7;
+
+function* iterDailyFiles(dbDir, days) {
+  const dir = join(dbDir, 'metrics');
+  if (!existsSync(dir)) return;
+  const cutoff = Date.now() - days * DAY_MS;
+  const files = readdirSync(dir).filter(f => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f));
+  for (const f of files) {
+    const ymd = f.slice(0, 10);
+    const fileMs = Date.parse(ymd + 'T00:00:00Z');
+    if (!Number.isFinite(fileMs) || fileMs < cutoff) continue;
+    yield join(dir, f);
+  }
+}
+
+/**
+ * Stream-read metric rows from the last `days` days.
+ * @yields {object}
+ */
+export function* readMetrics(dbDir, days = DEFAULT_WINDOW_DAYS) {
+  for (const path of iterDailyFiles(dbDir, days)) {
+    let raw;
+    try { raw = readFileSync(path, 'utf8'); } catch { continue; }
+    for (const line of raw.split('\n')) {
+      if (!line) continue;
+      try { yield JSON.parse(line); } catch { /* skip malformed */ }
+    }
+  }
+}
+
+function percentile(sorted, q) {
+  if (sorted.length === 0) return null;
+  const idx = Math.min(sorted.length - 1, Math.floor(q * sorted.length));
+  return sorted[idx];
+}
+
+/**
+ * Aggregate metrics into per-event summaries.
+ * Output shape: { [event]: { count, p50, p95, p99, errors, firstTs, lastTs } }
+ */
+export function aggregateMetrics(dbDir, days = DEFAULT_WINDOW_DAYS) {
+  const byEvent = new Map();
+  for (const row of readMetrics(dbDir, days)) {
+    const ev = row.event;
+    if (!ev) continue;
+    let bucket = byEvent.get(ev);
+    if (!bucket) {
+      bucket = { count: 0, durations: [], errors: 0, firstTs: row.ts, lastTs: row.ts };
+      byEvent.set(ev, bucket);
+    }
+    bucket.count++;
+    if (typeof row.durationMs === 'number' && Number.isFinite(row.durationMs)) {
+      bucket.durations.push(row.durationMs);
+    }
+    if (row.error) bucket.errors++;
+    if (row.ts && row.ts < bucket.firstTs) bucket.firstTs = row.ts;
+    if (row.ts && row.ts > bucket.lastTs) bucket.lastTs = row.ts;
+  }
+  const out = {};
+  for (const [ev, b] of byEvent) {
+    b.durations.sort((a, z) => a - z);
+    out[ev] = {
+      count: b.count,
+      errors: b.errors,
+      p50: percentile(b.durations, 0.5),
+      p95: percentile(b.durations, 0.95),
+      p99: percentile(b.durations, 0.99),
+      firstTs: b.firstTs,
+      lastTs: b.lastTs,
+    };
+  }
+  return out;
+}
+
+/**
+ * Human-readable summary table for `doctor` / `stats` output.
+ * Returns a string block with one line per event.
+ */
+export function formatSummary(aggregated, days = DEFAULT_WINDOW_DAYS) {
+  const events = Object.keys(aggregated).sort();
+  if (events.length === 0) return `[metrics] no data in the last ${days}d (is CLAUDE_MEM_METRICS=1 set?)`;
+  const header = `[metrics] last ${days}d — event · count · p50 / p95 / p99 (ms) · errors`;
+  const lines = [header];
+  for (const ev of events) {
+    const s = aggregated[ev];
+    const lat = s.p50 !== null ? `${s.p50} / ${s.p95} / ${s.p99}` : '(no latency)';
+    lines.push(`  ${ev.padEnd(16)} · n=${String(s.count).padStart(5)} · ${lat} · err=${s.errors}`);
+  }
+  return lines.join('\n');
+}

package/mem-cli.mjs

@@ -3,7 +3,7 @@
 // No MCP SDK or heavy deps — only imports schema.mjs and utils.mjs
 
 import { homedir } from 'os';
-import { ensureDb, DB_PATH, REGISTRY_DB_PATH, checkFTSIntegrity, rebuildFTS } from './schema.mjs';
+import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
 import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, jaccardSimilarity, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, isoWeekKey, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, DEFAULT_DECAY_HALF_LIFE_MS, getCurrentBranch, notLowSignalTitleClause, LOW_SIGNAL_TITLE } from './utils.mjs';
 import { extractCjkLikePatterns } from './nlp.mjs';
 import { resolveProject } from './project-utils.mjs';
@@ -19,88 +19,10 @@ import { probeOtherSources as probeIdSources } from './lib/id-routing.mjs';
 import { basename } from 'path';
 import { readFileSync } from 'fs';
 
-// OBS_BM25, TYPE_DECAY_CASE imported from utils.mjs
-
-// ─── Argument Parsing ────────────────────────────────────────────────────────
-
-function parseArgs(argv) {
-  const positional = [];
-  const flags = {};
-  let i = 0;
-  while (i < argv.length) {
-    const arg = argv[i];
-    if (arg.startsWith('--')) {
-      const key = arg.slice(2);
-      const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith('--') && (!next.startsWith('-') || /^-\d/.test(next))) {
-        flags[key] = next;
-        i += 2;
-      } else {
-        flags[key] = true;
-        i++;
-      }
-    } else if (arg === '-h') {
-      flags.help = true;
-      i++;
-    } else {
-      positional.push(arg);
-      i++;
-    }
-  }
-  return { positional, flags };
-}
-
-// ─── Output Helpers ──────────────────────────────────────────────────────────
-
-function out(text) {
-  process.stdout.write(text + '\n');
-}
-
-function fail(text) {
-  process.stderr.write(text + '\n');
-  process.exitCode = 1;
-}
-
-function relativeTime(epochMs) {
-  const diff = Date.now() - epochMs;
-  if (diff < 0) return 'just now';
-  const mins = Math.floor(diff / 60000);
-  if (mins < 1) return 'just now';
-  if (mins < 60) return `${mins}m ago`;
-  const hours = Math.floor(mins / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  return `${days}d ago`;
-}
-
-function fmtDateShort(iso) {
-  if (!iso) return '';
-  return iso.slice(0, 10); // YYYY-MM-DD
-}
-
-// Parse an ID token from a command positional argument.
-// Accepts: `123`, `#123`, `P#123` / `p123` (prompt), `S#123` / `s123` (session).
-// Returns { source: 'obs'|'session'|'prompt'|null, id: number } or null if unparseable.
-// source===null means no explicit prefix — caller picks default (typically 'obs').
-function parseIdToken(raw) {
-  const m = /^([PpSs]?)#?(\d+)$/.exec(String(raw).trim());
-  if (!m) return null;
-  const p = m[1].toUpperCase();
-  const id = parseInt(m[2], 10);
-  if (!Number.isFinite(id) || id <= 0) return null;
-  const source = p === 'P' ? 'prompt' : p === 'S' ? 'session' : null;
-  return { source, id };
-}
-
-// Format the shared `probeIdSources` output as CLI hint strings.
-// Example: ["#5419 (obs)", "P#5417 (prompt)"] — callers join with "; ".
-function formatProbeHints(probe) {
-  const hints = [];
-  if (probe.obs.length > 0)     hints.push(`#${probe.obs.join(', #')} (obs)`);
-  if (probe.session.length > 0) hints.push(`S#${probe.session.join(', S#')} (session)`);
-  if (probe.prompt.length > 0)  hints.push(`P#${probe.prompt.join(', P#')} (prompt)`);
-  return hints;
-}
+// v2.41: shared CLI helpers extracted to cli/common.mjs. Keep this file as the
+// router + remaining-command bodies during the incremental split. Future work:
+// 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';
 
 // ─── Commands ────────────────────────────────────────────────────────────────
 
@@ -1869,36 +1791,8 @@ function cmdMaintain(db, args) {
   out(`[mem] ${results.join('\n[mem] ')}`);
 }
 
-// ─── FTS Check ───────────────────────────────────────────────────────────────
-
-function cmdFtsCheck(db, args) {
-  const { positional } = parseArgs(args);
-  const action = positional[0];
-  if (!action || !['check', 'rebuild'].includes(action)) {
-    fail('[mem] Usage: mem fts-check <check|rebuild>');
-    return;
-  }
-
-  if (action === 'check') {
-    const result = checkFTSIntegrity(db);
-    if (result.healthy) {
-      out('[mem] FTS5 indexes are healthy — all integrity checks passed.');
-    } else {
-      out(`[mem] FTS5 issues found:`);
-      for (const d of result.details) out(`  ${d}`);
-    }
-    return;
-  }
-
-  if (action === 'rebuild') {
-    const result = rebuildFTS(db);
-    if (result.errors.length > 0) {
-      out(`[mem] Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`);
-    } else {
-      out(`[mem] Successfully rebuilt: ${result.rebuilt.join(', ')}`);
-    }
-  }
-}
+// cmdFtsCheck extracted to cli/fts-check.mjs (v2.41 split).
+import { cmdFtsCheck } from './cli/fts-check.mjs';
 
 // ─── Registry ─────────────────────────────────────────────────────────────────
 
@@ -2352,121 +2246,11 @@ async function cmdOptimize(db, args) {
   if (results.smartCompress) out(`  Smart-compress: ${results.smartCompress.compressed || 0} compressed of ${results.smartCompress.processed || 0} clusters`);
 }
 
-async function cmdDoctor(db, args) {
-  if (args.includes('--benchmark')) {
-    const { runBenchmark } = await import('./lib/doctor-benchmark.mjs');
-    const project = inferProject();
-    const result = runBenchmark(db, { project });
-    out(JSON.stringify(result, null, 2));
-    return;
-  }
-  out('[mem] doctor: supported flags: --benchmark');
-  process.exitCode = 1;
-}
+// cmdDoctor extracted to cli/doctor.mjs (v2.41 split).
+import { cmdDoctor } from './cli/doctor.mjs';
 
-// ─── Activity (T7 v2.31) ─────────────────────────────────────────────────────
-// Separate namespace from observations. Handlers are thin wrappers over
-// lib/activity.mjs pure functions; imported lazily to match the doctor pattern.
-
-function formatActivityResults(rows) {
-  if (!rows || rows.length === 0) return '(no events)';
-  return rows.map(r => `#${r.id} [${r.event_type}] ${r.title}`).join('\n');
-}
-
-async function cmdActivity(db, args) {
-  const sub = args[0];
-  if (!sub) {
-    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show> ...');
-    return;
-  }
-
-  const { positional, flags } = parseArgs(args.slice(1));
-  const { saveEvent, searchEvents, recentEvents, getEvent, EVENT_TYPES } = await import('./lib/activity.mjs');
-  const VALID_EVENT_TYPES = new Set(EVENT_TYPES);
-  const project = flags.project ? resolveProject(db, flags.project) : inferProject();
-
-  if (sub === 'save') {
-    const type = flags.type || 'observation';
-    if (!VALID_EVENT_TYPES.has(type)) {
-      fail(`[mem] activity save: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
-      return;
-    }
-    const title = flags.title || positional.join(' ').trim();
-    if (!title) {
-      fail('[mem] activity save: --title or positional text required');
-      return;
-    }
-    const body = flags.body || null;
-    // Accept both --file (singular, backward compat) and --files (plural,
-    // comma-split, preferred — matches cmdSave). Merge both sources.
-    const filesFromPlural = flags.files && typeof flags.files === 'string'
-      ? flags.files.split(',').map(s => s.trim()).filter(Boolean)
-      : [];
-    const filesFromSingular = flags.file && typeof flags.file === 'string' ? [flags.file] : [];
-    const file_paths_merged = [...filesFromSingular, ...filesFromPlural];
-    const file_paths = file_paths_merged.length > 0 ? file_paths_merged : null;
-    const rawImp = flags.importance !== undefined ? parseInt(flags.importance, 10) : 2;
-    if (flags.importance !== undefined && (isNaN(rawImp) || rawImp < 1 || rawImp > 3)) {
-      fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
-      return;
-    }
-    const id = saveEvent(db, {
-      project,
-      event_type: type,
-      title,
-      body,
-      importance: rawImp,
-      file_paths,
-    });
-    out(JSON.stringify({ ok: true, id }));
-    return;
-  }
-
-  if (sub === 'search') {
-    const q = positional.join(' ');
-    if (!q) {
-      fail('[mem] activity search: query required');
-      return;
-    }
-    const type = flags.type || null;
-    if (type !== null && !VALID_EVENT_TYPES.has(type)) {
-      fail(`[mem] activity search: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
-      return;
-    }
-    const limit = flags.limit !== undefined ? parseInt(flags.limit, 10) : 10;
-    const rows = searchEvents(db, q, { project, type, limit });
-    out(formatActivityResults(rows));
-    return;
-  }
-
-  if (sub === 'recent') {
-    // Accept either `activity recent 5` or `activity recent --limit 5`.
-    const posLimit = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
-    const flagLimit = flags.limit !== undefined ? parseInt(flags.limit, 10) : NaN;
-    const limit = Number.isFinite(posLimit) ? posLimit : (Number.isFinite(flagLimit) ? flagLimit : 20);
-    const type = flags.type || null;
-    if (type !== null && !VALID_EVENT_TYPES.has(type)) {
-      fail(`[mem] activity recent: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
-      return;
-    }
-    const rows = recentEvents(db, { project, type, limit });
-    out(formatActivityResults(rows));
-    return;
-  }
-
-  if (sub === 'show') {
-    const id = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
-    if (!Number.isFinite(id)) {
-      fail('[mem] activity show: numeric id required');
-      return;
-    }
-    const row = getEvent(db, id);
-    out(row ? JSON.stringify(row, null, 2) : 'Not found');
-    return;
-  }
-
-  fail(`[mem] Unknown activity subcommand: ${sub}`);
-}
+// cmdActivity (T7 v2.31) extracted to cli/activity.mjs (v2.41 split).
+import { cmdActivity } from './cli/activity.mjs';
 
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.40.0",
+  "version": "2.41.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -52,6 +52,13 @@
     "lib/low-signal-patterns.mjs",
     "lib/citation-tracker.mjs",
     "lib/id-routing.mjs",
+    "lib/err-sampler.mjs",
+    "lib/metrics.mjs",
+    "cli/common.mjs",
+    "cli/fts-check.mjs",
+    "cli/doctor.mjs",
+    "cli/activity.mjs",
+    "server/fts-check.mjs",
     "registry.mjs",
     "registry-retriever.mjs",
     "registry-indexer.mjs",

package/schema.mjs

@@ -13,7 +13,15 @@ export const DB_PATH = join(DB_DIR, 'claude-mem-lite.db');
 export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
 
 // Increment when schema changes (tables, columns, indexes, FTS, migrations)
-export const CURRENT_SCHEMA_VERSION = 26;
+//
+// v27 (v2.41): observations_au / session_summaries_au / user_prompts_au
+// triggers scoped to FTS-indexed columns via `AFTER UPDATE OF <cols>`. Before
+// v27 the _au triggers fired on ANY row UPDATE — access_count / injection_count
+// / last_accessed_at bumps (#8100 separation notwithstanding) caused wasted
+// FTS delete+reinsert cycles and amplified SQLITE_CORRUPT_VTAB blast radius
+// (project_non_obvious.md). Migration drops the old triggers once and lets
+// ensureFTS recreate them with the scoped form.
+export const CURRENT_SCHEMA_VERSION = 27;
 
 const CORE_SCHEMA = `
   CREATE TABLE IF NOT EXISTS sdk_sessions (
@@ -127,11 +135,27 @@ const MIGRATIONS = [
  * The DB should have foreign_keys OFF before calling (enabled after dedup migration).
  */
 export function initSchema(db) {
-  // Fast path: skip all migrations if schema is already at current version
+  // Fast path: skip all migrations if schema is already at current version.
+  // Forward-incompat guard: if persisted version is NEWER than this build's
+  // CURRENT_SCHEMA_VERSION, a newer claude-mem-lite wrote it; the current
+  // (older) binary would silently re-apply old migrations over a newer layout.
+  // Throw loudly instead — `claude-mem-lite doctor` / reinstall is the path.
   try {
     const row = db.prepare('SELECT version FROM schema_version LIMIT 1').get();
-    if (row && row.version === CURRENT_SCHEMA_VERSION) return db;
-  } catch { /* table may not exist yet */ }
+    if (row && typeof row.version === 'number') {
+      if (row.version === CURRENT_SCHEMA_VERSION) return db;
+      if (row.version > CURRENT_SCHEMA_VERSION) {
+        throw new Error(
+          `DB schema is v${row.version} but this claude-mem-lite binary supports up to v${CURRENT_SCHEMA_VERSION}. ` +
+          `A newer version wrote this DB; upgrade claude-mem-lite (npm i -g claude-mem-lite@latest) or point CLAUDE_MEM_DIR to a fresh directory.`
+        );
+      }
+    }
+  } catch (e) {
+    // schema_version table absent = first init — proceed to create it.
+    // Real forward-incompat throw above must propagate.
+    if (e.message?.startsWith('DB schema is v')) throw e;
+  }
 
   // Create core tables
   db.exec(CORE_SCHEMA);
@@ -241,6 +265,25 @@ export function initSchema(db) {
     }
   } catch { /* non-critical — ensureFTS will create if missing */ }
 
+  // v27 migration: drop legacy _au triggers that fire on ANY row UPDATE so
+  // ensureFTS reinstates them with `AFTER UPDATE OF <fts_cols>`. Trigger fires
+  // only when FTS-indexed columns change after this migration — access_count
+  // / injection_count / last_accessed_at bumps no longer thrash the FTS index.
+  // Conditional per #7647: only drop when the stored DDL lacks the scoped
+  // `UPDATE OF` clause (handles re-run + fresh-DB cases).
+  for (const [trg, tbl] of [
+    ['observations_au',      'observations'],
+    ['session_summaries_au', 'session_summaries'],
+    ['user_prompts_au',      'user_prompts'],
+  ]) {
+    try {
+      const row = db.prepare(`SELECT sql FROM sqlite_master WHERE type='trigger' AND name=?`).get(trg);
+      if (row && row.sql && !/\bAFTER\s+UPDATE\s+OF\s+/i.test(row.sql)) {
+        db.exec(`DROP TRIGGER IF EXISTS ${tbl}_au`);
+      }
+    } catch { /* non-critical — ensureFTS will recreate */ }
+  }
+
   // FTS5 full-text search tables + triggers (idempotent)
   ensureFTS(db, 'observations_fts', 'observations', OBS_FTS_COLUMNS);
   ensureFTS(db, 'session_summaries_fts', 'session_summaries', ['request', 'investigated', 'learned', 'completed', 'next_steps', 'notes', 'remaining_items']);
@@ -523,10 +566,8 @@ export function checkFTSIntegrity(db) {
 }
 
 export function ensureFTS(db, ftsName, tableName, columns) {
-  const exists = db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).get(ftsName);
-  if (exists) return;
-
-  // Validate identifiers to prevent SQL injection
+  // Validate identifiers to prevent SQL injection (done upfront; both
+  // branches below use these identifiers in string-interpolated SQL)
   const idRe = /^[a-z][a-z0-9_]*$/;
   if (!idRe.test(ftsName) || !idRe.test(tableName) || !columns.every(c => idRe.test(c))) {
     throw new Error(`Invalid identifier in ensureFTS: ${ftsName}, ${tableName}`);
@@ -535,18 +576,30 @@ export function ensureFTS(db, ftsName, tableName, columns) {
   const colList = columns.join(', ');
   const newVals = columns.map(c => `new.${c}`).join(', ');
   const oldVals = columns.map(c => `old.${c}`).join(', ');
-  db.exec(`
-    CREATE VIRTUAL TABLE ${ftsName} USING fts5(${colList}, content='${tableName}', content_rowid='id');
 
-    CREATE TRIGGER ${tableName}_ai AFTER INSERT ON ${tableName} BEGIN
+  const ftsExists = db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).get(ftsName);
+  if (!ftsExists) {
+    db.exec(`CREATE VIRTUAL TABLE ${ftsName} USING fts5(${colList}, content='${tableName}', content_rowid='id')`);
+  }
+
+  // Triggers created / recreated independently of FTS table existence so that
+  // schema migrations (e.g. v27 scope-to-FTS-columns) can drop the old _au
+  // trigger and this function reinstates it with the current template on the
+  // next ensureDb(). Per #7647: keep rebuild conditional — IF NOT EXISTS gates
+  // writes when the current definition already matches.
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS ${tableName}_ai AFTER INSERT ON ${tableName} BEGIN
       INSERT INTO ${ftsName}(rowid, ${colList}) VALUES (new.id, ${newVals});
     END;
 
-    CREATE TRIGGER ${tableName}_ad AFTER DELETE ON ${tableName} BEGIN
+    CREATE TRIGGER IF NOT EXISTS ${tableName}_ad AFTER DELETE ON ${tableName} BEGIN
       INSERT INTO ${ftsName}(${ftsName}, rowid, ${colList}) VALUES('delete', old.id, ${oldVals});
     END;
 
-    CREATE TRIGGER ${tableName}_au AFTER UPDATE ON ${tableName} BEGIN
+    -- v27: AFTER UPDATE OF <fts_cols> — trigger fires only when an FTS-indexed
+    -- column changes. Prevents access_count / injection_count / last_accessed_at
+    -- UPDATEs from firing wasteful FTS delete+reinsert (project_non_obvious.md).
+    CREATE TRIGGER IF NOT EXISTS ${tableName}_au AFTER UPDATE OF ${colList} ON ${tableName} BEGIN
       INSERT INTO ${ftsName}(${ftsName}, rowid, ${colList}) VALUES('delete', old.id, ${oldVals});
       INSERT INTO ${ftsName}(rowid, ${colList}) VALUES (new.id, ${newVals});
     END;

package/server/fts-check.mjs

@@ -0,0 +1,33 @@
+// server/fts-check.mjs — MCP `mem_fts_check` handler.
+// Extracted from server.mjs (v2.41, god-module split).
+//
+// Pure delegate to schema.mjs helpers; Zod filters args.action before we get
+// here (see memFtsCheckSchema). No shared state beyond the `db` handle passed
+// in from the server-process module scope.
+
+import { checkFTSIntegrity, rebuildFTS } from '../schema.mjs';
+
+/**
+ * Handle `mem_fts_check({ action })`. Returns an MCP content wrapper.
+ * @param {import('better-sqlite3').Database} db
+ * @param {{ action: 'check' | 'rebuild' }} args
+ */
+export function handleMemFtsCheck(db, args) {
+  if (args.action === 'check') {
+    const result = checkFTSIntegrity(db);
+    return {
+      content: [{
+        type: 'text',
+        text: result.healthy
+          ? 'FTS5 indexes are healthy — all integrity checks passed.'
+          : `FTS5 issues found:\n${result.details.join('\n')}`,
+      }],
+    };
+  }
+  // args.action === 'rebuild' (Zod enum enforces one of the two)
+  const result = rebuildFTS(db);
+  const summary = result.errors.length > 0
+    ? `Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`
+    : `Successfully rebuilt: ${result.rebuilt.join(', ')}`;
+  return { content: [{ type: 'text', text: summary }] };
+}

package/server.mjs

@@ -8,7 +8,7 @@ import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, getCurrentBranch, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause, LOW_SIGNAL_TITLE } from './utils.mjs';
 import { extractCjkLikePatterns } from './nlp.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
-import { ensureDb, DB_PATH, REGISTRY_DB_PATH, checkFTSIntegrity, rebuildFTS } from './schema.mjs';
+import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
 import { effectiveQuiet } from './hook-shared.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
@@ -2107,6 +2107,8 @@ server.registerTool(
 );
 
 // ─── Tool: mem_fts_check ─────────────────────────────────────────────────────
+// Handler extracted to server/fts-check.mjs (v2.41 split).
+import { handleMemFtsCheck } from './server/fts-check.mjs';
 
 server.registerTool(
   'mem_fts_check',
@@ -2114,22 +2116,7 @@ server.registerTool(
     description: descriptionOf('mem_fts_check'),
     inputSchema: memFtsCheckSchema,
   },
-  safeHandler(async (args) => {
-    // T3-P2-C: Zod `action: z.enum(['check','rebuild'])` filters any other value before we
-    // reach this handler, so there's no "Unknown action" fallback to write.
-    if (args.action === 'check') {
-      const result = checkFTSIntegrity(db);
-      return { content: [{ type: 'text', text: result.healthy
-        ? 'FTS5 indexes are healthy — all integrity checks passed.'
-        : `FTS5 issues found:\n${result.details.join('\n')}` }] };
-    }
-    // args.action === 'rebuild'
-    const result = rebuildFTS(db);
-    const summary = result.errors.length > 0
-      ? `Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`
-      : `Successfully rebuilt: ${result.rebuilt.join(', ')}`;
-    return { content: [{ type: 'text', text: summary }] };
-  })
+  safeHandler(async (args) => handleMemFtsCheck(db, args))
 );
 
 // ─── Tool: mem_browse ────────────────────────────────────────────────────────

package/source-files.mjs

@@ -39,6 +39,14 @@ export const SOURCE_FILES = [
   'lib/low-signal-patterns.mjs',
   'lib/citation-tracker.mjs',
   'lib/id-routing.mjs',
+  'lib/err-sampler.mjs',
+  'lib/metrics.mjs',
+  // v2.41 god-module split — mem-cli.mjs router + per-cmd handlers under cli/
+  'cli/common.mjs',
+  'cli/fts-check.mjs',
+  'cli/doctor.mjs',
+  'cli/activity.mjs',
+  'server/fts-check.mjs',
   // v2.32 invited-memory: memdir primitives + adopt/unadopt CLI
   'memdir.mjs',
   'adopt-content.mjs',

package/utils.mjs

@@ -235,7 +235,11 @@ export function debugLog(level, context, msg) {
 
 /**
  * Log a caught error at ERROR level (includes stack trace when available).
- * Gated by CLAUDE_MEM_DEBUG. Use in catch blocks for non-fatal errors.
+ * Gated by CLAUDE_MEM_DEBUG for stderr output. Separately, if
+ * `CLAUDE_MEM_CATCH_SAMPLE` (float 0..1) is set, a random fraction of caught
+ * errors get appended to `$DB_DIR/errors/YYYY-MM-DD.jsonl` — observable
+ * residue for otherwise-silent swallowed errors (see lib/err-sampler.mjs).
+ * Use in catch blocks for non-fatal errors.
  * @param {Error|unknown} e The caught error
  * @param {string} context Module or function name for attribution
  */
@@ -244,6 +248,20 @@ export function debugCatch(e, context) {
     const ts = new Date().toISOString();
     console.error(`[claude-mem-lite] [${ts}] [ERROR] ${context}:`, e?.stack || e?.message || e);
   }
+  // Sampled-to-disk surface for post-mortem. Lazy-loaded so fs-less paths
+  // don't pay the module cost; wrapped in try so sampler faults never crash
+  // the caller (debugCatch is the error-handler-of-last-resort path).
+  if (process.env.CLAUDE_MEM_CATCH_SAMPLE) {
+    (async () => {
+      try {
+        const [{ maybeSampleError }, { DB_DIR }] = await Promise.all([
+          import('./lib/err-sampler.mjs'),
+          import('./schema.mjs'),
+        ]);
+        maybeSampleError(e, context, DB_DIR);
+      } catch { /* sampler dynamic-import fault must not propagate */ }
+    })();
+  }
 }
 
 // ─── JSON Parsing ────────────────────────────────────────────────────────────