claude-mem-lite 3.59.0 → 3.60.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'citation-stats', 'delete', 'update', 'export', 'restore', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'import-jsonl', 'enrich', 'activity', 'adopt', 'unadopt', 'memdir-audit', 'defer', 'help']);
-const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'repair', 'release']);
+const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'repair', 'rebuild-binding', 'release']);
 
 const cmd = process.argv[2];
 

package/install.mjs

@@ -40,7 +40,8 @@ const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 import { RESOURCE_METADATA } from './install-metadata.mjs';
 import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
-import { probeBetterSqlite3Binding, ensureBetterSqlite3Working } from './lib/binding-probe.mjs';
+import { probeBetterSqlite3Binding, ensureBetterSqlite3Working, NATIVE_BINDING_REBUILD_CMD } from './lib/binding-probe.mjs';
+import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { acquireLock } from './lib/proc-lock.mjs';
 import { atomicWriteFileSync } from './lib/atomic-write.mjs';
@@ -1447,6 +1448,23 @@ async function doctor() {
     ok('Hook self-heal: no recent silent hook breakage');
   }
 
+  // Native DB binding. Two signals, because they answer different questions:
+  // the marker says "hooks have been failing" (possibly for days, since the hint
+  // is 6h-rate-limited stderr nobody reads), the live probe says "is it broken
+  // right now". A Node upgrade breaks every DB-touching path at once, so this is
+  // the single highest-value line in doctor when it fires.
+  const breakage = readNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
+  const bindingProbe = await probeBetterSqlite3Binding(bindingHostDir());
+  if (!bindingProbe.ok) {
+    fail(`Native DB binding: unusable (${String(bindingProbe.error).split('\n')[0]}) — run \`node ${join(PROJECT_DIR, 'cli.mjs')} rebuild-binding\``);
+    issues++;
+  } else if (breakage) {
+    const ageH = Math.round((Date.now() - (breakage.ts || 0)) / 3600000);
+    dwarn(`Native DB binding: healthy now, but a fire failed ~${ageH}h ago (${breakage.reason || 'unknown'}) — stale marker clears on the next successful rebuild-binding`);
+  } else {
+    ok(`Native DB binding: loadable on Node ${process.version}`);
+  }
+
   // Plugin/hook lifecycle state
   const settings = readSettings();
   const hasHooks = hasMemHooksConfigured(settings);
