claude-mem-lite 2.39.1 → 2.41.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.39.1",
+      "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.39.1",
+  "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;