claude-mem-lite 6.2.0 → 6.4.0

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/server.mjs

@@ -7,7 +7,15 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { truncate, typeIcon, inferProject, fmtDate, debugLog, debugCatch } from './utils.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
-import { ensureDbWithWalRecovery, DB_PATH, DB_DIR } from './schema.mjs';
+import { ensureDbWithWalRecovery, DB_PATH, DB_DIR, CODE_DIR } from './schema.mjs';
+// schema.mjs already imports this module for SCHEMA_SKEW_CODE, so it is in the graph before
+// the DB is touched — a static import here adds no cold-start cost.
+import {
+  isSchemaSkewError,
+  schemaSkewFromError,
+  schemaSkewRemedy,
+  formatSchemaSkewNotice,
+} from './lib/schema-skew.mjs';
 import { reRankWithContext, runIdleCleanup, buildServerInstructions } from './search-scoring.mjs';
 import { searchObservationsHybrid } from './search-engine.mjs';
 import {
@@ -153,6 +161,54 @@ try {
     info: (m) => debugLog('INFO', 'server', m),
   });
 } catch (err) {
+  // Schema skew gets the same treatment as the CLI (mem-cli.mjs) and for the same reason:
+  // the raw message ends in `npm i -g claude-mem-lite@latest`, which repairs nothing on the
+  // plugin-cache install that actually hits this.
+  //
+  // This branch has to live HERE rather than in scripts/launch.mjs, which already knows how
+  // to format the notice. server.mjs opens the DB while it is being imported, so the throw
+  // is caught by this block and `process.exit(1)` runs before the launcher's own catch can
+  // ever see it — the launcher's handler is unreachable for this one error. Re-throwing
+  // instead would fix the plugin path and break the npm one, because install.mjs registers
+  // `claude mcp add ... -- node <SERVER_PATH>`, launching this file with no launcher above
+  // it to catch anything. Emitting from here covers both, and the launcher's copy stays as
+  // the handler for failures that happen before this module is reached.
+  if (isSchemaSkewError(err)) {
+    const skew = schemaSkewFromError(err) || { 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'),
+      ]);
+      // CODE_DIR, not DB_DIR: `hasManagedCodeInstall` looks for server.mjs + hook.mjs inside
+      // whatever it is handed, and DB_DIR follows CLAUDE_MEM_DIR. Handing it the relocated DATA
+      // dir reports `managed: false` for a machine that has a managed install, so the remedy
+      // came out as "could not identify this install" or, with any plugin cache present, the
+      // plugin commands printed under a line naming ~/.claude-mem-lite. The three sibling call
+      // sites (mem-cli.mjs, hook.mjs, scripts/launch.mjs) all pass the CODE dir.
+      shape = shapeMod.detectInstallShape({ installDir: CODE_DIR });
+      dev = updateMod.isDevMode();
+    } catch {
+      /* shape unknown → schemaSkewRemedy answers 'unknown', which is its job */
+    }
+    const codeHome = process.env.CLAUDE_PLUGIN_ROOT || import.meta.dirname;
+    console.error(
+      formatSchemaSkewNotice({
+        dbVersion: skew.dbVersion,
+        binaryVersion: skew.binaryVersion,
+        remedy: schemaSkewRemedy({
+          managed: shape.managed,
+          activePluginVersion: shape.activePluginVersion,
+          dev,
+          root: codeHome,
+        }),
+        codeHome,
+      }),
+    );
+    process.exit(1);
+  }
   // Fatal: log and exit with descriptive message (Claude Code shows stderr)
   console.error(`[claude-mem-lite] FATAL: Database cannot be opened: ${err.message}`);
   if (err.walRecoveryAttempted) {

package/source-files.mjs

@@ -55,6 +55,11 @@ export const SOURCE_FILES = [
   // AND hook scripts (pre-tool-recall / post-tool-recall) — ship it
   // or auto-update leaves schema + every hook with ERR_MODULE_NOT_FOUND on each fire.
   'lib/resolve-data-dir.mjs',
+  // DB_DIR / DB_PATH / CODE_DIR. Statically imported by schema.mjs (which re-exports all
+  // three) and by hook-update.mjs, which takes them from HERE so the verified repair path
+  // stays loadable without better-sqlite3. Missing from the manifest → auto-update leaves
+  // schema.mjs and the repair path with ERR_MODULE_NOT_FOUND on every fire.
+  'lib/data-paths.mjs',
   // lib/ — statically imported by hook-llm.mjs (activity) + hook-handoff.mjs (git-state, task-reader);
   // dynamically imported by hook.mjs (startup-dashboard) + mem-cli.mjs (doctor-benchmark, plan-reader).
   'lib/activity.mjs',
@@ -131,6 +136,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.

package/tool-schemas.mjs

@@ -256,7 +256,15 @@ export const memGetSchema = {
 };
 
 export const memDeleteSchema = {
-  ids: coerceIntArray.pipe(z.array(z.number().int()).min(1).max(50)).describe('Observation IDs to delete'),
+  // `.nonoptional()` is not a runtime change — zod already rejected an omitted `ids` here.
+  // It is what keeps the field in the PUBLISHED JSON Schema's `required` array: zod 4's
+  // toJSONSchema({io:'input'}) reads a ZodPipe's input side as accepting `undefined` and
+  // drops the key, so the advertised contract said optional while the server said required.
+  // See tests/tool-schemas.test.mjs, which grades every field against runtime ground truth.
+  ids: coerceIntArray
+    .pipe(z.array(z.number().int()).min(1).max(50))
+    .nonoptional()
+    .describe('Observation IDs to delete'),
   confirm: coerceBool.describe('false=preview what will be deleted, true=execute deletion'),
 };
 
@@ -433,7 +441,8 @@ export const memMaintainSchema = {
 };
 
 export const memUpdateSchema = {
-  id: coerceInt.pipe(z.number().int().positive()).describe('Observation ID to update'),
+  // `.nonoptional()` for the published-`required` reason documented on memDeleteSchema.ids.
+  id: coerceInt.pipe(z.number().int().positive()).nonoptional().describe('Observation ID to update'),
   // CLI parity (cmdUpdate): empty/whitespace title would render as `(untitled)`
   // in every listing — reject here like the CLI does, instead of persisting it.
   title: z
@@ -541,6 +550,10 @@ export const memDeferDropSchema = {
       coerceInt.pipe(z.number().int().positive()),
       z.string().regex(/^D#\d+$/, 'expected D#N or positive integer'),
     ])
+    // `.nonoptional()` for the published-`required` reason documented on memDeleteSchema.ids.
+    // This is the CORE tool of the three — it ships in tools/list, so the drift was visible
+    // to every agent, and the tool's own description already calls the reason "required".
+    .nonoptional()
     .describe('Deferred item id — accepts D#N (raw id) or positive integer (ordinal-within-project)'),
   reason: z.string().min(1).max(500).describe('Why this item is being dropped (required for audit trail)'),
   project: z.string().optional().describe('Project name (default: inferred from CWD)'),