claude-mem-lite 6.2.0 → 6.4.0

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.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.2.0",
+      "version": "6.4.0",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.2.0",
+  "version": "6.4.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",
@@ -24,6 +24,7 @@
     "format": "prettier --write \"**/*.{mjs,js}\"",
     "format:check": "prettier --check \"**/*.{mjs,js}\"",
     "dead-code": "knip",
+    "validate:manifests": "node scripts/validate-plugin-manifests.mjs",
     "audit:metrics": "node scripts/audit-metrics.mjs --md",
     "audit:baseline": "node scripts/audit-metrics.mjs --run-tests --md",
     "test": "vitest run",
@@ -89,6 +90,7 @@
     "lib/err-sampler.mjs",
     "lib/hook-telemetry.mjs",
     "lib/resolve-data-dir.mjs",
+    "lib/data-paths.mjs",
     "lib/export-columns.mjs",
     "lib/file-intel.mjs",
     "lib/reread-guard.mjs",
@@ -102,6 +104,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

@@ -7,18 +7,20 @@ import { homedir } from 'os';
 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';
-
-// DATA location — DB, managed resources, registry DB, runtime/. Honors
-// CLAUDE_MEM_DIR so users can relocate state to a larger/faster volume.
-export const DB_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
-export const DB_PATH = join(DB_DIR, 'claude-mem-lite.db');
-// CODE / install location — server.mjs, hook.mjs, cli.mjs, package.json live
-// here. ALWAYS homedir-rooted: Claude Code's settings.json + MCP registration
-// bake ABSOLUTE paths to server.mjs/hooks, so the code must NOT follow the
-// CLAUDE_MEM_DIR relocation env var (mirrors install.mjs INSTALL_DIR). Equals
-// DB_DIR when CLAUDE_MEM_DIR is unset — the common, non-relocated case.
-export const CODE_DIR = join(homedir(), '.claude-mem-lite');
+// 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';
+
+// The three location constants now live in lib/data-paths.mjs — a leaf module with no
+// package imports — and are re-exported here so every existing importer is unchanged.
+// This file statically imports better-sqlite3, so holding a path constant here made the
+// native driver a load-time dependency of anything that wanted one; that is what put the
+// Ed25519-verified repair path out of reach on a tree with no node_modules. Imported AND
+// re-exported (not `export … from`) because schema.mjs uses DB_DIR / DB_PATH itself.
+// See lib/data-paths.mjs and tests/repair-path-no-native-dep.test.mjs.
+import { DB_DIR, DB_PATH, CODE_DIR } from './lib/data-paths.mjs';
+export { DB_DIR, DB_PATH, CODE_DIR };
 
 // Increment when schema changes (tables, columns, indexes, FTS, migrations)
 //
@@ -465,10 +467,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/hook-launcher.mjs

@@ -31,6 +31,7 @@ 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';
+import { createHash } from 'node:crypto';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const INSTALL_DIR = join(__dirname, '..');
@@ -65,7 +66,16 @@ const DATA_DIR = MEM_DIR && isAbsolute(MEM_DIR) ? MEM_DIR : join(homedir(), '.cl
 // `tests/runtime-dir-single-home.test.mjs` asserts this file still carries the rule.
 const RUNTIME_DIR = join(DATA_DIR, 'runtime'); // runtime-dir:stays-put — serves swap-in-progress only; HOOK_RUNTIME_DIR carries the hook markers
 const HOOK_RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || RUNTIME_DIR;
-const HEAL_MARKER = join(HOOK_RUNTIME_DIR, 'hook-launcher-lastheal');
+// Per CODE HOME, not per machine. The runtime dir is data-dir-relative and therefore SHARED
+// by every install shape on this box — a plugin cache version, a managed ~/.claude-mem-lite,
+// a dev checkout. With one global name, a failed heal attempt for root A silenced root B's
+// heal for the next six hours, and the two are repaired by different commands. The suffix is
+// derived from INSTALL_DIR, which is what `cli.mjs repair` below actually acts on.
+//
+// node:crypto only — the pure-`node:` charter above still holds. No migration: a pre-6.4.0
+// unsuffixed marker is simply ignored, which costs at most one extra heal attempt once.
+const INSTALL_KEY = createHash('sha256').update(INSTALL_DIR).digest('hex').slice(0, 12);
+const HEAL_MARKER = join(HOOK_RUNTIME_DIR, `hook-launcher-lastheal-${INSTALL_KEY}`);
 const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
 // Observable breakage state: written when the launcher degrades a broken install
 // to exit 0, cleared once the install is confirmed healthy. `doctor` reads it so
@@ -89,6 +99,14 @@ const BROKEN_MARKER = join(HOOK_RUNTIME_DIR, 'hook-launcher-broken');
 // SESSION-START only — never on the per-tool hot path, where an npm run would
 // stall the user's edit.
 // Marker dir: HOOK_RUNTIME_DIR (see its definition above for why it is override-aware).
+// BOTH stay machine-wide, unlike HEAL_MARKER above, and the difference is the SUBJECT of the
+// repair. HEAL_MARKER gates `cli.mjs repair`, which fixes THIS install dir. This pair gates
+// the native-binding rebuild, and `install.mjs rebuildBinding()` iterates
+// `shape.runtimeRoots` — "Every code home on this machine, not just the one this file sits
+// in", as its own comment puts it, which is also what install.mjs tells the user. Keying it
+// per code home would let N homes each spawn npm within one 6h window for a repair that
+// already covered all of them. A first cut of this change did exactly that; pre-ship review
+// caught that the justifying comment was false for the command it gates.
 const NB_BROKEN_MARKER = join(HOOK_RUNTIME_DIR, 'native-binding-broken');
 const NB_HEAL_MARKER = join(HOOK_RUNTIME_DIR, 'native-binding-lastheal');
 // Literal, not imported: the pure-`node:` charter above forbids importing lib/
@@ -111,10 +129,13 @@ const CLI_REPAIR = `node ${join(INSTALL_DIR, 'cli.mjs')} repair`;
 
 // Last-resort recovery string for users whose `cli.mjs repair` path
 // itself failed (install.mjs missing / repair errored / retry still drifting).
-// Duplicated in install.mjs::repair() catch; both are reachable when local
-// scripts are broken, so neither can import a shared constant.
+// Duplicated from install.mjs::MANUAL_TARBALL_FALLBACK — the pure-`node:` charter above
+// forbids importing it, and this path is reachable exactly when local scripts are broken.
+// Pinned to that constant by tests/manual-fallback-sync.test.mjs, which also fails if a
+// fifth surface starts hardcoding its own. Resolves the latest RELEASE tag rather than
+// `/tarball` (the default branch, i.e. unreleased WIP).
 const TARBALL_FALLBACK =
-  'T=$(mktemp -d) && curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/tarball | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install';
+  'T=$(mktemp -d) && U=$(curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/releases/latest | grep -o \'"tarball_url"[^,]*\' | cut -d\'"\' -f4) && curl -sL "$U" | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install';
 
 const [, , entryArg, ...rest] = process.argv;
 if (!entryArg) {