claude-mem-lite 6.2.0 → 6.3.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.2.0",
+      "version": "6.3.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": "6.2.0",
+  "version": "6.3.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-shared.mjs

@@ -22,6 +22,12 @@ import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 // Pure-`node:`/local module (it imports only binding-probe + native-binding-hint, and
 // neither imports this file) — no cycle.
 import { recordHookError } from './lib/hook-telemetry.mjs';
+import {
+  isSchemaSkewError,
+  schemaSkewFromError,
+  shouldRecordSkew,
+  SKEW_MARKER_PREFIX,
+} from './lib/schema-skew.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,
@@ -237,6 +243,7 @@ export const GC_PROJECT_MARKER_PREFIXES = Object.freeze([
   // forever. `.skill-cooldown-` / `.skill-reco-cooldown-` left with the skill registry in
   // 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
 ]);
 
 // Records of a completed side effect — never age out. `ep-`/`ep-flush-`/
@@ -382,12 +389,58 @@ export function createSessionId() {
 
 // ─── Database ────────────────────────────────────────────────────────────────
 
+// Last forward-incompat ("the DB is newer than me") failure seen in THIS process, or null.
+// SessionStart needs the two version numbers to render its notice and openDb has just been
+// handed them, so this beats a second DB open — and on a skew there may be no working
+// binding to open with anyway.
+let lastSkew = null;
+
+/**
+ * The schema skew that made the most recent openDb() return null, or null.
+ * Cleared by any successful open, so a heal mid-session stops the notice.
+ *
+ * @returns {{dbVersion: number|null, binaryVersion: number|null}|null}
+ */
+export function lastSchemaSkew() {
+  return lastSkew;
+}
+
 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.
-    return ensureDbWithWalRecovery();
+    const db = ensureDbWithWalRecovery();
+    lastSkew = null;
+    return db;
   } catch (e) {
+    // Forward-incompat is its own family: it cannot be healed by anything this process can
+    // do, it repeats on every single open, and it is the one failure the USER has to act on.
+    // Record it once and hand the numbers to SessionStart, which is the surface that speaks.
+    // Forward-incompat is its own family: nothing this process can do heals it, it repeats on
+    // every single open, and it is the one failure the USER has to act on. Dedup lives in
+    // lib/schema-skew.mjs so the `ups` face — which opens the DB itself and logged its own 15
+    // of the day's 727 lines — shares one implementation instead of drifting from this one.
+    //
+    // 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
+    // no-op on null and none of them expects an exception.
+    if (isSchemaSkewError(e)) {
+      lastSkew = schemaSkewFromError(e) || { dbVersion: null, binaryVersion: null };
+      // 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.
+      let project = '';
+      try {
+        project = inferProject();
+      } catch {
+        /* total: the marker degrades to one shared file */
+      }
+      if (shouldRecordSkew(RUNTIME_DIR, project, lastSkew)) {
+        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
     // eight 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`

package/hook-update.mjs

@@ -228,7 +228,11 @@ function isPluginMode() {
 }
 
 // ── Dev Mode Detection ─────────────────────────────────────
-function isDevMode() {
+// Exported since the schema-skew notice needs it: a dev checkout must be told `git pull`,
+// never a command that would overwrite its working tree. Re-implementing the check at the
+// call site would make it the second copy of a predicate this file has already had to get
+// right twice (whole-dir symlink, then per-file drift) — the twin-drift class.
+export function isDevMode() {
   try {
     // A dev checkout always carries a .git dir. This catches a whole-directory
     // symlink (~/.claude-mem-lite -> /repo): lstat on server.mjs there follows the

package/hook.mjs

@@ -60,7 +60,9 @@ import {
   episodeHasSignificantContent,
   explainSignificance,
 } from './hook-episode.mjs';
-import { DB_DIR } from './schema.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 { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-context.mjs';
 import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
@@ -82,6 +84,7 @@ import {
   spawnBackground,
   sweepOrphanEpisodeFiles,
   sweepStaleProjectMarkers,
+  lastSchemaSkew,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveEpisodeImmediate } from './hook-llm.mjs';
 import { readFastSummarySource, insertFastSummary, FAST_SUMMARY_LIMITS } from './lib/fast-summary.mjs';
@@ -2290,6 +2293,67 @@ async function buildStartupDashboardText(db, project) {
   }
 }
 
+/**
+ * Tell the user their memory is version-skewed, on the one surface they read.
+ *
+ * Only fires when openDb() failed for THIS reason — hook-shared records the two version
+ * numbers as it catches, so nothing is re-derived and no second DB open is attempted (on a
+ * skew there may be no usable binding to open with).
+ *
+ * Everything is dynamically imported: this is a cold path that must not cost the healthy
+ * SessionStart an install-shape scan. And it goes through the queue helpers, never a bare
+ * console.log — SessionStart merges three would-be stdout contributors into ONE envelope,
+ * and writing raw prose alongside it once made the host deliver the whole JSON object to
+ * the model as literal text (tests/session-start-stdout-envelope.test.mjs).
+ */
+async function emitSchemaSkewNotice() {
+  try {
+    const skew = lastSchemaSkew();
+    if (!skew) return;
+    const [shapeMod, updateMod, skewMod] = await Promise.all([
+      import('./lib/install-shape.mjs'),
+      import('./hook-update.mjs'),
+      import('./lib/schema-skew.mjs'),
+    ]);
+    const shape = shapeMod.detectInstallShape({ installDir: CODE_DIR });
+    // WHICH tree is running this hook, not which trees exist. CLAUDE_PLUGIN_ROOT is set in
+    // every hook process Claude Code spawns, so on a machine holding BOTH a managed install
+    // and a plugin cache it is the only thing that knows which one is behind. Deciding from
+    // the machine's global shape printed `claude-mem-lite self-update` beneath a line naming
+    // the plugin cache — a repair that cannot advance the tree it had just named.
+    const runningRoot = process.env.CLAUDE_PLUGIN_ROOT || CODE_DIR;
+    const remedy = skewMod.schemaSkewRemedy({
+      managed: shape.managed,
+      activePluginVersion: shape.activePluginVersion,
+      dev: updateMod.isDevMode(),
+      root: runningRoot,
+    });
+    const notice = skewMod.formatSchemaSkewNotice({
+      dbVersion: skew.dbVersion,
+      binaryVersion: skew.binaryVersion,
+      remedy,
+      // Name the home only when the remedy is about that home, so the two can never disagree.
+      codeHome:
+        remedy.kind === 'plugin' && shape.activePluginVersion
+          ? `plugin cache v${shape.activePluginVersion.version}`
+          : undefined,
+    });
+    // BOTH channels, and the HUMAN one is the point. queueHookContext reaches the model;
+    // lib/hook-stdout.mjs's queueHookSystemMessage is documented "for the HUMAN, not the
+    // model" and names v3.70.0 for making exactly this mistake — folding a banner into
+    // additionalContext "kept its content and lost its audience". A notice whose whole job is
+    // to hand the user a command must not depend on the assistant volunteering it.
+    // flushHookStdout merges both into one envelope, so this is additive: the model learns
+    // memory is unavailable, the user gets the repair.
+    queueHookSystemMessage(notice);
+    queueHookContext('SessionStart', notice);
+  } catch (e) {
+    // A hook must never crash the host session, and a notice that cannot render is still
+    // better handled by staying quiet than by taking SessionStart down with it.
+    debugCatch(e, 'session-start-schema-skew');
+  }
+}
+
 async function handleSessionStart() {
   // GC stale per-session cooldown files. Cheap (<5ms typical) and idempotent;
   // moved here from pre-tool-recall.js's hot path.
@@ -2471,7 +2535,16 @@ async function handleSessionStart() {
   const project = inferProject();
 
   const db = openDb();
-  if (!db) return;
+  if (!db) {
+    // A null DB used to end SessionStart in total silence. For most causes that is right —
+    // they are transient, or a repair path is already running. Forward-incompat is neither:
+    // it persists until the user installs newer code, it disables every write path, and the
+    // 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.
+    await emitSchemaSkewNotice();
+    return;
+  }
 
   try {
     const now = new Date();

package/install.mjs

@@ -70,6 +70,7 @@ import {
   nativeBindingRepairHint,
 } from './lib/binding-probe.mjs';
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
+import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.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';
@@ -1479,6 +1480,73 @@ async function doctor() {
     }
   }
 
+  // Can each code home actually OPEN this database? A binding that loads is not the same
+  // question: better-sqlite3 can be perfect and the store still unreadable, because
+  // schema.mjs refuses a DB written by a newer claude-mem-lite (correctly — replaying old
+  // migrations over a newer layout would corrupt it). That is a one-way ratchet, and on a
+  // plugin install it is REACHED ROUTINELY: the cache only advances when Claude Code's
+  // marketplace updater advances it, so anything else that opens the DB — an npm-global
+  // CLI, a dev checkout — can leave the cache locked out. Measured 2026-09-08: DB v49 vs a
+  // live 5.6.0 cache supporting v48, >=648 identical hook errors in one day, and the only
+  // user-visible signal was `-32000 Connection closed` from the MCP host.
+  //
+  // Probed per root, out of process, exactly like the binding check above and for the same
+  // reason: this is the check that has to survive answering the question, and importing
+  // another tree's schema.mjs would poison the process that must report the answer. It is
+  // also why this check is USEFUL TODAY rather than only after the next upgrade — doctor
+  // runs from whichever tree the user invoked, so new code here can diagnose an old cache.
+  if (!existsSync(DB_PATH)) {
+    ok('DB schema: no database yet — nothing to compare');
+  } else if (rootProbes.length === 0) {
+    // The fourth outcome the first cut had and did not print. The `fail` above already tells
+    // the reader no install owns a binding, but a block whose stated design point is "three
+    // outcomes, never two" must not answer a fourth case with silence.
+    dwarn('DB schema: not checked — no install on this machine owns a native binding to read it with');
+  } else {
+    const compat = probeSchemaCompat(shape.runtimeRoots, DB_PATH);
+    const behind = compat.filter((c) => c.status === 'skew');
+    const unknown = compat.filter((c) => c.status === 'unknown');
+    if (behind.length === 0 && unknown.length === 0) {
+      ok(`DB schema: v${compat[0]?.dbVersion} — readable by all ${compat.length} install(s)`);
+    }
+    if (behind.length > 0) {
+      // Dynamic: only a skewed machine pays for it, and it reuses hook-update's isDevMode
+      // rather than re-deriving "is this a checkout", which that file has already had to
+      // correct twice (whole-dir symlink, then per-file drift).
+      let dev = false;
+      try {
+        const { isDevMode } = await import('./hook-update.mjs');
+        dev = isDevMode();
+      } catch {
+        /* unreadable → the initialiser stands: a non-dev install gets the common remedy */
+      }
+      for (const b of behind) {
+        // PER ROOT, inside the loop. Computing one remedy for every skewed tree printed the
+        // machine's global answer beneath a label naming a different tree — on a mixed
+        // managed+plugin install that meant `self-update` under "plugin cache v5.6.0",
+        // which advances nothing. b.root is the tree that is actually behind.
+        const remedy = schemaSkewRemedy({
+          managed: shape.managed,
+          activePluginVersion: shape.activePluginVersion,
+          dev,
+          root: b.root,
+        });
+        // fail, not warn: every write path is dead in this state and only the user can fix it.
+        fail(`DB schema v${b.dbVersion} is newer than ${b.label}, which supports up to v${b.supported}`);
+        for (const c of remedy.commands) log(`    ${c}`);
+        if (remedy.note) log(`    ${remedy.note}`);
+        issues++;
+      }
+    }
+    for (const u of unknown) {
+      // Deliberately its own outcome. "I could not determine what this install supports"
+      // printed as a green line is the defect the v6.2.0 round wrote and its pre-ship review
+      // caught before the tag — a check that says "nothing to check" and "I could not look"
+      // in the same voice ends the reader's search instead of directing it.
+      dwarn(`DB schema: could not determine compatibility for ${u.label} (${u.error})`);
+    }
+  }
+
   try {
     await import('@modelcontextprotocol/sdk/server/mcp.js');
     ok('@modelcontextprotocol/sdk: verified (import OK)');

package/lib/schema-skew.mjs

@@ -0,0 +1,379 @@
+// lib/schema-skew.mjs — the DB is NEWER than the code trying to open it.
+//
+// schema.mjs's forward-incompat guard has thrown on this for a long time and the throw is
+// correct: an old binary that re-applied old migrations over a newer layout would corrupt
+// the store. What was missing is everything downstream of the throw.
+//
+// Measured 2026-09-08 on a plugin-mode machine: DB v49, live plugin cache 5.6.0 (supports
+// v48). Every `openDb()` threw, `hook-shared` logged each one, and the day's
+// runtime/hook-errors/*.jsonl held >=648 copies of one sentence and was still growing. The
+// MCP server died before its handshake, so the host showed `-32000 Connection closed`. And
+// hook.mjs's `const db = openDb(); if (!db) return;` made SessionStart return in silence.
+// Nothing the user could see said "your memory is version-skewed".
+//
+// Two design points that are easy to get wrong, both of which this repo has paid for before:
+//
+//   • THE REMEDY IS SHAPE-DEPENDENT. The thrown message says
+//     `npm i -g claude-mem-lite@latest`. That is right for a managed/npm install and inert
+//     for a plugin-cache install — which is the shape that actually hits this, because the
+//     cache only advances when Claude Code's marketplace updater advances it, so it lags
+//     anything else that opened the DB. A repair that cannot work is worse than silence:
+//     the user runs it, sees success, and stops looking.
+//
+//   • THREE OUTCOMES, NEVER TWO. "this home can open the DB" and "I could not determine
+//     what this home supports" must never print in the same voice. The v6.2.0 round WROTE a
+//     doctor check that answered "no hook command needs bash" on the one install shape where
+//     they are live, because a missing file read as a zero count — and its pre-ship review
+//     caught it before the tag (`f5e1786`), so it never shipped. Read that as the precedent
+//     it is: the defect is easy to write and invisible to unit tests. `status: 'unknown'`
+//     exists so it cannot be written here.
+//
+// This module is shared by hook-shared.mjs, hook.mjs, install.mjs (doctor) and
+// scripts/launch.mjs, so per the project's own rule it lives in lib/ and is registered in
+// BOTH source-files.mjs and package.json#files.
+//
+// It deliberately does NOT import better-sqlite3 at module scope: two of its consumers run
+// on paths where the native binding may be the thing that is broken, and a classifier that
+// cannot load is a classifier that cannot report. The only DB access here happens inside a
+// child process (probeSchemaCompatInFreshProcess).
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** Machine-readable marker set by schema.mjs on the forward-incompat throw. */
+export const SCHEMA_SKEW_CODE = 'CLAUDE_MEM_SCHEMA_TOO_NEW';
+
+// PER PROJECT. The first version of this dedup used one marker file for the whole data dir,
+// keyed on a per-project session id — so two projects sharing ~/.claude-mem-lite overwrote
+// each other's key and every fire recorded again. Measured by review: 8 fires across 2
+// projects → 8 records; the same 8 fires in 1 project → 1. The flood this exists to stop was
+// therefore unfixed for exactly the multi-project machine that produced it.
+export const SKEW_MARKER_PREFIX = '.schema-skew-logged-';
+
+// Skew persists until the user installs newer code, so "record it once" would be defensible.
+// An hour is the compromise: the log's remaining job is forensic ("when did this start, is it
+// still happening"), and ≤24 lines/day/project answers that at a cost the 727-in-one-day
+// measurement makes look free.
+export const SKEW_RELOG_INTERVAL_MS = 60 * 60 * 1000;
+
+/**
+ * Should this skew be written to the hook-error log, or has it been recorded recently?
+ *
+ * TOTAL — every path returns a boolean, nothing escapes. That is a hard requirement, not
+ * defensiveness: callers invoke this from inside a DB-open failure handler, and `openDb()`'s
+ * contract is to return null and never throw. The first version called `getSessionId()` here,
+ * which is not a read — it MINTS and writes a session id — so an unwritable runtime dir
+ * (EROFS, ENOSPC, a dismounted CLAUDE_MEM_DIR) made the catch block itself throw. Two-arm
+ * proof at the time: HEAD threw ENOTDIR where the previous build returned null.
+ *
+ * Fails toward RECORDING: an unreadable or unwritable marker must never silence the log.
+ *
+ * @param {string} runtimeDir
+ * @param {string} project Marker scope; anything falsy collapses to one shared file.
+ * @param {{dbVersion?: number|null, binaryVersion?: number|null}|null} info
+ * @param {{now?: number, intervalMs?: number}} [opts]
+ * @returns {boolean}
+ */
+export function shouldRecordSkew(
+  runtimeDir,
+  project,
+  info,
+  { now = Date.now(), intervalMs = SKEW_RELOG_INTERVAL_MS } = {},
+) {
+  try {
+    const scope = String(project || 'unscoped').replace(/[^A-Za-z0-9._-]/g, '_');
+    const file = join(runtimeDir, SKEW_MARKER_PREFIX + scope);
+    const key = `${info?.dbVersion ?? '?'}:${info?.binaryVersion ?? '?'}`;
+    try {
+      const prev = JSON.parse(readFileSync(file, 'utf8'));
+      // A changed version pair always re-records: a PARTIAL upgrade (the binary moves v48→v49
+      // while the DB moves to v50) is new information, not the fault we already logged.
+      if (prev.key === key && typeof prev.ts === 'number' && now - prev.ts < intervalMs) return false;
+    } catch {
+      /* absent, unreadable or corrupt → record */
+    }
+    try {
+      // The dir may not exist yet. hook-shared creates RUNTIME_DIR at module scope, but the
+      // `ups` face does not import it — so on a fresh data dir the first marker write failed
+      // silently and the SECOND fire recorded again. Measured: 4 ups fires produced 2 records
+      // instead of 1, both from the same call site, with the marker present afterwards.
+      mkdirSync(runtimeDir, { recursive: true });
+      writeFileSync(file, JSON.stringify({ key, ts: now }), { mode: 0o600 });
+    } catch {
+      /* an unwritable marker must not suppress the record */
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+// The shipped message, which older builds throw with no code field at all. Kept as a
+// fallback classifier so this module can still recognise a skew raised by code that
+// predates SCHEMA_SKEW_CODE — the interesting direction, since skew means old code.
+const SKEW_MESSAGE_RE = /DB schema is v(\d+) but this claude-mem-lite binary supports up to v(\d+)/;
+const SKEW_MESSAGE_LOOSE_RE = /DB schema is v\d+/;
+
+/**
+ * True when `err` means "this DB was written by a newer claude-mem-lite".
+ *
+ * Accepts anything thrown (Error, string, null) because recordHookError does.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isSchemaSkewError(err) {
+  if (!err) return false;
+  if (err.code === SCHEMA_SKEW_CODE) return true;
+  return SKEW_MESSAGE_LOOSE_RE.test(String(err.message ?? err ?? ''));
+}
+
+/**
+ * The two version numbers, from the error's own fields when present and from its message
+ * otherwise. Null when this is not a skew error, or when neither source carries numbers.
+ *
+ * @param {unknown} err
+ * @returns {{dbVersion: number, binaryVersion: number}|null}
+ */
+export function schemaSkewFromError(err) {
+  if (!err) return null;
+  if (typeof err.dbVersion === 'number' && typeof err.binaryVersion === 'number') {
+    return { dbVersion: err.dbVersion, binaryVersion: err.binaryVersion };
+  }
+  const m = SKEW_MESSAGE_RE.exec(String(err.message ?? err ?? ''));
+  if (!m) return null;
+  return { dbVersion: Number(m[1]), binaryVersion: Number(m[2]) };
+}
+
+/** Same directory, tolerating symlinks — a plugin cache root reaches callers both ways. */
+function samePath(a, b) {
+  if (!a || !b) return false;
+  if (resolve(a) === resolve(b)) return true;
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Both halves are needed and the order matters: the local marketplace clone is what Claude
+ * Code compares against, so an outdated clone makes `/plugin update` a no-op that reports
+ * success. Measured 2026-09-08: the clone sat 22 commits behind while npm and GitHub already
+ * carried the version that owned the DB.
+ */
+function pluginRemedy(activePluginVersion, marketplace, plugin) {
+  return {
+    kind: 'plugin',
+    commands: [`/plugin marketplace update ${marketplace}`, `/plugin update ${plugin}@${marketplace}`],
+    note: `Run both in Claude Code, then restart it. Plugin cache is at v${activePluginVersion.version}.`,
+  };
+}
+
+/**
+ * Which command actually repairs this machine — or, when `root` is given, the tree that is
+ * actually behind. Pass `root` whenever you know it; the machine's global shape is the
+ * fallback, and on a mixed install it is the wrong answer.
+ *
+ * @param {{managed?: boolean, activePluginVersion?: {version: string}|null, dev?: boolean, marketplace?: string, plugin?: string}} shape
+ * @returns {{kind: 'dev'|'plugin'|'managed'|'unknown', commands: string[], note: string}}
+ */
+export function schemaSkewRemedy({
+  managed = false,
+  activePluginVersion = null,
+  dev = false,
+  root = null,
+  marketplace = 'sdsrss',
+  plugin = 'claude-mem-lite',
+} = {}) {
+  // THE ROOT WINS when the caller knows which tree is behind. A machine can hold a managed
+  // install AND a plugin cache at once, and `hasManagedCodeInstall` is true for a dev
+  // checkout too (existsSync follows symlinks). Deciding from the machine's global shape
+  // then printed `claude-mem-lite self-update` under a line reading "the code running here
+  // (plugin cache v5.6.0)" — neither command advances a plugin cache. That is verbatim the
+  // failure this module's header calls its reason to exist, reproduced end to end by review
+  // on the exact version pair from the motivating measurement.
+  if (root && activePluginVersion?.root && samePath(root, activePluginVersion.root)) {
+    return pluginRemedy(activePluginVersion, marketplace, plugin);
+  }
+  // Dev next: a checkout's files are symlinked or git-managed, so every other remedy would
+  // overwrite the user's working tree.
+  if (dev) {
+    return {
+      kind: 'dev',
+      commands: ['git pull'],
+      note: 'This is a development checkout — something newer than this working tree opened the DB.',
+    };
+  }
+  if (activePluginVersion && !managed) {
+    return pluginRemedy(activePluginVersion, marketplace, plugin);
+  }
+  if (managed) {
+    return {
+      kind: 'managed',
+      commands: ['claude-mem-lite self-update'],
+      note: 'Or reinstall with: npm i -g claude-mem-lite@latest',
+    };
+  }
+  // Not "nothing to do" — "I could not tell". Name both places that were consulted so the
+  // reader knows where to look rather than assuming the check found nothing wrong.
+  return {
+    kind: 'unknown',
+    commands: [],
+    note: 'Could not identify this install: no managed code install in ~/.claude-mem-lite and no active plugin cache version. Run `claude-mem-lite doctor` from the install you actually use.',
+  };
+}
+
+/**
+ * The user-facing block. Kept short on purpose — at SessionStart it shares one stdout
+ * envelope with the startup dashboard and the `<claude-mem-context>` block.
+ *
+ * @param {{dbVersion: number|null, binaryVersion: number|null, remedy: ReturnType<typeof schemaSkewRemedy>, codeHome?: string}} info
+ * @returns {string}
+ */
+export function formatSchemaSkewNotice({ dbVersion, binaryVersion, remedy, codeHome }) {
+  const where = codeHome ? ` (${codeHome})` : '';
+  const lines = [
+    '⚠️ [claude-mem-lite] Memory is OFF: this database was written by a newer version.',
+    `   DB schema v${dbVersion ?? '?'}; the code running here${where} supports up to v${binaryVersion ?? '?'}.`,
+  ];
+  for (const c of remedy.commands) lines.push(`   ${c}`);
+  if (remedy.note) lines.push(`   ${remedy.note}`);
+  lines.push('   Until then, saves and recall are disabled. Your stored memories are intact.');
+  return lines.join('\n');
+}
+
+/**
+ * The child-process source for one code home. Exported so a test can pin the contract
+ * without spawning, and so the string is reviewable in isolation.
+ *
+ * Both paths are ASKED, never derived: the supported version comes from importing that
+ * home's own schema.mjs, and the DB version from opening the DB with that home's own
+ * better-sqlite3. Parsing `export const CURRENT_SCHEMA_VERSION = \d+` out of the file
+ * would be the same mistake as naming the native addon's path instead of asking
+ * lib/binding.js for it — a literal that goes stale silently.
+ *
+ * The payload is BRACKETED. Importing another tree's schema.mjs runs that tree's module
+ * scope, and anything it prints lands on the same stdout — so a bare `JSON.parse(stdout)`
+ * turned "this home is fine" into "could not determine" for any code home that logs on
+ * import. Review demonstrated it with a one-line `console.log`. Sentinels cost nothing and
+ * make the channel robust to a co-tenant instead of assuming it is empty.
+ *
+ * @param {string} root
+ * @param {string} dbPath
+ * @returns {string}
+ */
+export function schemaCompatProbeSource(root, dbPath) {
+  const pkg = JSON.stringify(join(root, 'package.json'));
+  const schemaUrl = JSON.stringify(pathToFileURL(join(root, 'schema.mjs')).href);
+  const db = JSON.stringify(dbPath);
+  const open = JSON.stringify(PROBE_BEGIN);
+  const close = JSON.stringify(PROBE_END);
+  return (
+    '(async () => { const out = {};' +
+    `try { const m = await import(${schemaUrl});` +
+    ' out.supported = typeof m.CURRENT_SCHEMA_VERSION === "number" ? m.CURRENT_SCHEMA_VERSION : null; }' +
+    ' catch (e) { out.supportedError = String((e && e.message) || e); }' +
+    'try { const { createRequire } = require("node:module");' +
+    ` const D = createRequire(${pkg})("better-sqlite3");` +
+    ` const d = new D(${db}, { readonly: true, fileMustExist: true });` +
+    ' const r = d.prepare("SELECT version FROM schema_version LIMIT 1").get();' +
+    ' d.close();' +
+    ' out.dbVersion = r && typeof r.version === "number" ? r.version : null; }' +
+    ' catch (e) { out.dbError = String((e && e.message) || e); }' +
+    `process.stdout.write(${open} + JSON.stringify(out) + ${close}); })()`
+  );
+}
+
+// Deliberately unlikely to appear in a module's own logging, and matched with lastIndexOf so
+// a tree that echoes the sentinel itself still loses to the real payload written last.
+const PROBE_BEGIN = '<<claude-mem-schema-probe>>';
+const PROBE_END = '<</claude-mem-schema-probe>>';
+
+/** The bracketed payload, or null when the child never got as far as writing one. */
+function extractProbePayload(stdout) {
+  const s = String(stdout || '');
+  const a = s.lastIndexOf(PROBE_BEGIN);
+  if (a < 0) return null;
+  const b = s.indexOf(PROBE_END, a);
+  if (b < 0) return null;
+  try {
+    return JSON.parse(s.slice(a + PROBE_BEGIN.length, b));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Can THIS code home open THIS database?
+ *
+ * Out of process for the same reason every other probe here is: importing another tree's
+ * schema.mjs and dlopen'ing its better-sqlite3 would poison the calling process, and doctor
+ * has to survive answering the question.
+ *
+ * @param {string} root Code home (holds schema.mjs and node_modules)
+ * @param {string} dbPath
+ * `spawn` is injectable so the "child produced no parseable stdout" branch can be driven at
+ * all. THE ORIGINAL REASON GIVEN HERE WAS WRONG and is corrected rather than quietly
+ * dropped: it claimed the branch was reachable only from a native crash and could not be
+ * provoked from a test. Review falsified that in one step — a code home whose schema.mjs
+ * writes anything to stdout at module scope (a `console.log`, or any import that logs)
+ * pollutes the JSON payload and lands here through the real function, exit 0. So the branch
+ * is ORDINARY, not exotic: any tree that logs on import degrades a correct verdict into a
+ * doctor ⚠. That is why the child now brackets its payload with a sentinel and this function
+ * reads only what is inside it — the seam remains for the genuinely unreachable shapes
+ * (a native crash leaving both streams empty, a spawn that never starts).
+ *
+ * @param {{timeoutMs?: number, spawn?: (cmd: string, args: string[], opts: object) => object}} [opts]
+ * @returns {{status: 'ok'|'skew'|'unknown', supported?: number|null, dbVersion?: number|null, error?: string}}
+ */
+export function probeSchemaCompatInFreshProcess(
+  root,
+  dbPath,
+  { timeoutMs = 15_000, spawn = spawnSync } = {},
+) {
+  const r = spawn(process.execPath, ['-e', schemaCompatProbeSource(root, dbPath)], {
+    stdio: 'pipe',
+    encoding: 'utf8',
+    timeout: timeoutMs,
+  });
+  // Before the status check: spawnSync's `timeout` is SIGTERM-then-wait, so a child that
+  // survives the signal can still exit 0 while r.error is ETIMEDOUT.
+  if (r.error) return { status: 'unknown', error: r.error.message };
+  const out = extractProbePayload(r.stdout);
+  if (!out) {
+    const stderrLine = String(r.stderr || '')
+      .split('\n')
+      .map((l) => l.trim())
+      .find(Boolean);
+    return { status: 'unknown', error: stderrLine || `probe exited ${r.status ?? `on signal ${r.signal}`}` };
+  }
+  const { supported, dbVersion } = out;
+  // Either number missing = unknown. Not 'ok': a home whose schema.mjs would not load is
+  // not a home we just certified, and a DB we could not read is not a DB we compared against.
+  if (typeof supported !== 'number' || typeof dbVersion !== 'number') {
+    return {
+      status: 'unknown',
+      supported: supported ?? null,
+      dbVersion: dbVersion ?? null,
+      error: out.supportedError || out.dbError || 'probe returned no version',
+    };
+  }
+  return { status: supported < dbVersion ? 'skew' : 'ok', supported, dbVersion };
+}
+
+/**
+ * Probe every code home against one DB, so a report can NAME the one that is behind
+ * instead of asserting something global about "the install".
+ *
+ * @param {Array<{label: string, root: string}>} roots
+ * @param {string} dbPath
+ * @param {{probe?: (root: string, dbPath: string) => object}} [deps]
+ * @returns {Array<{label: string, root: string, status: string, supported?: number|null, dbVersion?: number|null, error?: string}>}
+ */
+export function probeSchemaCompat(roots, dbPath, deps = {}) {
+  const probe = deps.probe || ((root, p) => probeSchemaCompatInFreshProcess(root, p));
+  return (roots || []).map(({ label, root }) => ({ label, root, ...probe(root, dbPath) }));
+}

package/mem-cli.mjs

@@ -3,7 +3,7 @@
 // No MCP SDK or heavy deps — only imports schema.mjs and utils.mjs
 
 import { homedir } from 'os';
-import { ensureDbWithWalRecovery, DB_PATH, DB_DIR } from './schema.mjs';
+import { ensureDbWithWalRecovery, DB_PATH, DB_DIR, CODE_DIR } from './schema.mjs';
 import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 import { truncate, typeIcon, inferProject, scrubSecrets, COMPRESSED_PENDING_PURGE } from './utils.mjs';
 import { resolveProject } from './project-utils.mjs';
@@ -79,6 +79,12 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 // 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 {
+  isSchemaSkewError,
+  schemaSkewFromError,
+  schemaSkewRemedy,
+  formatSchemaSkewNotice,
+} from './lib/schema-skew.mjs';
 import { CLI_PATH, CLI_INVOKE } from './cli-path.mjs';
 import {
   parseArgs,
@@ -3670,6 +3676,41 @@ export async function run(argv) {
       process.exitCode = 1;
       return;
     }
+    // Schema skew gets the same treatment as the native-binding family above, and for the
+    // same reason: the raw message ends in `npm i -g claude-mem-lite@latest`, which repairs
+    // nothing on a plugin-cache install — the shape that actually hits this. Four surfaces
+    // were wired before this one, and this is the command a user reaches for right after
+    // `doctor` tells them something is wrong.
+    if (isSchemaSkewError(e)) {
+      const skew = schemaSkewFromError(e) || { dbVersion: null, binaryVersion: null };
+      let shape = { managed: false, activePluginVersion: null };
+      let dev = false;
+      try {
+        const [shapeMod, updateMod] = await Promise.all([
+          import('./lib/install-shape.mjs'),
+          import('./hook-update.mjs'),
+        ]);
+        shape = shapeMod.detectInstallShape({ installDir: CODE_DIR });
+        dev = updateMod.isDevMode();
+      } catch {
+        /* shape unknown → schemaSkewRemedy answers 'unknown', which is its job */
+      }
+      out(
+        formatSchemaSkewNotice({
+          dbVersion: skew.dbVersion,
+          binaryVersion: skew.binaryVersion,
+          remedy: schemaSkewRemedy({
+            managed: shape.managed,
+            activePluginVersion: shape.activePluginVersion,
+            dev,
+            root: process.env.CLAUDE_PLUGIN_ROOT || CODE_DIR,
+          }),
+        }),
+      );
+      out(`[mem] DB path: ${DB_PATH}`);
+      process.exitCode = 1;
+      return;
+    }
     out(`[mem] Error: Cannot open database: ${e.message}`);
     out(`[mem] DB path: ${DB_PATH}`);
     process.exitCode = 1;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.2.0",
+      "version": "6.3.0",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.2.0",
+  "version": "6.3.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",
@@ -102,6 +102,7 @@
     "lib/lesson-bridge.mjs",
     "lib/binding-probe.mjs",
     "lib/install-shape.mjs",
+    "lib/schema-skew.mjs",
     "lib/hook-stdin.mjs",
     "lib/plugin-key.mjs",
     "lib/hook-stdout.mjs",

package/schema.mjs

@@ -8,6 +8,10 @@ import { join } from 'path';
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, chmodSync } from 'fs';
 import { OBS_FTS_COLUMNS, debugCatch } from './utils.mjs';
 import { resolveDataDir } from './lib/resolve-data-dir.mjs';
+// Imported, never re-declared: a hand-copied marker string is this repo's twin-drift
+// class, and every consumer of the forward-incompat throw keys on this exact value.
+// schema-skew.mjs imports nothing local, so this closes no cycle.
+import { SCHEMA_SKEW_CODE } from './lib/schema-skew.mjs';
 
 // DATA location — DB, managed resources, registry DB, runtime/. Honors
 // CLAUDE_MEM_DIR so users can relocate state to a larger/faster volume.
@@ -465,10 +469,21 @@ export function initSchema(db) {
         return db;
       }
       if (row.version > CURRENT_SCHEMA_VERSION) {
-        throw new Error(
+        // The MESSAGE is the long-standing contract (tests/schema.test.mjs and
+        // tests/wal-recovery.test.mjs both match on it, and older builds throw exactly
+        // this), so it is unchanged. The FIELDS are additive: every consumer downstream
+        // used to re-derive these numbers by regexing the sentence, and the `npm i -g`
+        // remedy baked into it is inert for a plugin-cache install — which is the shape
+        // that actually hits this. lib/schema-skew.mjs turns the fields into a
+        // shape-correct repair; see its header for the 2026-09-08 measurement.
+        const err = new Error(
           `DB schema is v${row.version} but this claude-mem-lite binary supports up to v${CURRENT_SCHEMA_VERSION}. ` +
             `A newer version wrote this DB; upgrade claude-mem-lite (npm i -g claude-mem-lite@latest) or point CLAUDE_MEM_DIR to a fresh directory.`,
         );
+        err.code = SCHEMA_SKEW_CODE;
+        err.dbVersion = row.version;
+        err.binaryVersion = CURRENT_SCHEMA_VERSION;
+        throw err;
       }
     }
   } catch (e) {

package/scripts/launch.mjs

@@ -209,26 +209,84 @@ try {
   useDevServer = existsSync(devServer) && lstatSync(devServer).isSymbolicLink();
 } catch {}
 
+// The MCP server opens the DB while it is being imported, so a forward-incompat store
+// (schema.mjs's "DB schema is vN but this binary supports up to vN-1") throws right here
+// and kills the process before the stdio handshake. All the host can say about that is
+// `-32000 Connection closed`, which names nothing — measured 2026-09-08, a full day of it
+// with the real cause visible only in a JSONL file the user has no reason to open.
+//
+// stderr is the one channel a launcher still has at that point. It reaches the plugin's own
+// log rather than the transcript, so this is a diagnosis for whoever goes looking, not a
+// substitute for the SessionStart notice — which is why both exist.
+async function importServerOrExplain(run, { dev = false } = {}) {
+  try {
+    await run();
+  } catch (e) {
+    // The classifier is loaded INSIDE its own try and any failure rethrows the ORIGINAL
+    // error. Importing it unconditionally destroyed `e`: this path exists to diagnose an
+    // install whose files are missing (issue #15), lib/schema-skew.mjs is a brand-new file,
+    // and resolveLaunchEntry can serve the server from dataDir while `../lib/…` still
+    // resolves against ROOT. Proven by review — with the module moved aside the process died
+    // naming ERR_MODULE_NOT_FOUND for the classifier while the real boot failure never
+    // appeared anywhere in the output.
+    let skewMod;
+    try {
+      skewMod = await import('../lib/schema-skew.mjs');
+    } catch {
+      throw e;
+    }
+    if (!skewMod.isSchemaSkewError(e)) throw e;
+    let shape = { managed: false, activePluginVersion: null };
+    try {
+      ({ ...shape } = await import('../lib/install-shape.mjs').then((m) =>
+        m.detectInstallShape({ installDir: dataDir }),
+      ));
+    } catch {
+      /* shape unknown → schemaSkewRemedy answers 'unknown', which is its job */
+    }
+    const skew = skewMod.schemaSkewFromError(e) || { dbVersion: null, binaryVersion: null };
+    process.stderr.write(
+      skewMod.formatSchemaSkewNotice({
+        dbVersion: skew.dbVersion,
+        binaryVersion: skew.binaryVersion,
+        // `dev` is passed because the useDevServer branch IS the dev install by definition —
+        // omitting it told a checkout to `npm i -g` over its own working tree. `root: ROOT`
+        // so a mixed managed+plugin machine gets the remedy for the tree that is behind.
+        remedy: skewMod.schemaSkewRemedy({
+          managed: shape.managed,
+          activePluginVersion: shape.activePluginVersion,
+          dev,
+          root: ROOT,
+        }),
+        codeHome: ROOT,
+      }) + '\n',
+    );
+    process.exit(1);
+  }
+}
+
 if (useDevServer) {
-  await import(pathToFileURL(devServer).href);
+  await importServerOrExplain(() => import(pathToFileURL(devServer).href), { dev: true });
 } else {
   // Preflight: detect incomplete primary install (issue #15) — if relative
   // imports referenced by server.mjs are missing on disk, fall back to the
   // hook-update.mjs-maintained ~/.claude-mem-lite/ copy when healthy, or exit
   // with a clear repair command instead of a Node ERR_MODULE_NOT_FOUND stack.
   const { resolveLaunchEntry } = await import('./launch-preflight.mjs');
-  try {
-    const entry = resolveLaunchEntry({
-      primaryRoot: ROOT,
-      fallbackRoot: dataDir,
-      warn: (msg) => process.stderr.write(msg + '\n'),
-    });
-    await import(pathToFileURL(entry.path).href);
-  } catch (e) {
-    if (e.code === 'INSTALL_INCOMPLETE') {
-      process.stderr.write(e.message + '\n');
-      process.exit(1);
+  await importServerOrExplain(async () => {
+    try {
+      const entry = resolveLaunchEntry({
+        primaryRoot: ROOT,
+        fallbackRoot: dataDir,
+        warn: (msg) => process.stderr.write(msg + '\n'),
+      });
+      await import(pathToFileURL(entry.path).href);
+    } catch (e) {
+      if (e.code === 'INSTALL_INCOMPLETE') {
+        process.stderr.write(e.message + '\n');
+        process.exit(1);
+      }
+      throw e;
     }
-    throw e;
-  }
+  });
 }

package/scripts/user-prompt-search.js

@@ -39,6 +39,7 @@ import {
 import { injectedIdsFileName, mergeInjectedMarker } from '../lib/injected-ids.mjs';
 import { getDeferredByIds } from '../lib/deferred-work.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
+import { isSchemaSkewError, schemaSkewFromError, shouldRecordSkew } from '../lib/schema-skew.mjs';
 
 import { DAY_MS } from '../lib/time-constants.mjs';
 import { envNumber } from '../lib/env-number.mjs';
@@ -773,6 +774,25 @@ async function main() {
       // A failed DB open silently kills EVERY prompt-time injection while `stats`
       // reads zero errors (audit 2026-08-14 M-5) — record before the mandatory
       // swallow. Exact blindness class of the 2026-08-13 pre-recall:db-open outage.
+      //
+      // Schema skew is the one member of that family worth deduplicating: it persists until
+      // the user installs newer code, so it repeats on EVERY prompt. This face opens the DB
+      // itself rather than through hook-shared's openDb, so it needs the gate explicitly —
+      // it contributed 15 of one measured day's 727 identical lines, i.e. the flood was ~98%
+      // closed and not closed. Shared implementation, deliberately: a second copy of a
+      // dedup rule is this repo's twin-drift class.
+      if (isSchemaSkewError(e)) {
+        let project = '';
+        try {
+          project = inferProject();
+        } catch {
+          /* total — the marker degrades to one shared file, never a throw */
+        }
+        if (shouldRecordSkew(RUNTIME_DIR, project, schemaSkewFromError(e))) {
+          recordHookError('ups:db-open', e, RUNTIME_DIR);
+        }
+        return;
+      }
       recordHookError('ups:db-open', e, RUNTIME_DIR);
       return;
     }

package/source-files.mjs

@@ -131,6 +131,7 @@ export const SOURCE_FILES = [
   // Missing from the manifest → an updated install ships a doctor that throws
   // ERR_MODULE_NOT_FOUND on the command users run when something is already wrong.
   'lib/install-shape.mjs',
+  'lib/schema-skew.mjs',
   // Single-envelope stdout for hook processes — imported by hook.mjs. Claude Code
   // parses hook stdout as ONE JSON document; missing from the manifest → an updated
   // install throws ERR_MODULE_NOT_FOUND on every hook fire.