claude-mem-lite 4.0.0 → 4.0.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "4.0.0",
+      "version": "4.0.2",
       "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": "4.0.0",
+  "version": "4.0.2",
   "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/README.md

@@ -145,7 +145,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 
 ## Requirements
 
-- **Node.js** >= 20
+- **Node.js** >= 22
 - **Claude Code** CLI installed and configured (`claude` command available)
 - **SQLite3** support (provided by `better-sqlite3`, compiled on install)
 - **Platform**: Linux or macOS (see [Platform Support](#platform-support))

package/hook-optimize.mjs

@@ -169,7 +169,7 @@ export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', proje
   const stmt = db.prepare(`
     SELECT id, title, narrative, type, subtitle, importance, project
     FROM observations
-    WHERE COALESCE(compressed_into, 0) = 0
+    WHERE ${liveObsFilterSql('')}
       AND (concepts IS NULL OR concepts = '')
       AND (facts IS NULL OR facts = '')
       AND lesson_learned IS NULL
@@ -468,7 +468,7 @@ export function extractUniqueConcepts(db, limit = 500, { project } = {}) {
   const projectClause = project ? 'AND project = ?' : '';
   const stmt = db.prepare(`
     SELECT concepts FROM observations
-    WHERE COALESCE(compressed_into, 0) = 0
+    WHERE ${liveObsFilterSql('')}
       AND concepts IS NOT NULL AND concepts != ''
       ${projectClause}
     ORDER BY created_at_epoch DESC
@@ -536,7 +536,7 @@ export function applyNormalization(db, groups, { project = null } = {}) {
     .prepare(
       `
     SELECT id, title, narrative, concepts, search_aliases, lesson_learned FROM observations
-    WHERE COALESCE(compressed_into, 0) = 0
+    WHERE ${liveObsFilterSql('')}
       AND concepts IS NOT NULL AND concepts != ''
       AND (? IS NULL OR project = ?)
   `,

package/install.mjs

@@ -68,7 +68,7 @@ import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
 import {
   probeBetterSqlite3Binding,
   ensureBetterSqlite3Working,
-  NATIVE_BINDING_REBUILD_CMD,
+  nativeBindingRepairHint,
 } from './lib/binding-probe.mjs';
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
@@ -404,6 +404,57 @@ export function patchClaudeMdVersion(text, version) {
 // at the same red line. Claude Code also seeds a NEW cache version from that same
 // emptied clone. So check the source before prescribing it, and fall back to a
 // reinstall — which re-clones the manifest from the repo — when it is empty too.
+/**
+ * Clear whatever occupies `p` — file, directory, or symlink INCLUDING a dangling one —
+ * before a symlink is written over it. Returns true when something was removed.
+ *
+ * A20260906-R8-P2-3: every call site used to gate on `existsSync(p)`, which FOLLOWS the
+ * link, so a dangling symlink reads as absent. Two consequences, and the second is the
+ * one that bites: `uninstall` leaves a dead `claude-mem-lite` on PATH, and
+ * `createCliSymlink` skips the removal, `symlinkSync` throws EEXIST, the catch falls back
+ * to an unwritable /usr/local/bin, and the user is told "CLI symlink failed — run
+ * manually". Re-running `install` — the documented repair — cannot repair it. The same
+ * file already knew the idiom: isDevInstall() pairs existsSync with lstatSync.
+ *
+ * rmSync rather than unlinkSync because the dev-mode sites link DIRECTORIES; verified it
+ * removes the link and leaves the target intact (a link to a populated dir, target still
+ * readable afterwards) — following it would delete the developer's own scripts/.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function clearLinkPath(p) {
+  try {
+    lstatSync(p);
+  } catch {
+    return false; // genuinely absent — nothing to clear
+  }
+  try {
+    rmSync(p, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false; // permissions; callers fall back or report their own failure
+  }
+}
+
+/**
+ * Minimum supported Node MAJOR, parsed out of a `package.json#engines.node` range.
+ *
+ * A20260906-R8-P2-1: doctor carried its own `>= 18` literal, so v4.0.0 raised the real
+ * floor to 22 (npm refuses to install below it, and better-sqlite3 13 ships no prebuild
+ * for those Nodes) while doctor kept printing `✓ Node.js: v20.x` — greenlighting the
+ * runtime that WAS the fault, in the one tool a broken user is told to run. One source,
+ * so the two cannot drift again; the fallback only covers an unreadable manifest.
+ *
+ * @param {unknown} enginesNode e.g. '>=22' or '^22.12.0 || ^24.0.0 || >=26.0.0'
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+export function requiredNodeMajor(enginesNode, fallback = 22) {
+  const m = /(\d+)/.exec(String(enginesNode ?? ''));
+  return m ? Number(m[1]) : fallback;
+}
+
 export function hookManifestRepairHint(cacheRoot, marketplaceRoot) {
   const src = join(marketplaceRoot, 'hooks', 'hooks.json');
   const dst = join(cacheRoot, 'hooks', 'hooks.json');
@@ -513,34 +564,22 @@ function installSourceFiles(IS_DEV) {
         // Ensure parent dir exists for subdir entries (e.g. 'lib/activity.mjs')
         const linkParent = dirname(link);
         if (!existsSync(linkParent)) mkdirSync(linkParent, { recursive: true });
-        // Remove existing file/symlink before creating
-        if (existsSync(link))
-          try {
-            unlinkSync(link);
-          } catch {}
+        // Remove existing file/symlink (including a dangling one) before creating.
+        clearLinkPath(link);
         symlinkSync(target, link);
       }
     }
     // Symlink scripts/ directory
     const scriptsLink = join(DATA_DIR, 'scripts');
-    if (existsSync(scriptsLink))
-      try {
-        rmSync(scriptsLink, { recursive: true, force: true });
-      } catch {}
+    clearLinkPath(scriptsLink);
     symlinkSync(join(PROJECT_DIR, 'scripts'), scriptsLink);
     // Symlink node_modules/
     const nmLink = join(DATA_DIR, 'node_modules');
-    if (existsSync(nmLink))
-      try {
-        rmSync(nmLink, { recursive: true, force: true });
-      } catch {}
+    clearLinkPath(nmLink);
     symlinkSync(join(PROJECT_DIR, 'node_modules'), nmLink);
     // Symlink registry/ directory
     const regLink = join(DATA_DIR, 'registry');
-    if (existsSync(regLink))
-      try {
-        rmSync(regLink, { recursive: true, force: true });
-      } catch {}
+    clearLinkPath(regLink);
     if (existsSync(join(PROJECT_DIR, 'registry'))) {
       symlinkSync(join(PROJECT_DIR, 'registry'), regLink);
     }
@@ -620,9 +659,7 @@ async function installDependencies(IS_DEV) {
       ok(`better-sqlite3: ${verify.action}`);
     } else {
       fail(`better-sqlite3 binding unusable after rebuild: ${verify.error}`);
-      log(
-        'Try manually: cd ' + INSTALL_DIR + ' && npm rebuild better-sqlite3 --dangerously-allow-all-scripts',
-      );
+      log(`Try manually: ${nativeBindingRepairHint(INSTALL_DIR)}`);
       process.exit(1);
     }
 
@@ -643,7 +680,7 @@ async function installDependencies(IS_DEV) {
           `better-sqlite3 unusable in the package this installer runs from (${PROJECT_DIR}): ${selfVerify.error}`,
         );
         log(
-          `  The install itself is fine; the \`claude-mem-lite\` shell command will self-heal on first use, or run: cd ${PROJECT_DIR} && ${NATIVE_BINDING_REBUILD_CMD}`,
+          `  The install itself is fine; the \`claude-mem-lite\` shell command will self-heal on first use, or run: ${nativeBindingRepairHint(PROJECT_DIR)}`,
         );
       }
     }
@@ -662,14 +699,14 @@ function createCliSymlink() {
     const cliLink = join(localBin, 'claude-mem-lite');
     try {
       if (!existsSync(localBin)) mkdirSync(localBin, { recursive: true });
-      if (existsSync(cliLink)) unlinkSync(cliLink);
+      clearLinkPath(cliLink);
       symlinkSync(cliSource, cliLink);
       ok(`CLI: ${cliLink} → ${cliSource}`);
     } catch {
       // Fallback: try /usr/local/bin (may need sudo)
       try {
         const globalLink = '/usr/local/bin/claude-mem-lite';
-        if (existsSync(globalLink)) unlinkSync(globalLink);
+        clearLinkPath(globalLink);
         symlinkSync(cliSource, globalLink);
         ok(`CLI: ${globalLink} → ${cliSource}`);
       } catch {
@@ -1545,8 +1582,7 @@ async function uninstall() {
   for (const binDir of [join(homedir(), '.local', 'bin'), '/usr/local/bin']) {
     const cliLink = join(binDir, 'claude-mem-lite');
     try {
-      if (existsSync(cliLink)) {
-        unlinkSync(cliLink);
+      if (clearLinkPath(cliLink)) {
         ok(`CLI symlink removed: ${cliLink}`);
       }
     } catch {
@@ -1901,12 +1937,22 @@ async function doctor() {
     warn(msg);
   };
 
-  // Node version
+  // Node version. The floor is read from package.json#engines rather than restated here —
+  // see requiredNodeMajor. It is PRINTED on the ok line too, so the guard test has something
+  // to compare against the manifest; a floor nobody can observe is a floor nobody notices
+  // has gone stale, which is exactly how the `>= 18` literal outlived the v4.0.0 bump.
   const nodeVer = process.version;
-  if (parseInt(nodeVer.slice(1)) >= 18) {
-    ok(`Node.js: ${nodeVer}`);
+  let enginesNode = null;
+  try {
+    enginesNode = JSON.parse(readFileSync(join(PROJECT_DIR, 'package.json'), 'utf8')).engines?.node;
+  } catch {
+    /* unreadable manifest → requiredNodeMajor's fallback */
+  }
+  const nodeFloor = requiredNodeMajor(enginesNode);
+  if (parseInt(nodeVer.slice(1)) >= nodeFloor) {
+    ok(`Node.js: ${nodeVer} (>=${nodeFloor} required)`);
   } else {
-    fail(`Node.js ${nodeVer} too old (need >=18)`);
+    fail(`Node.js ${nodeVer} too old (need >=${nodeFloor})`);
     issues++;
   }
 
@@ -3094,7 +3140,7 @@ async function rebuildBinding() {
         ok(`better-sqlite3 binding ${verify.action} for Node ${process.version} — ${label} (${root})`);
       } else {
         fail(`better-sqlite3 binding still unusable in ${label}: ${verify.error}`);
-        log(`Try manually: cd ${root} && ${NATIVE_BINDING_REBUILD_CMD}`);
+        log(`Try manually: ${nativeBindingRepairHint(root)}`);
         failed++;
       }
     }

package/lib/binding-probe.mjs

@@ -11,8 +11,10 @@ import { createRequire } from 'node:module';
 import { join } from 'node:path';
 
 // npm >= 12 blocks lifecycle scripts by default, so a plain `npm rebuild` exits 0
-// WITHOUT compiling — see the rebuild() comment below. Single home for the one
-// command that actually works, so hints, docs and heal paths cannot drift apart.
+// WITHOUT compiling — see the rebuild() comment below. Step 1 of the heal chain, and
+// correct for a dependency that declares an install script. It is NOT sufficient for the
+// better-sqlite3 the project actually ships — see the constant below, and never hand this
+// one to a human on its own (nativeBindingRepairHint is what surfaces get).
 export const NATIVE_BINDING_REBUILD_CMD = 'npm rebuild better-sqlite3 --dangerously-allow-all-scripts';
 
 // Last-resort heal, added in v4.0.0 with better-sqlite3 13. THE npm-REBUILD PATH ABOVE
@@ -29,6 +31,33 @@ export const NATIVE_BINDING_REBUILD_CMD = 'npm rebuild better-sqlite3 --dangerou
 // nothing → this command produces build/Release/better_sqlite3.node and the DB opens.
 export const NATIVE_BINDING_SOURCE_BUILD_CMD = 'npm run --prefix node_modules/better-sqlite3 build-release';
 
+/**
+ * The one-liner a HUMAN should be given to repair the binding under `root`.
+ *
+ * A20260906-R8-P1-1: every user-facing "Repair:" line printed NATIVE_BINDING_REBUILD_CMD
+ * alone — including doctor's, via install-shape. On better-sqlite3 13 that command prints
+ * "rebuilt dependencies successfully", exits 0, and compiles nothing (re-measured
+ * 2026-09-06, npm 12.0.2, both prebuild states), so the copy-paste repair REPORTS SUCCESS
+ * on a still-dead binding. That is worse than printing nothing. The command that heals was
+ * added in v4.0.0 but lived only inside the automated chain and was shown to nobody.
+ *
+ * This is the same defect the CHANGELOG records once already: the hints used to say
+ * `--build-from-source`, which no-oped the same way, and were changed to the flag above.
+ * That fix was right for better-sqlite3 12 and expired when the dependency was bumped.
+ *
+ * `&&`, never `||`: step 1 exits 0 whether or not it did anything, so an `||` chain would
+ * never reach step 2 — the no-op is the whole trap. Sequencing unconditionally costs a
+ * recompile in the case step 1 already fixed, which is the right trade for a manual repair.
+ *
+ * @param {string} root Directory whose node_modules holds better-sqlite3
+ * @returns {string}
+ */
+export function nativeBindingRepairHint(root) {
+  // Quoted: INSTALL_DIR / a plugin-cache root can contain spaces, and an unquoted `cd`
+  // hands the user a command that fails on exactly the machines least able to debug it.
+  return `cd "${root}" && ${NATIVE_BINDING_REBUILD_CMD} && ${NATIVE_BINDING_SOURCE_BUILD_CMD}`;
+}
+
 // Set on a re-exec'd child so one failed heal cannot fork-bomb the CLI.
 export const BINDING_HEAL_GUARD_ENV = 'CLAUDE_MEM_BINDING_HEALED';
 
@@ -243,9 +272,24 @@ export async function ensureBetterSqlite3Working(installDir, deps = {}) {
   // get it appended — otherwise an injected strategy would silently grow a step its owner
   // never asked for, and (as the stub tests caught) a test that stubs `rebuild` without
   // stubbing `exec` would shell out for real.
+  //
+  // `sourceBuild: false` is the EXPLICIT opt-out, and it exists because the `deps.rebuild`
+  // test above was the wrong proxy for "this caller has a budget" (A20260906-R8b-P0-1, found
+  // by independent review). The one caller that is genuinely time-boxed — the SessionStart
+  // hook probe — injects `exec` with a 20 s cap and does NOT inject `rebuild`, so it landed
+  // outside the guard. That matters because this step is `node-gyp clean && node-gyp rebuild`:
+  // it DELETES build/ before compiling, so a truncated attempt is not a no-op, it is
+  // destructive. Measured on a tree whose compiled binding opened a DB — 20 s cap, SIGTERM at
+  // 20.02 s, no `.node` left, `DB opens: YES` → `NO`, repeating on every SessionStart because
+  // setup.sh writes its marker only on success. Callers with a time budget must opt out and
+  // leave the compile to a foreground path (`rebuild-binding`, `healAndReexec`) that has none.
   const sourceBuild =
-    deps.sourceBuild ||
-    (deps.rebuild ? null : () => exec(NATIVE_BINDING_SOURCE_BUILD_CMD, { cwd: installDir, stdio: 'pipe' }));
+    deps.sourceBuild === false
+      ? null
+      : deps.sourceBuild ||
+        (deps.rebuild
+          ? null
+          : () => exec(NATIVE_BINDING_SOURCE_BUILD_CMD, { cwd: installDir, stdio: 'pipe' }));
   if (!sourceBuild) return { ok: false, error: second.error || first.error };
 
   try {

package/lib/install-shape.mjs

@@ -36,7 +36,7 @@ import { homedir } from 'node:os';
 
 import {
   probeBindingInFreshProcess,
-  NATIVE_BINDING_REBUILD_CMD,
+  nativeBindingRepairHint,
   flattenBindingError,
 } from './binding-probe.mjs';
 
@@ -245,7 +245,7 @@ export function probeRuntimeRoots(roots, deps = {}) {
     // showed a bare path for the one fault family this check exists for.
     const error = flattenBindingError(r.error);
     return ownDeps
-      ? { label, root, ok: false, error, repair: `cd ${root} && ${NATIVE_BINDING_REBUILD_CMD}` }
+      ? { label, root, ok: false, error, repair: nativeBindingRepairHint(root) }
       : {
           label,
           root,