claude-mem-lite 6.4.0 → 6.5.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.4.0",
+      "version": "6.5.0",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "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": "6.4.0",
+  "version": "6.5.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/hook-context.mjs

@@ -585,7 +585,12 @@ export function buildSessionContextLines(
   } else if (!latestSummary && !effectiveQuiet()) {
     // Fallback: no summary AND no key observations — show recent activity.
     // Skipped under QUIET_HOOKS since the Recent table already carries titles.
-    const recentObs = (observations.length >= 3 ? observations : fallbackObs).slice(0, 3);
+    // Slice FIRST, then sort: the slice is the selection (top 3 by value density) and must
+    // stay that way; only the order they are printed in is corrected, same as the Recent
+    // table below. Sorting before the slice would silently change WHICH three are injected.
+    const recentObs = (observations.length >= 3 ? observations : fallbackObs)
+      .slice(0, 3)
+      .sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at) || b.id - a.id);
     if (recentObs.length > 0) {
       summaryLines.push('### Recent Activity');
       for (const o of recentObs) {
@@ -695,8 +700,18 @@ export function buildSessionContextLines(
   }
 
   // 6. Recent observations table
+  //
+  // SELECTION order (greedy knapsack, value density) is not DISPLAY order. This block used
+  // to render the picks in the order the knapsack happened to take them, under a heading
+  // that says "Recent" next to a Time column — so row 1 was not the newest row, and both a
+  // human and the model read it as if it were. Sorting here is display-only: `obsToShow` is
+  // already chosen, so the token budget and the row set are untouched (pinned by a case in
+  // tests/hook-context.test.mjs). Tiebroken on id for the same reason D#9 gives — an
+  // untiebroken tie flips direction, and two saves in one millisecond are common.
   const obsLines = [];
-  const obsToShow = observations.length >= 3 ? observations : fallbackObs;
+  const obsToShow = [...(observations.length >= 3 ? observations : fallbackObs)].sort(
+    (a, b) => Date.parse(b.created_at) - Date.parse(a.created_at) || b.id - a.id,
+  );
   if (obsToShow.length > 0) {
     const today = now.toISOString().slice(0, 10);
     obsLines.push(`### Recent (${today})`);

package/hook-shared.mjs

@@ -28,6 +28,8 @@ import {
   shouldRecordSkew,
   SKEW_MARKER_PREFIX,
 } from './lib/schema-skew.mjs';
+import { isDbUnusableError, DB_UNUSABLE_MARKER_PREFIX } from './lib/db-unusable.mjs';
+import { shouldRecordOnce } from './lib/record-once.mjs';
 // Audit 2026-09-05 P1-2 (carried from 2026-09-02 P2-9): `callLLM`, the quiet/adoption
 // predicates and the handoff constants moved into `lib/` because two lib modules
 // imported them from here and dragged this file's whole import graph — haiku-client,
@@ -244,6 +246,9 @@ export const GC_PROJECT_MARKER_PREFIXES = Object.freeze([
   // v5.0.0; a prefix for files nothing writes any more is dead weight in a hot-path loop.
   'last-mark-compressible-', // per-project auto-compress 24h gate
   SKEW_MARKER_PREFIX, // per-project schema-skew log dedup; regenerated on the next skewed open
+  // Same shape, same reason, and it was missed here first time round — the note above is
+  // about exactly this defect, two entries up.
+  DB_UNUSABLE_MARKER_PREFIX, // per-project unopenable-DB log dedup; regenerated on the next failing open
 ]);
 
 // Records of a completed side effect — never age out. `ep-`/`ep-flush-`/
@@ -405,12 +410,28 @@ export function lastSchemaSkew() {
   return lastSkew;
 }
 
+// Same idea, other unhealable family: the file exists and SQLite will not open it. Held as a
+// boolean rather than the error, because the only thing SessionStart needs is "which notice",
+// and keeping an Error alive here would tempt a caller into rendering a stack trace at a user.
+let lastUnusable = false;
+
+/**
+ * True when the most recent openDb() returned null because the database file is not a usable
+ * database. Cleared by any successful open, so a repair mid-session stops the notice.
+ *
+ * @returns {boolean}
+ */
+export function lastDbUnusable() {
+  return lastUnusable;
+}
+
 export function openDb() {
   try {
     // WAL-corruption self-heal (was server.mjs-only): without it, hooks stayed
     // silently dead (null DB) on a corrupt WAL until the next MCP server start.
     const db = ensureDbWithWalRecovery();
     lastSkew = null;
+    lastUnusable = false;
     return db;
   } catch (e) {
     // Forward-incompat is its own family: it cannot be healed by anything this process can
@@ -423,10 +444,11 @@ export function openDb() {
     //
     // shouldRecordSkew is TOTAL by contract. Nothing in this catch may throw: the first cut
     // called getSessionId() here, which MINTS and writes a session id, so an unwritable
-    // runtime dir turned openDb() itself into a thrower. All 13 call sites are written to
+    // runtime dir turned openDb() itself into a thrower. All 12 openDb() call sites in hook.mjs are written to
     // no-op on null and none of them expects an exception.
     if (isSchemaSkewError(e)) {
       lastSkew = schemaSkewFromError(e) || { dbVersion: null, binaryVersion: null };
+      lastUnusable = false;
       // Guarded even though inferProject() reads env and cwd: "the only statement in this
       // catch cannot throw" was true of the original one-line body and stopped being true
       // the moment anything was added. An unscoped marker is a worse dedup, not a crash.
@@ -441,8 +463,31 @@ export function openDb() {
       }
       return null;
     }
-    // Still null, still no throw — a hook must never crash the host session, and all
-    // eight call sites in hook.mjs are written to no-op on null. But "returned null"
+    // The OTHER unhealable family, and it was the silent one. A file that is not a database
+    // repeats on every fire exactly like a skew does, and until now took the generic branch
+    // below: one full stack trace per SessionStart fire (measured: 20 fires → 20 records, ~860 B
+    // each), no dedup, and no user-visible word anywhere in the session. Same treatment as skew
+    // — record once per project per hour, and hand SessionStart a flag to speak with.
+    //
+    // Nothing in this branch may throw: `isDbUnusableError` is a regex over a string and
+    // `shouldRecordOnce` is total by contract, which is exactly the property the first cut of
+    // the skew dedup lost by calling a function that WRITES.
+    if (isDbUnusableError(e)) {
+      lastUnusable = true;
+      lastSkew = null; // the two flags are a set: whichever family fired last is the true one
+      let project = '';
+      try {
+        project = inferProject();
+      } catch {
+        /* total: the marker degrades to one shared file */
+      }
+      if (shouldRecordOnce(RUNTIME_DIR, DB_UNUSABLE_MARKER_PREFIX, project, 'unusable')) {
+        recordHookError('hook-shared:db-open', e, RUNTIME_DIR);
+      }
+      return null;
+    }
+    // Still null, still no throw — a hook must never crash the host session, and all 12
+    // openDb() call sites in hook.mjs are written to no-op on null. But "returned null"
     // used to be the ONLY trace: nothing reached runtime/hook-errors/, so `stats`
     // reported 0 and doctor printed "no recent silent hook breakage" while every
     // capture path was dead (audit B1, 2026-08-14 — the same blindness that hid the

package/hook.mjs

@@ -62,7 +62,7 @@ import {
 } from './hook-episode.mjs';
 // CODE_DIR, not DB_DIR: the schema-skew notice asks which CODE homes exist, and those are
 // always homedir-rooted even when CLAUDE_MEM_DIR relocates the data.
-import { DB_DIR, CODE_DIR } from './schema.mjs';
+import { DB_DIR, DB_PATH, CODE_DIR } from './schema.mjs';
 import { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-context.mjs';
 import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
@@ -85,6 +85,7 @@ import {
   sweepOrphanEpisodeFiles,
   sweepStaleProjectMarkers,
   lastSchemaSkew,
+  lastDbUnusable,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveEpisodeImmediate } from './hook-llm.mjs';
 import { readFastSummarySource, insertFastSummary, FAST_SUMMARY_LIMITS } from './lib/fast-summary.mjs';
@@ -2354,6 +2355,33 @@ async function emitSchemaSkewNotice() {
   }
 }
 
+/**
+ * The corruption twin of emitSchemaSkewNotice. Same channels, same reason they are BOTH used:
+ * queueHookContext reaches the model, queueHookSystemMessage reaches the human, and a notice
+ * whose whole job is handing the user a command must not depend on the assistant volunteering
+ * it (lib/hook-stdout.mjs names v3.70.0 for exactly that mistake).
+ *
+ * Dynamically imported like its twin: a cold path must not cost the healthy SessionStart a
+ * directory scan for backup snapshots.
+ */
+async function emitDbUnusableNotice() {
+  try {
+    if (!lastDbUnusable()) return;
+    const mod = await import('./lib/db-unusable.mjs');
+    // TWO DIFFERENT STRINGS, unlike the skew twin, and the asymmetry is the point: the
+    // human channel carries the repair command, the model channel carries only the fact.
+    // See formatDbUnusableModelNotice — this family's remedy overwrites the database.
+    queueHookSystemMessage(
+      mod.formatDbUnusableNotice({ dbPath: DB_PATH, remedy: mod.dbUnusableRemedy(DB_PATH) }),
+    );
+    queueHookContext('SessionStart', mod.formatDbUnusableModelNotice());
+  } catch (e) {
+    // A hook must never crash the host session, and a notice that cannot render is better
+    // handled by staying quiet than by taking SessionStart down with it.
+    debugCatch(e, 'session-start-db-unusable');
+  }
+}
+
 async function handleSessionStart() {
   // GC stale per-session cooldown files. Cheap (<5ms typical) and idempotent;
   // moved here from pre-tool-recall.js's hot path.
@@ -2542,7 +2570,13 @@ async function handleSessionStart() {
     // only other signal it produces is a `-32000 Connection closed` from the MCP host, which
     // names nothing. Measured 2026-09-08: a whole day of it, >=648 log lines, zero words to
     // the user. This is the surface the user actually reads.
+    //
+    // A database file that is not a database is the same shape and got the same treatment:
+    // unhealable without the user, disables every path, and every OTHER surface (CLI exit 1,
+    // `status`, `doctor` with an exact repair command) already reports it — leaving the
+    // in-session one as the only silent one.
     await emitSchemaSkewNotice();
+    await emitDbUnusableNotice();
     return;
   }
 

package/install.mjs

@@ -17,7 +17,7 @@ import {
   statSync,
   lstatSync,
 } from 'fs';
-import { join, resolve, dirname, basename } from 'path';
+import { join, resolve, dirname, basename, sep } from 'path';
 import { homedir, tmpdir } from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
@@ -70,9 +70,9 @@ import {
   nativeBindingRepairHint,
   isNativeBindingError,
 } from './lib/binding-probe.mjs';
-import { readSnapshots } from './lib/db-backup.mjs';
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
 import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.mjs';
+import { isDbUnusableError, dbUnusableRemedy } from './lib/db-unusable.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { ORPHAN_EPISODE_AGE_MS } from './lib/time-constants.mjs';
@@ -444,34 +444,22 @@ export function nonPluginMemRegistrations(listOutput) {
  */
 export function dbCheckRemedy(dbPath, err) {
   if (isNativeBindingError(err)) return `Repair: ${nativeBindingRepairHint(PROJECT_DIR)}`;
-  const msg = String(err?.message ?? err ?? '');
-  // SQLite's own spellings for "this file is not a usable database".
-  if (!/not a database|disk image is malformed|file is not a database/i.test(msg)) return null;
-
-  const clear = `rm -f "${dbPath}-wal" "${dbPath}-shm"`;
-  const snap = readSnapshots(dbPath);
-  if (!snap.ok) {
-    return (
-      `Could not read ${dirname(dbPath)} to look for a backup snapshot (${snap.reason}) — ` +
-      `fix that directory first, then look for ${basename(dbPath)}.*.bak beside the database.`
-    );
-  }
-  if (snap.snapshots.length === 0) {
+  // Classification and remedy both live in lib/db-unusable.mjs since v6.5.0, because the hook
+  // path now has to answer the same question in-session and two copies of a SQLite-message
+  // regex is this repo's named twin-drift class. Doctor keeps its own SENTENCE (one line, no
+  // leading banner); only the decision is shared.
+  if (!isDbUnusableError(err)) return null;
+  const remedy = dbUnusableRemedy(dbPath);
+  if (remedy.kind === 'unknown') return remedy.note;
+  if (remedy.kind === 'set-aside') {
     return (
       `No backup snapshot exists beside the database. Set the broken file aside so a fresh ` +
-      `store is created on the next session: ${clear} && mv "${dbPath}" "${dbPath}.corrupt" ` +
+      `store is created on the next session: ${remedy.command} ` +
       `— memories in that file are not recoverable without a backup.`
     );
   }
-  // Newest by mtime. Ties are broken by name, which carries an ISO stamp, so the answer is
-  // total rather than dependent on which of two same-millisecond files readdir returned
-  // first (the D#9 shape).
-  const newest = snap.snapshots
-    .slice()
-    .sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1))[0];
   return (
-    `Restore the newest of ${snap.snapshots.length} backup snapshot(s): ` +
-    `${clear} && cp "${newest.path}" "${dbPath}" ` +
+    `Restore the newest of ${remedy.snapshotCount} backup snapshot(s): ${remedy.command} ` +
     `— move the broken file aside first if you want to keep it for inspection.`
   );
 }
@@ -655,6 +643,57 @@ function createCliSymlink() {
   }
 }
 
+/**
+ * Which of our MCP names a PROJECT-scoped `.mcp.json` in `cwd` registers.
+ *
+ * This exists because the installer used to run `claude mcp remove -s project <name>` as
+ * part of "purge any pre-existing registration before re-registering". That command edits
+ * `<cwd>/.mcp.json` — a file that belongs to whatever repository the user happens to be
+ * standing in, not to this installer's state. Measured 2026-09-08: running the installer
+ * from a clone of this repo emptied the tracked root `.mcp.json` (the plugin's own MCP
+ * manifest, and a RELEASE_SIGNED_FILES entry), and nothing said so; only a test noticed.
+ * For anyone else it is a silent edit to a checked-in file that breaks the registration
+ * for every teammate who pulls it.
+ *
+ * `uninstall` has always removed `-s user` only, so the scope discipline already existed
+ * on the other half of the lifecycle; this brings install into line with it and reports
+ * the duplicate instead — same doctrine as the README's mixed-install residue section,
+ * where the tool diagnoses and the user decides.
+ *
+ * @param {string} cwd directory to inspect
+ * @returns {{file: string, names: string[]}} names present, empty when there is nothing to say
+ */
+export function projectScopedMemRegistrations(cwd) {
+  const file = join(cwd, '.mcp.json');
+  try {
+    const servers = JSON.parse(readFileSync(file, 'utf8'))?.mcpServers;
+    // Array.isArray is load-bearing: `typeof [] === 'object'`, so without it an array
+    // falls through to the membership filter and the guard cannot fire on its own
+    // named input — which is how the test case for it was passing.
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return { file, names: [] };
+    return { file, names: ['mem', 'mem-lite'].filter((n) => n in servers) };
+  } catch {
+    // Absent, unreadable, or not JSON — nothing we can honestly report.
+    return { file, names: [] };
+  }
+}
+
+/**
+ * Say so when the directory we are standing in registers our server at PROJECT scope.
+ *
+ * Reporting rather than removing is the whole point — see projectScopedMemRegistrations.
+ */
+function warnProjectScopedMcpDuplicate() {
+  const projectScoped = projectScopedMemRegistrations(process.cwd());
+  if (projectScoped.names.length === 0) return;
+  warn(
+    `${projectScoped.file} also registers ${projectScoped.names.map((n) => `"${n}"`).join(' and ')} ` +
+      `at PROJECT scope — that duplicate wins inside this directory. Left untouched: it is your ` +
+      `repo's file. Remove it with \`claude mcp remove -s project <name>\` if you want the ` +
+      `user-scope registration to apply here.`,
+  );
+}
+
 function registerMcpServer() {
   // 3. Register MCP server (skip if plugin system already handles it)
   // Plugin MCP must stay at root .mcp.json so Claude Code registers plugin:*:mem-lite.
@@ -673,6 +712,12 @@ function registerMcpServer() {
     /* not installed via plugin system */
   }
 
+  // The DISCLOSURE is unconditional even though the removal it replaced was not: a
+  // project-scoped `mem`/`mem-lite` entry shadows the user-scope one inside that directory
+  // whichever way this install provides the server, so a plugin-mode user standing in such a
+  // repo has the same problem and used to get the same silence.
+  warnProjectScopedMcpDuplicate();
+
   if (pluginHandlesMcp) {
     log('MCP server: plugin system handles registration (skipping global)');
     // Clean up stale global registrations (both legacy "mem" and current "mem-lite")
@@ -685,14 +730,13 @@ function registerMcpServer() {
   } else {
     log('Registering MCP server...');
     try {
-      // Purge legacy "mem" and any pre-existing "mem-lite" before re-registering
+      // Purge legacy "mem" and any pre-existing "mem-lite" from OUR scope before
+      // re-registering. User scope only — see projectScopedMemRegistrations for why the
+      // project-scope removal that used to sit here was a bug, not a cleanup.
       for (const name of ['mem', 'mem-lite']) {
         try {
           execFileSync('claude', ['mcp', 'remove', '-s', 'user', name], { stdio: 'pipe' });
         } catch {}
-        try {
-          execFileSync('claude', ['mcp', 'remove', '-s', 'project', name], { stdio: 'pipe' });
-        } catch {}
       }
       execFileSync(
         'claude',
@@ -1338,12 +1382,90 @@ async function uninstall() {
       }
     }
   } else {
-    log('Data preserved (use --purge to remove)');
+    // "Data preserved" was true and incomplete, and the gap is what a user notices on
+    // disk: the DB here is fractions of a megabyte while the installed code and its
+    // node_modules — which uninstall has just made unreachable (symlink gone, hooks gone,
+    // MCP registration gone) — are tens of megabytes and were never named. Measured on a
+    // sandbox install right after uninstall: 56 MB total, 53 MB of it node_modules,
+    // against a 0.2 MB DB. Report both halves so nothing large is left unnamed.
+    //
+    // These are APPARENT bytes (`statSync().size`), which is what `du --apparent-size`
+    // reports and NOT what a bare `du -sh` does: block rounding over thousands of small
+    // node_modules files put the same tree at 44.4 MB apparent against 54.3 MB of blocks,
+    // a 22% gap. Do not "reconcile" this line against a plain `du` — they are two rulers.
+    const kept = preservedFootprint();
+    const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+    log(`Data preserved: memories in ${MEM_DATA_DIR} (${mb(kept.memoryBytes)}MB)`);
+    if (kept.restBytes > 0) {
+      log(
+        `  Also kept: the installed code + node_modules under ${DATA_DIR} (${mb(kept.restBytes)}MB) — ` +
+          `a later \`install\` reuses them; nothing runs them now.`,
+      );
+    }
+    log('  `uninstall --purge` removes the directory, memories included');
   }
 
   console.log('\n  Done!\n');
 }
 
+/**
+ * Split what a non-purge uninstall leaves behind into the two halves a user cares about:
+ * the memories, and everything else.
+ *
+ * "Memories" is every file whose name starts with `claude-mem-lite.db` in the data dir —
+ * the DB, its WAL/SHM, and the `.db.<tag>.bak` snapshots. That is DELIBERATELY WIDER than
+ * lib/db-backup.mjs::readSnapshots, which additionally requires the trailing dot and a
+ * `.bak` suffix: this wants everything that is the user's data, that wants snapshots only. "Rest" is the whole install directory minus that,
+ * so it covers the source files, node_modules, runtime/ and metrics/ in one number. The
+ * point of the split is the node_modules order-of-magnitude (53 MB against a 0.2 MB DB on
+ * a fresh sandbox install), not a per-subdirectory audit.
+ *
+ * Never throws: a missing dir, a permission error or a symlink loop all degrade to 0, and
+ * the caller prints the shorter sentence. An uninstall must not fail on a size probe.
+ *
+ * @returns {{memoryBytes: number, restBytes: number}} bytes, 0 when unmeasurable
+ */
+function preservedFootprint() {
+  const DB_PREFIX = 'claude-mem-lite.db';
+  const walk = (dir, onFile) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      try {
+        if (e.isDirectory()) walk(p, onFile);
+        else if (e.isFile()) onFile(p, e.name, statSync(p).size);
+      } catch {
+        /* raced deletion / unreadable entry — skip */
+      }
+    }
+  };
+
+  let memoryBytes = 0;
+  let restBytes = 0;
+  // The memories may live outside the install dir (CLAUDE_MEM_DIR), so measure each dir
+  // for what it actually holds rather than assuming the two are the same tree.
+  walk(MEM_DATA_DIR, (_p, name, size) => {
+    if (name.startsWith(DB_PREFIX)) memoryBytes += size;
+    else if (MEM_DATA_DIR === DATA_DIR) restBytes += size;
+  });
+  if (MEM_DATA_DIR !== DATA_DIR) {
+    // A relocated CLAUDE_MEM_DIR may still sit INSIDE the install dir, in which case walking
+    // DATA_DIR would count the DB and its snapshots a second time — reported 9.0MB against a
+    // true 6.0MB on a nested fixture. Skip the memory tree explicitly rather than assume the
+    // two are disjoint; `+ sep` so a sibling named `<dir>-old` is not swallowed too.
+    const memPrefix = MEM_DATA_DIR.endsWith(sep) ? MEM_DATA_DIR : MEM_DATA_DIR + sep;
+    walk(DATA_DIR, (p, _name, size) => {
+      if (p !== MEM_DATA_DIR && !p.startsWith(memPrefix)) restBytes += size;
+    });
+  }
+  return { memoryBytes, restBytes };
+}
+
 // ─── Cleanup Hooks ───────────────────────────────────────────────────────────
 
 async function cleanupHooks() {

package/lib/db-unusable.mjs

@@ -0,0 +1,178 @@
+// lib/db-unusable.mjs — the database file is not a usable database.
+//
+// The sibling of lib/schema-skew.mjs, and it exists for the same reason: the throw is
+// correct, and everything downstream of it was missing. Measured 2026-09-08 in a sandboxed
+// HOME with a corrupted header:
+//
+//   • CLI (`search` / `recent` / `stats` / `get` / `save` / `browse` / `fts-check`) — all exit
+//     1 with the SQLite message. Correct.
+//   • `status` — "⚠ Database: exists but check failed". Correct.
+//   • `doctor` — names the file and prints an exact repair command. Correct.
+//   • Hooks — `openDb()` returns null, `hook.mjs`'s `const db = openDb(); if (!db) return;`
+//     ends SessionStart with EMPTY stdout and EMPTY stderr, and every fire wrote another
+//     stack trace to runtime/hook-errors/. Nothing the user sees says memory is off.
+//
+// State that last figure carefully, because the first draft got it wrong twice over: it said
+// "20 fires → 10 identical ~1.5 KB records", which was a MIXED fire set (only some events
+// reach this path) reported as if it were 20 SessionStarts, and a size nobody measured.
+// Re-measured over 20 SessionStart fires: 20 records, 859-873 bytes each — one per fire, and
+// ~1.7x smaller than claimed. `recordHookError` caps the stack at 6 frames and the message at
+// 500 chars, so the per-record size is bounded; the unbounded quantity is the COUNT.
+//
+// So the one surface the user is actually looking at during a session was the only silent
+// one, on a condition that never heals by itself. That is the schema-skew shape exactly, and
+// this module is deliberately its mirror image so the two cannot drift apart.
+//
+// It imports no native binding: the static graph is 10 modules and zero package edges (the
+// only bare specifiers anywhere in it are the `node:` builtins). That is the property that
+// matters — a classifier the hook path may need while the binding is the broken thing must
+// not sit behind a native import. It is NOT as tight as schema-skew.mjs, which imports
+// `node:` builtins and nothing else; this one reaches `db-backup → utils → …` for
+// `readSnapshots`. Same guarantee, larger graph — do not restate it as "same discipline".
+
+import { basename, dirname } from 'node:path';
+import { readSnapshots } from './db-backup.mjs';
+
+/** Marker prefix for lib/record-once.mjs. Per project, like the skew one. */
+export const DB_UNUSABLE_MARKER_PREFIX = '.db-unusable-logged-';
+
+// SQLite's own spellings for "this file is not a usable database". Kept here as the single
+// definition so install.mjs's doctor check and the hook path classify identically — they used
+// to hold one copy each, which is this repo's named twin-drift class.
+//
+// Deliberately NOT matching "unable to open database file": that is a PERMISSIONS or
+// missing-directory failure, whose remedy is nothing like the two below, and answering it
+// with "move the file aside" would tell a user to destroy a healthy store.
+const UNUSABLE_RE = /not a database|disk image is malformed/i;
+
+/**
+ * Whether an error is a damaged FTS5 INDEX rather than a damaged database file.
+ *
+ * THE MESSAGE CANNOT TELL THEM APART. SQLite reports a damaged index as
+ * SQLITE_CORRUPT_VTAB with the same "database disk image is malformed" text the file-level
+ * faults use, so the code is the only discriminator — and matching on message alone is what
+ * conflated them before R10 P3-9. The remedy is rebuildFTS, which the FTS content lets us do
+ * losslessly; treating it as file corruption would offer `cp <old snapshot> <db>` over a
+ * database whose rows are all intact.
+ *
+ * This lives HERE rather than in schema.mjs (which re-exports it, so every existing importer
+ * is unchanged) because both consumers of the distinction now need it and schema.mjs imports
+ * better-sqlite3 — a classifier the hook path may need while the binding is the broken thing
+ * must not be behind a native import.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isFtsCorruptionError(err) {
+  return /SQLITE_CORRUPT_VTAB/i.test(`${err?.code || ''}`);
+}
+
+/**
+ * True when `err` means "this file exists and SQLite cannot use it as a database".
+ *
+ * Accepts anything thrown (Error, string, null) because recordHookError does.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isDbUnusableError(err) {
+  if (!err) return false;
+  // FIRST, and for the same reason isDbCorruptionError does it first: a damaged index is a
+  // HEALTHY FILE, and every remedy below is wrong — and destructive — for one.
+  if (isFtsCorruptionError(err)) return false;
+  return UNUSABLE_RE.test(String(err.message ?? err ?? ''));
+}
+
+/**
+ * What the user should actually run. Three outcomes, never two — the same rule schema-skew.mjs
+ * states: "there is no backup" and "I could not look for one" must not print in the same
+ * voice, because a green-sounding line ends the reader's search.
+ *
+ * `snapshotCount` is part of the return rather than something a caller re-derives: doctor's
+ * sentence names it ("Restore the newest of 2 backup snapshot(s)"), and a second
+ * `readSnapshots` call to recover a number this function already had would be a second
+ * directory read that can disagree with the first.
+ *
+ * @param {string} dbPath
+ * @returns {{kind: 'restore'|'set-aside'|'unknown', command: string, note: string, snapshotCount: number}}
+ */
+export function dbUnusableRemedy(dbPath) {
+  const clear = `rm -f "${dbPath}-wal" "${dbPath}-shm"`;
+  const snap = readSnapshots(dbPath);
+  if (!snap.ok) {
+    return {
+      kind: 'unknown',
+      command: '',
+      snapshotCount: 0,
+      note:
+        `Could not read ${dirname(dbPath)} to look for a backup snapshot (${snap.reason}) — ` +
+        `fix that directory first, then look for ${basename(dbPath)}.*.bak beside the database.`,
+    };
+  }
+  if (snap.snapshots.length === 0) {
+    return {
+      kind: 'set-aside',
+      command: `${clear} && mv "${dbPath}" "${dbPath}.corrupt"`,
+      snapshotCount: 0,
+      note:
+        'No backup snapshot exists beside the database. That command sets the broken file ' +
+        'aside so a fresh store is created on the next session — memories in it are not ' +
+        'recoverable without a backup.',
+    };
+  }
+  // Newest by mtime, ties broken by name (which carries an ISO stamp) so the answer is total
+  // rather than dependent on readdir order — the D#9 shape.
+  const newest = snap.snapshots
+    .slice()
+    .sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1))[0];
+  return {
+    kind: 'restore',
+    command: `${clear} && cp "${newest.path}" "${dbPath}"`,
+    snapshotCount: snap.snapshots.length,
+    note:
+      `Restores the newest of ${snap.snapshots.length} backup snapshot(s). Move the broken ` +
+      'file aside first if you want to keep it for inspection.',
+  };
+}
+
+/**
+ * The user-facing block. Short on purpose — at SessionStart it shares one stdout envelope
+ * with the startup dashboard and the `<claude-mem-context>` block.
+ *
+ * @param {{dbPath: string, remedy: ReturnType<typeof dbUnusableRemedy>}} info
+ * @returns {string}
+ */
+export function formatDbUnusableNotice({ dbPath, remedy }) {
+  const lines = [
+    '⚠️ [claude-mem-lite] Memory is OFF: the database file cannot be opened.',
+    `   ${dbPath} exists but SQLite does not recognise it as a database.`,
+  ];
+  if (remedy.command) lines.push(`   ${remedy.command}`);
+  if (remedy.note) lines.push(`   ${remedy.note}`);
+  lines.push('   Until then, saves and recall are disabled. `claude-mem-lite doctor` re-checks.');
+  return lines.join('\n');
+}
+
+/**
+ * The same fact, with NO COMMAND IN IT, for the model channel.
+ *
+ * The schema-skew twin sends one string to both channels and that is safe there — its
+ * commands are `git pull` / `claude plugin update` / `npm i -g`. This family's remedy is
+ * `rm -f …-wal …-shm && cp "<snapshot>" "<db>"`, which OVERWRITES the database, and handing
+ * a ready-to-run irreversible shell line to an agent that has Bash — with no addressee and no
+ * "ask first" — is a different proposition. Worse, the restore arm defeats its own advice: a
+ * reader who acts on the command line destroys the broken file the next line tells them to
+ * keep for inspection.
+ *
+ * So the human gets the command and the model gets the situation. Both still learn memory is
+ * off, which is the point of using both channels at all.
+ *
+ * @returns {string}
+ */
+export function formatDbUnusableModelNotice() {
+  return [
+    '⚠️ [claude-mem-lite] Memory is OFF for this session: the database file is unreadable.',
+    '   Saves and recall are disabled. Do not attempt to repair it yourself — tell the user to',
+    '   run `claude-mem-lite doctor`, which prints the exact command for their machine.',
+  ].join('\n');
+}