@@ -2129,6 +2147,51 @@ function regenerateLockfile() {
 
 // ─── Main ───────────────────────────────────────────────────────────────────
 
+// An install can own MORE THAN ONE better-sqlite3 tree (dev repo, ~/.claude-mem-lite,
+// the plugin cache), each with its own .node — and only the one the RUNNING code
+// resolves matters, i.e. the one next to this file. Rebuilding the wrong tree
+// reports success while every hook keeps failing. Fall back to INSTALL_DIR when
+// this file sits in a source-only layout with no deps of its own.
+function bindingHostDir() {
+  return existsSync(join(PROJECT_DIR, 'node_modules', 'better-sqlite3')) ? PROJECT_DIR : INSTALL_DIR;
+}
+
+// Local, network-free repair for an unusable native DB binding — the Node-upgrade
+// fault (ABI 127 → 137) that `repair` is the wrong size for: repair re-downloads
+// and signature-verifies a whole GitHub release and fails closed offline, while
+// this recompiles one module in place. Named in the hook hint, run unattended by
+// scripts/hook-launcher.mjs at session-start, and usable by hand.
+//
+// Takes the same install.lock as the install write phase and launch.mjs's rebuild:
+// two concurrent rebuilds can clobber the .node mid-compile. A live peer → report
+// and exit 0 (it is doing this very work), never race it.
+async function rebuildBinding() {
+  const host = bindingHostDir();
+  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock'));
+  if (!release) {
+    // NOT exit 0: skipping is not healing. Callers key their state on the exit
+    // code — a false success would let the launcher drop its cooldown and the
+    // CLI re-exec into the same broken binding.
+    console.error('[install] Another install/repair is in progress — it owns the rebuild; skipping.');
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const verify = await ensureBetterSqlite3Working(host);
+    if (verify.ok) {
+      ok(`better-sqlite3 binding ${verify.action} for Node ${process.version} (${host})`);
+      // The fault is gone → drop the marker so session-start stops retrying.
+      clearNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
+    } else {
+      fail(`better-sqlite3 binding still unusable: ${verify.error}`);
+      log(`Try manually: cd ${host} && ${NATIVE_BINDING_REBUILD_CMD}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    release();
+  }
+}
+
 // Cross-process gate around the install write phase. repair() is intentionally
 // NOT locked here: it spawns `install.mjs install` as a child, which takes this
 // lock — locking the parent too would deadlock. A live peer (another session's
@@ -2173,6 +2236,9 @@ export async function main(argv = process.argv.slice(2)) {
     case 'repair':
       await repair();
       break;
+    case 'rebuild-binding':
+      await rebuildBinding();
+      break;
     case 'release':
       syncVersions();
       if (!flags.has('--no-lock')) regenerateLockfile();
@@ -2203,6 +2269,7 @@ Usage:
   node install.mjs cleanup-hooks      Remove only claude-mem-lite hooks from settings.json
   node install.mjs self-update         Check for and install updates
   node install.mjs repair             Recover a broken install: download latest tarball, re-run install
+  node install.mjs rebuild-binding    Recompile better-sqlite3 for the running Node (fixes "NODE_MODULE_VERSION" after a Node upgrade)
   node install.mjs release            Sync versions (plugin/marketplace/CLAUDE.md) + regen lockfile via npm@10.9.2 (use --no-lock to skip lock regen)
 
   npx claude-mem-lite                 Install via npx (one-liner)

package/lib/activity.mjs

@@ -7,7 +7,9 @@
 import { sanitizeFtsQuery } from '../utils.mjs';
 import { scrubRecord } from './scrub-record.mjs';
 import { saveObservation } from './save-observation.mjs';
-import { notLowSignalTitleClause } from '../scoring-sql.mjs';
+// Pure title-only builder: this query runs on the EVENTS table, which has no
+// lesson_learned column — the lesson-escape variant would be a SQL error here.
+import { buildNotLowSignalSql } from './low-signal-patterns.mjs';
 import { OBS_TYPE_SET } from './obs-types.mjs';
 
 // Observation types (mirrors the observations.type enum) — events carry a wider
@@ -150,7 +152,7 @@ export function promoteInsightEvents(db, { project = null, minImportance = 2, ex
     FROM events
     WHERE body IS NOT NULL AND TRIM(body) != '' AND importance >= ?
       AND superseded_at_epoch IS NULL
-      AND ${notLowSignalTitleClause('')}
+      AND ${buildNotLowSignalSql('')}
       ${projClause}
     ORDER BY created_at_epoch DESC LIMIT ?
   `;

package/lib/binding-probe.mjs

@@ -6,10 +6,51 @@
 // Node v24), and the presence of node_modules/better-sqlite3/ on disk is not
 // sufficient — the binding can be present-but-stale after a Node upgrade.
 
-import { execSync } from 'node:child_process';
+import { execSync, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 
+// npm >= 12 blocks lifecycle scripts by default, so a plain `npm rebuild` exits 0
+// WITHOUT compiling — see the rebuild() comment below. Single home for the one
+// command that actually works, so hints, docs and heal paths cannot drift apart.
+export const NATIVE_BINDING_REBUILD_CMD = 'npm rebuild better-sqlite3 --dangerously-allow-all-scripts';
+
+// Set on a re-exec'd child so one failed heal cannot fork-bomb the CLI.
+export const BINDING_HEAL_GUARD_ENV = 'CLAUDE_MEM_BINDING_HEALED';
+
+// The native-binding fault family, in the four shapes it actually reaches callers:
+//   • ERR_DLOPEN_FAILED            — Node's code for a failed dlopen (ABI mismatch)
+//   • NODE_MODULE_VERSION N vs M   — the ABI text itself (some throws carry no code)
+//   • Could not locate the bindings file — build/Release missing or never compiled
+//   • Module did not self-register — the .node was REPLACED under a process that
+//     already dlopen'd the old one; only a fresh process recovers (hence the
+//     re-exec in healAndReexec, not an in-process retry)
+// Deliberately NARROW: a rebuild cannot fix DB corruption or a missing data dir,
+// and misclassifying those would burn a 30s npm run on every fire.
+const NATIVE_BINDING_PATTERNS = [
+  /NODE_MODULE_VERSION/,
+  /Could not locate the bindings file/i,
+  /did not self-register/i,
+  /invalid ELF header/i,
+];
+
+/**
+ * True when `err` means "the better-sqlite3 native binding is unusable and a
+ * rebuild is the right repair".
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isNativeBindingError(err) {
+  if (!err) return false;
+  if (err.code === 'ERR_DLOPEN_FAILED') return true;
+  // `err ?? ''` covers a thrown STRING: recordHookError accepts any thrown value
+  // and already normalizes that shape for its log, so the classifier must not
+  // silently read undefined and miss it.
+  const msg = String(err.message ?? err ?? '');
+  return NATIVE_BINDING_PATTERNS.some((re) => re.test(msg));
+}
+
 /**
  * Probe better-sqlite3's native binding by importing it from `installDir`'s
  * node_modules and opening an in-memory DB. Returns {ok, error?}.
@@ -43,7 +84,11 @@ export async function probeBetterSqlite3Binding(installDir) {
  */
 export async function ensureBetterSqlite3Working(installDir, deps = {}) {
   const probe = deps.probe || (() => probeBetterSqlite3Binding(installDir));
-  const exec = deps.exec || execSync;
+  // Bounded by default: a node-gyp fallback that stalls (no compiler, a hung
+  // registry fetch) must not hang the caller forever — the CLI blocks a user at
+  // the terminal, and scripts/setup.sh passes an even tighter 20s cap because it
+  // runs under a hook timeout. Callers needing a different budget inject `exec`.
+  const exec = deps.exec || ((cmd, opts) => execSync(cmd, { timeout: 240_000, ...opts }));
   const rebuild = deps.rebuild || (async () => {
     // npm >= 12 blocks install/lifecycle scripts by default (the `allow-scripts`
     // allowlist ships empty). better-sqlite3's install step
@@ -57,7 +102,7 @@ export async function ensureBetterSqlite3Working(installDir, deps = {}) {
     // npm has no such gate and treats the unknown flag as an ignored config; if
     // it instead errors on the flag, fall back to the plain rebuild.
     try {
-      exec('npm rebuild better-sqlite3 --dangerously-allow-all-scripts', { cwd: installDir, stdio: 'pipe' });
+      exec(NATIVE_BINDING_REBUILD_CMD, { cwd: installDir, stdio: 'pipe' });
     } catch {
       exec('npm rebuild better-sqlite3', { cwd: installDir, stdio: 'pipe' });
     }
@@ -77,3 +122,46 @@ export async function ensureBetterSqlite3Working(installDir, deps = {}) {
 
   return { ok: false, error: second.error || first.error };
 }
+
+/**
+ * Foreground heal for a user-invoked process (the CLI): rebuild the binding,
+ * then RE-EXEC this process with its original argv and return the child's exit
+ * code. The re-exec is not a convenience — better-sqlite3 dlopen's its .node
+ * lazily and caches the handle, so a process that has already hit the stale
+ * binary cannot use the fresh one: retrying in-process fails with "Module did
+ * not self-register" (observed 2026-08-13 while healing this exact fault).
+ *
+ * Refuses to act when the guard env is already set, so a heal that does not
+ * actually fix the binding cannot spawn an unbounded chain of children.
+ *
+ * @param {{installDir?: string, argv?: string[], env?: Record<string,string|undefined>, ensure?: () => Promise<{ok: boolean, action?: string, error?: string}>, reexec?: (argv: string[], env: Record<string,string|undefined>) => number, log?: (msg: string) => void}} opts
+ * @returns {Promise<{healed: true, exitCode: number} | {healed: false, reason: string, error?: string}>}
+ */
+export async function healAndReexec(opts) {
+  const {
+    installDir,
+    argv = process.argv,
+    env = process.env,
+    log = () => {},
+  } = opts;
+  const ensure = opts.ensure || (() => ensureBetterSqlite3Working(installDir));
+  const reexec = opts.reexec || ((childArgv, childEnv) => {
+    const r = spawnSync(childArgv[0], childArgv.slice(1), { stdio: 'inherit', env: childEnv });
+    return typeof r.status === 'number' ? r.status : 1;
+  });
+
+  if (env[BINDING_HEAL_GUARD_ENV]) return { healed: false, reason: 'already-attempted' };
+
+  log(`native DB binding unusable — rebuilding for this Node (${process.version})…`);
+  let verify;
+  try {
+    verify = await ensure();
+  } catch (e) {
+    return { healed: false, reason: 'rebuild-failed', error: e.message };
+  }
+  if (!verify.ok) return { healed: false, reason: 'rebuild-failed', error: verify.error };
+
+  log('binding rebuilt — retrying');
+  const exitCode = reexec(argv, { ...env, [BINDING_HEAL_GUARD_ENV]: '1' });
+  return { healed: true, exitCode };
+}

package/lib/hook-telemetry.mjs

@@ -20,6 +20,11 @@
 
 import { appendFileSync, mkdirSync, existsSync, readdirSync, readFileSync, statSync, unlinkSync } from 'fs';
 import { join } from 'path';
+// Both are pure-`node:`-static modules (better-sqlite3 is only createRequire'd
+// lazily inside binding-probe's functions), so this keeps the "usable from the
+// lightweight standalone scripts" property stated above.
+import { isNativeBindingError } from './binding-probe.mjs';
+import { recordNativeBindingBreakage } from './native-binding-hint.mjs';
 
 const DAY_MS = 86400000;
 const RETENTION_MS = 14 * DAY_MS;
@@ -82,6 +87,18 @@ export function recordHookError(scope, err, runtimeDir, ctx) {
     appendFileSync(join(dir, `${today()}.jsonl`), line, { mode: 0o600 });
     // Amortized retention sweep: 14-day window kept clean without a cron.
     pruneOldShards(dir);
+
+    // Every hook script funnels its failures through here — including the
+    // STANDALONE ones (scripts/pre-tool-recall.js, scripts/pre-skill-bridge.js)
+    // that never import hook.mjs and so never reach its dispatch catch. That gap
+    // is why the 2026-08-13 outage stayed invisible: 78 of that day's 79 entries
+    // were `pre-recall:db-open`, i.e. the ONE path whose errors nothing but this
+    // log could see. Flagging the native-binding family here — rather than at
+    // each call site — is what makes the session-start heal fire no matter which
+    // script hits the stale binding first.
+    if (isNativeBindingError(err)) {
+      recordNativeBindingBreakage(runtimeDir, { reason: String(err?.message ?? err ?? ''), event: String(scope || '') });
+    }
   } catch { /* recorder must never throw */ }
 }
 

package/lib/low-signal-patterns.mjs

@@ -50,13 +50,29 @@ export function buildLowSignalRegex() {
  * 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.
  *
+ * `lessonEscape` (2026-07-24 audit P1, D#11): retrieval consumers on the
+ * observations table pass `{ lessonEscape: true }` to admit rows whose title
+ * matches a LOW_SIGNAL pattern but which carry a real lesson_learned — the
+ * read-side counterpart of the isNoiseObservation/capNoiseImportance write-side
+ * signal escapes. Without it, a substantive obs titled "npm pack drops …" is
+ * unsearchable forever. Escape is lesson-only by design: an importance>=2
+ * escape would resurrect pre-v2.47 Haiku-inflated noise on legacy DBs.
+ * Default stays title-only because two consumers query the events table
+ * (no lesson_learned column) and two are noise-title METRICS, not filters.
+ *
  * @param {string} [alias=''] Table alias (e.g. 'o') — empty for unqualified.
+ * @param {object} [opts]
+ * @param {boolean} [opts.lessonEscape=false] Admit rows with non-empty, non-'none' lesson_learned.
  * @returns {string} SQL boolean expression
  */
-export function buildNotLowSignalSql(alias = '') {
+export function buildNotLowSignalSql(alias = '', { lessonEscape = false } = {}) {
   const p = alias ? `${alias}.` : '';
   const clauses = LOW_SIGNAL_PATTERNS.map(({ like }) => `${p}title NOT LIKE '${like}'`);
-  return '(\n    ' + clauses.join('\n    AND ') + '\n  )';
+  const chain = '(\n    ' + clauses.join('\n    AND ') + '\n  )';
+  if (!lessonEscape) return chain;
+  // Mirrors the write-side lesson test: String(lesson).trim().toLowerCase() not in ('', 'none').
+  const escape = `(${p}lesson_learned IS NOT NULL AND LOWER(TRIM(${p}lesson_learned)) NOT IN ('', 'none'))`;
+  return `(${chain} OR ${escape})`;
 }
 
 // Cached singleton — isNoiseObservation is called once per observation insert.

package/lib/native-binding-hint.mjs

@@ -16,20 +16,33 @@
 //     run `npm rebuild` itself (2–5s timeout + concurrent-fire races).
 //
 // Pure node: imports + injectable now/runtimeDir so it unit-tests without the
-// hook dependency graph (no schema.mjs / better-sqlite3 import).
+// hook dependency graph (no schema.mjs / better-sqlite3 import). The one non-node:
+// import — lib/binding-probe.mjs for the shared fault classifier — keeps that
+// property: it only `createRequire`s better-sqlite3 lazily inside its functions,
+// so importing it never dlopen's the very binding this module reports on.
 
 import { join } from 'node:path';
-import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { isNativeBindingError } from './binding-probe.mjs';
 
 export const NATIVE_BINDING_HINT_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
 const MARKER_NAME = 'native-binding-hint-last';
 
-// Resolvable invocation of the bundled CLI's repair path. Absolute via
+// Breakage marker read by scripts/hook-launcher.mjs at session-start to trigger
+// the unattended rebuild. The hint alone was NOT enough: it goes to hook stderr,
+// is rate-limited to once per 6h, and in the field (2026-08-13) a Node 22 → 24
+// upgrade left the binding stale for 4 days across 79 failed fires because the
+// only healer was the MCP-server launch path, which those sessions never ran.
+export const NATIVE_BINDING_BROKEN_MARKER = 'native-binding-broken';
+
+// Resolvable invocation of the bundled CLI's LOCAL binding repair. Absolute via
 // import.meta.url (cli.mjs is one dir up from lib/) so it works on a plugin-only
-// install, where bare `claude-mem-lite` is not on PATH. cli.mjs routes `repair`
-// → install.mjs. (review #3)
-const CLI_REPAIR = `node ${fileURLToPath(new URL('../cli.mjs', import.meta.url))} repair`;
+// install, where bare `claude-mem-lite` is not on PATH. `rebuild-binding`, not
+// `repair`: repair re-downloads and Ed25519-verifies a whole GitHub release and
+// fails closed offline — the wrong (often impossible) tool for recompiling one
+// native module against the running Node. (review #3)
+const CLI_REBUILD_BINDING = `node ${fileURLToPath(new URL('../cli.mjs', import.meta.url))} rebuild-binding`;
 
 // Stable-ish identity of a fault so DISTINCT failures get DISTINCT cooldown
 // windows: the same fault → same key (suppressed within the window), a different
@@ -93,13 +106,56 @@ export function nativeBindingHintDue(runtimeDir, now = Date.now(), cooldownMs =
  */
 export function formatHookError(err, event, { now = Date.now(), runtimeDir } = {}) {
   const ts = new Date(now).toISOString();
-  if (err && err.code === 'ERR_DLOPEN_FAILED') {
+  if (isNativeBindingError(err)) {
+    // Record BEFORE the cooldown check: the hint is cosmetic and rate-limited,
+    // the marker is the heal trigger. Gating the marker on the hint would mean a
+    // silenced hint also silences the repair — exactly the 4-day outage shape.
+    if (runtimeDir) recordNativeBindingBreakage(runtimeDir, { reason: err.message, event, now });
     // Key the cooldown on the fault identity so a DISTINCT native failure within
     // the window still surfaces (a second ABI mismatch after a partial rebuild, a
     // corrupt .node) instead of being silenced by a prior, different DLOPEN. (#8/#15)
     if (runtimeDir && !nativeBindingHintDue(runtimeDir, now, NATIVE_BINDING_HINT_COOLDOWN_MS, errKey(err.message))) return null;
     return `[claude-mem-lite] [${ts}] [WARN] ${event}: native DB binding can't load ` +
-      `(likely a Node version change) — auto-heals on next MCP server start, or run: ${CLI_REPAIR}`;
+      `(likely a Node version change) — auto-heals at the next session start, or run now: ${CLI_REBUILD_BINDING}`;
   }
   return `[claude-mem-lite] [${ts}] [ERROR] ${event}: ${err && err.message}`;
 }
+
+/**
+ * Record the "native binding is unusable" state for the launcher's session-start
+ * heal. Overwrites: the newest fault is the one worth repairing. Best-effort —
+ * a hook must never fail because a marker could not be written.
+ *
+ * @param {string} runtimeDir
+ * @param {{reason?: string, event?: string, now?: number}} [opts]
+ */
+export function recordNativeBindingBreakage(runtimeDir, { reason = '', event = '', now = Date.now() } = {}) {
+  try {
+    mkdirSync(runtimeDir, { recursive: true });
+    const marker = join(runtimeDir, NATIVE_BINDING_BROKEN_MARKER);
+    const tmp = `${marker}.tmp-${process.pid}`;
+    // First line only: the ABI error is multi-line and the marker is read by the
+    // launcher (pure node:, no parser beyond JSON.parse) and by `doctor`.
+    writeFileSync(tmp, JSON.stringify({ reason: String(reason).split('\n')[0], event, ts: now }));
+    renameSync(tmp, marker);
+  } catch { /* best-effort */ }
+}
+
+/**
+ * @param {string} runtimeDir
+ * @returns {{reason?: string, event?: string, ts?: number} | null} null when
+ * absent, unreadable or torn — a garbage marker must never throw into a hook.
+ */
+export function readNativeBindingBreakage(runtimeDir) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(runtimeDir, NATIVE_BINDING_BROKEN_MARKER), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Idempotent. @param {string} runtimeDir */
+export function clearNativeBindingBreakage(runtimeDir) {
+  try { unlinkSync(join(runtimeDir, NATIVE_BINDING_BROKEN_MARKER)); } catch { /* already gone */ }
+}

package/lib/stats-quality.mjs

@@ -3,7 +3,7 @@
 // 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 { buildNotLowSignalSql } from './low-signal-patterns.mjs';
 import { truncate } from '../format-utils.mjs';
 import { COMPRESSED_PENDING_PURGE } from '../utils.mjs';
 
@@ -27,9 +27,11 @@ export function computeQualityStats(db, { project, days }) {
   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('')}`;
+  // LOW_SIGNAL match = NOT notLowSignal. Pure title-only builder: this is a
+  // METRIC counting pattern-titled rows ("Low-signal titles" in stats output),
+  // not a retrieval filter — the lesson-escape variant would silently exclude
+  // lesson-bearing rows from the count and understate title degradation.
+  const lowSignalIsMatchExpr = `NOT ${buildNotLowSignalSql('')}`;
 
   // Narrative-text proxy for bugfix investigations that never landed a fix.
   const unresolvedNarrativeExpr = `(

package/mem-cli.mjs

@@ -35,11 +35,14 @@ import { auditMemdir, memdirPath } from './memdir.mjs';
 import { aggregateProjectCiteRecall } from './lib/citation-tracker.mjs';
 import { probeOtherSources as probeIdSources, bucketIdTokens, splitDeferredTokens } from './lib/id-routing.mjs';
 import { join, sep, dirname } from 'path';
+import { spawnSync } from 'child_process';
 import { readFileSync, existsSync, readdirSync } from 'fs';
 
 // 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 { isNativeBindingError, healAndReexec } from './lib/binding-probe.mjs';
+import { CLI_PATH, CLI_INVOKE } from './cli-path.mjs';
 import { parseArgs, out, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints, rejectBareStringFlags, resolvePositionalAlias, suggestUnknownFlags, OBS_TIME_FIELDS, formatObsFieldValue } from './cli/common.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
 import { rebuildObservationDerived, normalizeScope, insertObservationVector } from './lib/observation-write.mjs';
@@ -3204,6 +3207,37 @@ export async function run(argv) {
     // previously threw here with no auto-repair until the next MCP start.
     db = ensureDbWithWalRecovery({ warn: (m) => process.stderr.write(`[mem] ${m}\n`) });
   } catch (e) {
+    // A Node upgrade leaves better_sqlite3.node compiled for the old ABI, and
+    // every DB-touching path fails at once. Pre-v3.60 this printed the raw
+    // multi-line NODE_MODULE_VERSION error with no repair named, and the only
+    // healer was an MCP server start the user might never perform — the shape of
+    // the 4-day outage on 2026-08-13. Heal in place, then RE-EXEC: this process
+    // has already dlopen'd the stale binary, so it cannot use the new one.
+    if (isNativeBindingError(e)) {
+      const healed = await healAndReexec({
+        // Delegate the actual rebuild to `cli.mjs rebuild-binding` so there is
+        // ONE healer: it takes install.lock, resolves which node_modules tree
+        // the running code uses, and clears the hooks' breakage marker.
+        ensure: async () => {
+          // Child stdout is DISCARDED, not inherited: install.mjs logs progress
+          // to stdout, and this CLI's stdout is a data channel (`search --json`
+          // is piped into jq). Progress still reaches the user via stderr.
+          const r = spawnSync(process.execPath, [CLI_PATH, 'rebuild-binding'], {
+            stdio: ['ignore', 'ignore', 'inherit'],
+            timeout: 300_000,
+          });
+          return r.status === 0
+            ? { ok: true, action: 'rebuilt' }
+            : { ok: false, error: `rebuild-binding exited ${r.status ?? 'on signal'}` };
+        },
+        log: (m) => process.stderr.write(`[mem] ${m}\n`),
+      });
+      if (healed.healed) { process.exitCode = healed.exitCode; return; }
+      out(`[mem] Error: native DB binding unusable on Node ${process.version}${healed.error ? ` — ${healed.error}` : ''}`);
+      out(`[mem] Fix: ${CLI_INVOKE} rebuild-binding`);
+      process.exitCode = 1;
+      return;
+    }
     out(`[mem] Error: Cannot open database: ${e.message}`);
     out(`[mem] DB path: ${DB_PATH}`);
     process.exitCode = 1;

package/memdir.mjs

@@ -304,9 +304,30 @@ export function removePluginDoc(memdir, slug) {
 // noise.
 
 const AUDIT_FILE_RE = /^(feedback|project)_[A-Za-z0-9_-]+\.md$/;
+// Legacy skip prefixes: user_*/reference_* have no Why/How requirement. A known
+// filename prefix wins over frontmatter type (a user_*.md stays excluded even if
+// its frontmatter says feedback).
+const SKIP_FILE_RE = /^(user|reference)_[A-Za-z0-9_-]+\.md$/;
 const WHY_RE = /^\s*\*\*Why:\*\*/m;
 const HOW_RE = /^\s*\*\*How to apply:\*\*/m;
 
+/**
+ * Extract the memory type from a file's YAML frontmatter (2026-07-24 audit P2).
+ * The current CC harness writes kebab-case filenames (ship-runbook.md) and puts
+ * the type in frontmatter — either top-level `type: X` or nested under
+ * `metadata:` as `  type: X`. Anchored `^\s*type:` cannot match `node_type:`.
+ *
+ * @param {string} raw Full file content
+ * @returns {string|null} Lowercased type, or null when absent/no frontmatter
+ */
+function frontmatterType(raw) {
+  if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) return null;
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!m) return null;
+  const t = m[1].match(/^\s*type:\s*([A-Za-z]+)\s*$/m);
+  return t ? t[1].toLowerCase() : null;
+}
+
 /**
  * Strip the leading YAML frontmatter block (between `---` fences) so audit
  * checks run only against body content. Returns input unchanged if no
@@ -339,13 +360,29 @@ export function auditMemdir(memdir) {
   let entries;
   try { entries = readdirSync(memdir); } catch { return result; }
 
-  const targets = entries.filter(n => AUDIT_FILE_RE.test(n)).sort();
-  for (const name of targets) {
-    let body = '';
-    try {
-      const raw = readFileSync(join(memdir, name), 'utf8');
-      body = stripFrontmatter(raw);
-    } catch { /* unreadable — count as missingBoth */ }
+  // Two selection paths (2026-07-24 audit P2):
+  //   1. legacy filename prefix — feedback_*/project_* audited, user_*/reference_* skipped
+  //   2. kebab-case (current harness) — frontmatter type ∈ {feedback, project}
+  // Path 2 needs the file content; read once and reuse for the body check.
+  const candidates = entries
+    .filter(n => n.endsWith('.md') && n !== 'MEMORY.md' && !n.startsWith('.'))
+    .sort();
+  let total = 0;
+  for (const name of candidates) {
+    const legacyAudit = AUDIT_FILE_RE.test(name);
+    if (!legacyAudit && SKIP_FILE_RE.test(name)) continue;
+
+    let raw = null;
+    try { raw = readFileSync(join(memdir, name), 'utf8'); } catch { /* unreadable */ }
+
+    if (!legacyAudit) {
+      // Frontmatter decides; unreadable or untyped files carry no Why/How contract.
+      const type = raw === null ? null : frontmatterType(raw);
+      if (type !== 'feedback' && type !== 'project') continue;
+    }
+    // Legacy-prefixed unreadable file keeps the old behavior: counted as missingBoth.
+    const body = raw === null ? '' : stripFrontmatter(raw);
+    total += 1;
 
     const hasWhy = WHY_RE.test(body);
     const hasHow = HOW_RE.test(body);
@@ -354,6 +391,6 @@ export function auditMemdir(memdir) {
     else if (!hasWhy) result.missingWhy.push(name);
     else result.missingHowToApply.push(name);
   }
-  result.total = targets.length;
+  result.total = total;
   return result;
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.59.0",
+  "version": "3.60.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.59.0",
+      "version": "3.60.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",
@@ -1570,22 +1570,6 @@
         }
       }
     },
-    "node_modules/ajv/node_modules/fast-uri": {
-      "version": "3.1.4",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz",
-      "integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/fastify"
-        },
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/fastify"
-        }
-      ],
-      "license": "BSD-3-Clause"
-    },
     "node_modules/assertion-error": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
@@ -2401,6 +2385,22 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-uri": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
+      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
     "node_modules/fd-package-json": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/fd-package-json/-/fd-package-json-2.0.0.tgz",
@@ -2687,9 +2687,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.31",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.31.tgz",
-      "integrity": "sha512-zJIHFrl6bq3RDd2YusFNCDlM8qUprxKswyi/OPzPyzKDdyBXDqWx8bZlZ7R+saTdSTatUmb3O7K4SspGPaEOQg==",
+      "version": "4.13.2",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.2.tgz",
+      "integrity": "sha512-JydRilDRkYBQMt9qR9U92mXxmbGqsqSn/IKOrh4e7/gEbn+0zSr8igTu0obwJoNGN4sez28DIql7FBHWydoJpA==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -2791,9 +2791,9 @@
       "license": "ISC"
     },
     "node_modules/ip-address": {
-      "version": "10.2.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
-      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.5.0.tgz",
+      "integrity": "sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.59.0",
+  "version": "3.60.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scoring-sql.mjs

@@ -152,8 +152,17 @@ export function noisePenaltyClause(alias = 'o') {
 // 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.
+//
+// lessonEscape (2026-07-24 audit P1, D#11): every consumer of THIS clause is an
+// observations-table retrieval surface (search, recall, error-recall, context/
+// handoff/UPS injection, optimize candidates), so all get the read-side lesson
+// escape — a low-signal TITLE no longer hides a row with a real lesson_learned.
+// Consumers that must stay title-only import buildNotLowSignalSql directly:
+// events-table queries (lib/activity.mjs, pre-tool-recall.js events fallback —
+// no lesson_learned column) and noise-title metrics (lib/stats-core.mjs,
+// lib/stats-quality.mjs — they COUNT pattern-titled rows, not filter them).
 export function notLowSignalTitleClause(alias = 'o') {
-  return buildNotLowSignalSql(alias);
+  return buildNotLowSignalSql(alias, { lessonEscape: true });
 }
 
 // ─── Cite-history factor (A1, v2.83) ────────────────────────────────────────

package/scripts/hook-launcher.mjs

@@ -25,7 +25,7 @@
 // install.
 
 import { existsSync, mkdirSync, writeFileSync, statSync, unlinkSync, readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { dirname, join, isAbsolute } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { homedir } from 'node:os';
@@ -47,6 +47,34 @@ const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
 // the intentional silence (no stack trace per fire) stays detectable. (#4/#8)
 const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
 
+// ── Native-binding (ABI) self-heal ──────────────────────────────────────────
+// A stale better_sqlite3.node after a Node upgrade does NOT throw at import time
+// — better-sqlite3 dlopen's it lazily at the first `new Database()`, deep inside
+// the hook script, whose own catch swallows it. So it never reaches the
+// ERR_MODULE_NOT_FOUND path below.
+//
+// scripts/setup.sh has probed + rebuilt the binding at SessionStart since v3.58,
+// but ONLY on plugin-manifest installs: hooks/hooks.json registers setup.sh,
+// while an install.mjs-managed settings.json does NOT — it wires the launcher
+// alone. On that install shape nothing healed. Field result (2026-08-13): 4 days
+// with a dead memory system, 79 failed fires in one day.
+//
+// The hook scripts now drop a marker on every such fire (via
+// lib/hook-telemetry.mjs and lib/native-binding-hint.mjs); this heals from it at
+// SESSION-START only — never on the per-tool hot path, where an npm run would
+// stall the user's edit.
+// Marker dir mirrors the standalone hook scripts (pre-tool-recall /
+// pre-skill-bridge), which honor CLAUDE_MEM_RUNTIME_DIR — they write 78 of every
+// 79 of these markers, so reading a different dir would mean never healing.
+const NB_RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || RUNTIME_DIR;
+const NB_BROKEN_MARKER = join(NB_RUNTIME_DIR, 'native-binding-broken');
+const NB_HEAL_MARKER = join(NB_RUNTIME_DIR, 'native-binding-lastheal');
+// Literal, not imported: the pure-`node:` charter above forbids importing lib/
+// here (this file must survive a broken install). Kept in sync with
+// lib/binding-probe.mjs::NATIVE_BINDING_REBUILD_CMD, which is the single home
+// everywhere the charter allows an import.
+const NB_MANUAL_CMD = 'npm rebuild better-sqlite3 --dangerously-allow-all-scripts';
+
 // Resolvable invocation of the bundled CLI's repair path. Absolute via
 // INSTALL_DIR (import.meta.url) so it works on a plugin-only install, where
 // bare `claude-mem-lite` is not on PATH and ~/.claude-mem-lite/ holds no source.
@@ -248,6 +276,62 @@ async function attemptHeal(reason) {
 // falls through to the normal entry import. The dynamic import keeps this
 // launcher's pure-`node:` static-import charter intact (it must survive a broken
 // install even if hook-update.mjs is unimportable).
+// → the function this describes is trySyncDataDirFromCache(), below.
+
+// Rebuild the native binding when a prior fire recorded it as unusable.
+//
+// DETACHED, never awaited. This hook runs under a 15s Claude Code cap
+// (hooks/hooks.json) while a rebuild can take far longer — prebuild-install has
+// to fetch, and a node-gyp fallback is minutes. Waiting would trade a broken
+// binding for a SIGKILL'd session-start (no memory context at all) plus a
+// half-written .node, the exact hazard scripts/setup.sh's 20s exec cap documents.
+// Detaching costs one fire: the rebuild lands within seconds and the NEXT hook
+// fire — usually the same session's first PreToolUse — is already healthy.
+// stdio is fully ignored: install.mjs logs to STDOUT, and SessionStart stdout is
+// a JSON envelope Claude Code parses, so inheriting it corrupts the fire.
+//
+// Bounded by its own 6h cooldown so an unfixable case (no prebuild for this Node,
+// no compiler, offline) does not re-spawn npm every session. The cooldown is
+// dropped once the binding is confirmed healthy, so a LATER unrelated break heals
+// immediately instead of waiting out a stale window.
+// Best-effort throughout — a heal failure must never stop the hook fire.
+function healNativeBindingIfBroken() {
+  try {
+    if (!existsSync(NB_BROKEN_MARKER)) {
+      // Healthy (or already healed by the child) → reset the cooldown.
+      try { unlinkSync(NB_HEAL_MARKER); } catch { /* nothing to reset */ }
+      return;
+    }
+    try {
+      if (Date.now() - statSync(NB_HEAL_MARKER).mtimeMs < HEAL_COOLDOWN_MS) return;
+    } catch { /* no marker → not on cooldown */ }
+    try {
+      mkdirSync(NB_RUNTIME_DIR, { recursive: true });
+      writeFileSync(NB_HEAL_MARKER, String(Date.now()));
+    } catch { /* best-effort */ }
+
+    const installer = join(INSTALL_DIR, 'install.mjs');
+    if (!existsSync(installer)) {
+      process.stderr.write(
+        `[claude-mem-lite] native DB binding unusable and install.mjs is missing — run: cd "${INSTALL_DIR}" && ${NB_MANUAL_CMD}\n`,
+      );
+      return;
+    }
+    // The CHILD clears the breakage marker, and only on a verified-good rebuild
+    // (install.mjs::rebuildBinding). Clearing it here would mean a rebuild that
+    // silently did nothing — lock contention, a no-op npm — still reads as
+    // "healed", dropping the cooldown and re-spawning npm on every session.
+    process.stderr.write(
+      '[claude-mem-lite] native DB binding unusable (Node version change?) — rebuilding in the background\n',
+    );
+    const child = spawn(process.execPath, [installer, 'rebuild-binding'], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+  } catch { /* best-effort — never block the hook fire */ }
+}
+
 async function trySyncDataDirFromCache() {
   try {
     const { syncDataDirFromCache } = await import(
@@ -257,15 +341,27 @@ async function trySyncDataDirFromCache() {
   } catch { /* best-effort — proceed to the normal entry regardless */ }
 }
 
-if (rest.includes('session-start')) {
+const IS_SESSION_START = rest.includes('session-start');
+
+if (IS_SESSION_START) {
+  // Before the entry: this process has not dlopen'd better-sqlite3 yet, so the
+  // freshly built .node is picked up by the very fire that follows. (After a
+  // failed dlopen, only a NEW process can load the replacement — the module
+  // handle is cached and an in-process retry dies with "did not self-register".)
+  healNativeBindingIfBroken();
   await trySyncDataDirFromCache();
 }
 
+
 try {
   await runEntry();
   // A clean session-start fire confirms the install is healthy → clear any stale
   // breakage marker. Gated to session-start so the per-tool hot path pays nothing.
-  if (rest.includes('session-start')) clearBreakage();
+  if (IS_SESSION_START) clearBreakage();
+  // After the entry too: the fire that DISCOVERS the breakage is the one that
+  // records it, so a pre-entry-only check would leave the whole session dead and
+  // heal one session late.
+  if (IS_SESSION_START) healNativeBindingIfBroken();
 } catch (e) {
   if (!isLocalModuleErr(e)) throw e;
   const reason = describeFailure(e);