claude-mem-lite 3.69.0 → 3.70.0

package/.claude-plugin/marketplace.json

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

@@ -48,6 +48,7 @@ import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObse
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { recordHookError } from './lib/hook-telemetry.mjs';
+import { queueHookContext, flushHookStdout } from './lib/hook-stdout.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
@@ -168,6 +169,11 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
           }
         }
       } catch {}
+      // The salvage path exits without falling through to the dispatcher tail, so
+      // it owns its own flush: a receipt queued before the signal arrived was
+      // delivered by the pre-v3.70 inline write and would otherwise be dropped here
+      // (pre-tag review NOTE N1).
+      try { flushHookStdout(); } catch { /* never change the exit code for a receipt */ }
       process.exit(0);
     });
   });
@@ -265,20 +271,13 @@ function flushEpisodeWithDb(db, episode, hookEventName) {
       // bugfix-shape nudge above and may co-fire.
       const citeBack = loadCiteBackForEpisode(episode, RUNTIME_DIR);
       if (citeBack) lines.push(citeBack);
-      // Trailing newline is REQUIRED: when this receipt flushes at SessionStart
-      // (leftover episode after /clear or /compact), the startup dashboard writes a
-      // second hookSpecificOutput object right after. Without the '\n' the two land
-      // back-to-back as `}{` on one line and Claude Code's line-based JSON parser
-      // drops both — losing the episode-flush / cite-back context exactly at the
-      // session boundary. Every other hookSpecificOutput write appends '\n'; this
-      // was the lone exception.
-      process.stdout.write(JSON.stringify({
-        suppressOutput: true,
-        hookSpecificOutput: {
-          hookEventName,
-          additionalContext: lines.join('\n'),
-        },
-      }) + '\n');
+      // Queued, not written: when this receipt flushes at SessionStart (leftover
+      // episode after /clear or /compact) the startup dashboard also has something
+      // to say, and two envelopes on one stdout is not a JSON document — Claude
+      // Code's parser takes the whole thing as plain text (lib/hook-stdout.mjs).
+      // The older comment here claimed a line-based parser made two objects safe
+      // as long as each got its own line; the 2.1.233 bundle has no such parser.
+      queueHookContext(hookEventName, lines.join('\n'));
     } catch { /* never block on receipt */ }
   }
 
@@ -513,16 +512,14 @@ function triggerErrorRecall(db, toolInput, response) {
       // the G8 gate change (isError→isHardError) could not be volume-verified
       // from metrics. Counter only; no latency (query is bundled in the hook).
       recordMetric(join(RUNTIME_DIR, '..'), { event: 'error_recall', returned: rows.length });
-      // MED-3 (full audit 2026-07-16): emit via the JSON envelope (trailing '\n'),
-      // NOT raw stdout. A raw multi-line write corrupts a co-emitted episode-flush
-      // receipt (both write to PostToolUse stdout in the same call → `<text>{json}`)
-      // and is silently dropped on CC variants that ignore plain-text PostToolUse
-      // stdout. This is the same suppressOutput+additionalContext channel
-      // flushEpisode uses; two separate JSON lines each parse independently.
-      process.stdout.write(JSON.stringify({
-        suppressOutput: true,
-        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: out },
-      }) + '\n');
+      // MED-3 (full audit 2026-07-16): go through the envelope, NOT raw stdout —
+      // a raw multi-line write corrupts a co-emitted episode-flush receipt.
+      // The follow-up correction (2026-08-17): "two separate JSON lines each parse
+      // independently" was false. A hard-error Bash call reaches BOTH this and
+      // flushEpisode in one handlePostToolUse, and two documents make the parser
+      // fall back to plain text — which the renderer drops entirely for
+      // PostToolUse. Both receipts vanished. Queue; one envelope is written at exit.
+      queueHookContext('PostToolUse', out);
     }
   } catch (e) { debugCatch(e, 'triggerErrorRecall'); }
 }
@@ -1343,10 +1340,16 @@ function buildFallbackFastSummary(db, { project, now, prevSessionId }) {
   }
 }
 
-async function emitStartupDashboard(db, project) {
-  // T10c: Startup dashboard — aggregate git/tasks/plans/handoff/events into a
-  // structured JSON hookSpecificOutput block. Emitted BEFORE the plain-text
-  // <claude-mem-context> so both surfaces coexist. Empty string → skip.
+async function buildStartupDashboardText(db, project) {
+  // T10c: Startup dashboard — aggregate git/tasks/plans/handoff/events into text.
+  //
+  // Returns the text rather than writing it: SessionStart has three would-be
+  // stdout contributors (this, the <claude-mem-context> block, the update
+  // banner) and handleSessionStart merges them into ONE envelope. Writing here
+  // put a JSON document and raw prose on the same stdout, which stopped the
+  // host from parsing the envelope at all — the whole `{"suppressOutput":true,
+  // …}` object was delivered to the model as literal escaped text. See
+  // tests/session-start-stdout-envelope.test.mjs.
   try {
     const { buildDashboard } = await import('./lib/startup-dashboard.mjs');
     let dashboardText = buildDashboard({ db, project, projectPath: process.cwd() });
@@ -1381,16 +1384,8 @@ async function emitStartupDashboard(db, project) {
         dashboardText = dashboardText ? `${nudge}\n${dashboardText}` : nudge;
       }
     } catch (e) { debugCatch(e, 'session-start-deps-flag'); }
-    if (dashboardText) {
-      process.stdout.write(JSON.stringify({
-        suppressOutput: true,
-        hookSpecificOutput: {
-          hookEventName: 'SessionStart',
-          additionalContext: dashboardText,
-        },
-      }) + '\n');
-    }
-  } catch (e) { debugCatch(e, 'session-start-dashboard'); }
+    return dashboardText || '';
+  } catch (e) { debugCatch(e, 'session-start-dashboard'); return ''; }
 }
 
 async function handleSessionStart() {
@@ -1517,7 +1512,7 @@ async function handleSessionStart() {
 
     buildFallbackFastSummary(db, { project, now, prevSessionId });
 
-    await emitStartupDashboard(db, project);
+    const dashboardText = await buildStartupDashboardText(db, project);
 
     // Build the full context body via shared helper (also used by `mem-cli context`).
     // Queries session_summaries, key observations, clear handoff, and the
@@ -1527,16 +1522,43 @@ async function handleSessionStart() {
     const contextCollector = {};
     const fullContext = buildSessionContextLines(db, project, now, ccSessionId, contextCollector);
 
-    // Stdout is the sole context-delivery channel. The SessionStart hook output
-    // is injected as a <system-reminder> at session start, giving Claude the
-    // full summary + handoff state + observations table fresh from the DB.
+    // Stdout is the sole context-delivery channel, and it carries exactly ONE
+    // JSON envelope. Everything SessionStart wants to say is collected here and
+    // written once below: a JSON document followed by raw prose is not a JSON
+    // document, and the host then declines to parse the envelope — delivering
+    // `{"suppressOutput":true,…}` to the model as literal escaped text instead
+    // of honouring it.
+    //
     // Skip the wrapper entirely when there is no body. On a brand-new install every
     // section is empty, and the hook still emitted `<claude-mem-context>\n\n</...>` —
     // a framing block that asserts a memory surface and then shows nothing, which is
     // both wasted context and an active misread ("memory exists and is empty" is a
-    // reason NOT to call mem_*). Non-empty output is byte-identical.
+    // reason NOT to call mem_*).
+    const stdoutParts = [];
+    if (dashboardText) stdoutParts.push(dashboardText);
     if (fullContext.trim()) {
-      process.stdout.write(`<claude-mem-context>\n${fullContext}\n</claude-mem-context>\n`);
+      stdoutParts.push(`<claude-mem-context>\n${fullContext}\n</claude-mem-context>`);
+    }
+
+    // Auto-update banner (audit P3d): NON-BLOCKING — read from cached state
+    // (zero network) and, if the 24h check is due, refresh in a detached
+    // background worker so SessionStart never blocks on a GitHub fetch (was an
+    // inline `await checkForUpdate()` that could stall the session 3-6s).
+    // Collected here rather than written at the end of the handler so it joins
+    // the single envelope; the spawn stays a side effect and is fired below.
+    let updateCheckDue = false;
+    try {
+      const banner = getCachedUpdateBanner();
+      if (banner) stdoutParts.push(String(banner).trim());
+      updateCheckDue = isUpdateCheckDue();
+    } catch (e) { debugCatch(e, 'session-start-update'); }
+
+    // Queued into the same single envelope a leftover episode receipt may also
+    // be contributing to (flushEpisode runs earlier in this very process after
+    // /clear or /compact). Written once, at the dispatcher's exit.
+    if (stdoutParts.length) queueHookContext('SessionStart', stdoutParts.join('\n\n'));
+    if (updateCheckDue) {
+      try { spawnBackground('update-check'); } catch (e) { debugCatch(e, 'session-start-update-spawn'); }
     }
 
     // D#123 (review C-1): persist the Key Context ids ACTUALLY rendered above so
@@ -1580,16 +1602,6 @@ async function handleSessionStart() {
     // Pre-load TF-IDF vocabulary cache for this session (from DB, ~1ms)
     try { getVocabulary(db); } catch (e) { debugCatch(e, 'session-start-vocab'); }
 
-    // Auto-update check (audit P3d): NON-BLOCKING. Emit the banner from cached
-    // state (zero network) and, if the 24h check is due, refresh in a detached
-    // background worker so SessionStart never blocks on a GitHub fetch (was an
-    // inline `await checkForUpdate()` that could stall the session 3-6s).
-    try {
-      const banner = getCachedUpdateBanner();
-      if (banner) process.stdout.write(banner);
-      if (isUpdateCheckDue()) spawnBackground('update-check');
-    } catch (e) { debugCatch(e, 'session-start-update'); }
-
   } finally {
     db.close();
   }
@@ -1995,4 +2007,9 @@ try {
   recordHookError(`hook:${event}`, err, RUNTIME_DIR);
 }
 
+// Single stdout write for the whole process (lib/hook-stdout.mjs). Runs after the
+// catch too: a handler that queued a receipt and then threw should still deliver
+// what it had, and Claude Code only ever reads one JSON document from here.
+try { flushHookStdout(); } catch { /* a receipt must never change the exit code */ }
+
 process.exit(0);

package/install.mjs

@@ -40,7 +40,8 @@ const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 import { RESOURCE_METADATA } from './install-metadata.mjs';
 import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
-import { probeBetterSqlite3Binding, probeBindingInFreshProcess, ensureBetterSqlite3Working, NATIVE_BINDING_REBUILD_CMD } from './lib/binding-probe.mjs';
+import { probeBetterSqlite3Binding, ensureBetterSqlite3Working, NATIVE_BINDING_REBUILD_CMD } from './lib/binding-probe.mjs';
+import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { acquireLock } from './lib/proc-lock.mjs';
@@ -501,6 +502,23 @@ if (IS_DEV) {
     log('Try manually: cd ' + INSTALL_DIR + ' && npm rebuild better-sqlite3 --dangerously-allow-all-scripts');
     process.exit(1);
   }
+
+  // The package this installer is RUNNING from owns a second tree, and after
+  // `npm i -g claude-mem-lite` npm >= 12 has left its better-sqlite3 install
+  // scripts blocked — so the binding is present-but-uncompiled and nothing
+  // above touches it. The shell CLI heals it on first DB use, but only after
+  // the user has already seen `doctor` report `2 issue(s) found` on a
+  // correct install. Close the window here instead. Never fatal: this tree is
+  // not what hooks or the MCP server load.
+  if (PROJECT_DIR !== INSTALL_DIR && existsSync(join(PROJECT_DIR, 'node_modules', 'better-sqlite3'))) {
+    const selfVerify = await ensureBetterSqlite3Working(PROJECT_DIR);
+    if (selfVerify.ok) {
+      if (selfVerify.action === 'rebuilt') ok(`better-sqlite3: rebuilt for the running package too (${PROJECT_DIR})`);
+    } else {
+      warn(`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}`);
+    }
+  }
 }
 }
 
@@ -1352,6 +1370,14 @@ async function status() {
   const checks = [];
   const push = (level, key, message, extra = {}) => checks.push({ level, key, message, ...extra });
 
+  // A plugin install registers its MCP server and its hooks through the plugin
+  // manifest, never through `claude mcp add` / settings.json. Without knowing
+  // that, status printed `✗ MCP server: not registered` and `✗ Hooks: not
+  // configured` at a correctly-installed plugin user — two red marks describing
+  // the intended state.
+  const shape = detectInstallShape({ home: homedir(), projectDir: PROJECT_DIR, installDir: INSTALL_DIR });
+  const pluginProvides = !!shape.activePluginVersion;
+
   // MCP
   try {
     const list = execFileSync('claude', ['mcp', 'list'], { encoding: 'utf8' });
@@ -1364,7 +1390,13 @@ async function status() {
     // circuited first). `claude mcp list` formats as `<name>: <command>`, so
     // the two colon-form checks below cover every shape.
     const registered = list.includes('mem-lite:') || list.includes('mem:');
-    push(registered ? 'ok' : 'fail', 'mcp', registered ? 'MCP server: registered' : 'MCP server: not registered', { registered });
+    if (registered) {
+      push('ok', 'mcp', 'MCP server: registered', { registered });
+    } else if (pluginProvides) {
+      push('ok', 'mcp', `MCP server: provided by the plugin manifest (v${shape.activePluginVersion.version} .mcp.json) — no user-scope registration expected`, { registered: false, via: 'plugin' });
+    } else {
+      push('fail', 'mcp', 'MCP server: not registered', { registered });
+    }
   } catch {
     push('warn', 'mcp', 'Could not check MCP status', { registered: null });
   }
@@ -1385,6 +1417,8 @@ async function status() {
     push('ok', 'hooks', 'Hooks: configured', { configured: true });
   } else if (pluginDisabled) {
     push('ok', 'hooks', 'Hooks: not configured', { configured: false });
+  } else if (pluginProvides) {
+    push('ok', 'hooks', `Hooks: provided by the plugin manifest (v${shape.activePluginVersion.version} hooks/hooks.json) — settings.json correctly holds none`, { configured: false, via: 'plugin' });
   } else {
     push('fail', 'hooks', 'Hooks: not configured', { configured: false });
   }
@@ -1487,18 +1521,36 @@ async function doctor() {
     issues++;
   }
 
+  // Which code homes does this machine actually run? A machine can hold three
+  // at once (plugin cache / ~/.claude-mem-lite / npm-global) and each owns its
+  // own native binding. Answering about only the dir install.mjs sits in got it
+  // wrong both ways in the field: `✗ server.mjs: missing` on a healthy
+  // plugin-only install, and `✓ better-sqlite3: verified` while the registered
+  // MCP server FATAL'd because a DIFFERENT tree was stale. See lib/install-shape.mjs.
+  const shape = detectInstallShape({ home: homedir(), projectDir: PROJECT_DIR, installDir: INSTALL_DIR });
+
   // Dependencies. Out of process: an in-process open of a STALE .node caches a
   // dead module handle for the rest of doctor and can SIGSEGV on teardown —
   // truncating the report of the very run the user started because things are
   // broken. This is also what makes the native-binding check further down
-  // (which reads the same tree) honest rather than answering from a poisoned
+  // (which reuses these results) honest rather than answering from a poisoned
   // process.
-  const depProbe = probeBindingInFreshProcess(bindingHostDir());
-  if (depProbe.ok) {
-    ok('better-sqlite3: verified (import + open OK)');
-  } else {
-    fail(`better-sqlite3: import/init failed (${String(depProbe.error).split('\n')[0]})`);
+  const rootProbes = probeRuntimeRoots(shape.runtimeRoots);
+  const brokenRoots = rootProbes.filter((r) => !r.ok);
+  if (rootProbes.length === 0) {
+    fail('better-sqlite3: no install on this machine owns a native binding — nothing here can open the DB');
     issues++;
+  } else if (brokenRoots.length === 0) {
+    ok(`better-sqlite3: verified in ${rootProbes.length} install${rootProbes.length === 1 ? '' : 's'} (${rootProbes.map((r) => r.label).join('; ')})`);
+  } else {
+    // Name the ROOT, not just the fault: the repair is per-tree, and pointing a
+    // user at the wrong `cd` is how `rebuild-binding` used to report success
+    // while the broken install stayed broken.
+    for (const b of brokenRoots) {
+      fail(`better-sqlite3 unusable in ${b.label}: ${b.error}`);
+      log(`    repair: ${b.repair}`);
+      issues++;
+    }
   }
 
   try {
@@ -1509,20 +1561,27 @@ async function doctor() {
     issues++;
   }
 
-  // Server file
-  if (existsSync(SERVER_PATH)) {
+  // Entry points. These live in ~/.claude-mem-lite ONLY in the install.mjs-managed
+  // layout; `/plugin install` provisions the data dir but serves code from the
+  // plugin cache, so demanding them there reported two ✗ and exit 1 on a healthy
+  // install of the README's recommended method. Grade against the shape that is
+  // actually in use.
+  if (shape.managed) {
     ok(`server.mjs: ${SERVER_PATH}`);
-  } else {
-    fail('server.mjs: missing');
-    issues++;
-  }
-
-  // Hook file
-  if (existsSync(HOOK_PATH)) {
     ok(`hook.mjs: ${HOOK_PATH}`);
+  } else if (shape.activePluginVersion) {
+    const v = shape.activePluginVersion;
+    ok(`Entry points: served from plugin cache v${v.version} (plugin-only install — the ~/.claude-mem-lite code layout is not used)`);
+    for (const entry of ['server.mjs', 'hook.mjs', 'cli.mjs']) {
+      if (!existsSync(join(v.root, entry))) {
+        fail(`Plugin cache v${v.version}: ${entry} missing — reinstall with \`/plugin install claude-mem-lite@sdsrss\``);
+        issues++;
+      }
+    }
   } else {
+    fail('server.mjs: missing');
     fail('hook.mjs: missing');
-    issues++;
+    issues += 2;
   }
 
   // Hook self-heal runtime: the launcher (scripts/hook-launcher.mjs) degrades a
@@ -1548,11 +1607,10 @@ async function doctor() {
   // right now". A Node upgrade breaks every DB-touching path at once, so this is
   // the single highest-value line in doctor when it fires.
   const breakage = readNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
-  // Reuses the dependency probe above — same tree, same question, and doctor
-  // should not pay for two child spawns to ask it twice.
-  const bindingProbe = depProbe;
-  if (!bindingProbe.ok) {
-    fail(`Native DB binding: unusable (${String(bindingProbe.error).split('\n')[0]}) — run \`node ${join(PROJECT_DIR, 'cli.mjs')} rebuild-binding\``);
+  // Reuses the per-root probes above — same trees, same question, and doctor
+  // should not pay for another round of child spawns to ask it twice.
+  if (brokenRoots.length > 0) {
+    fail(`Native DB binding: unusable in ${brokenRoots.map((b) => b.label).join(', ')} — run \`node ${join(PROJECT_DIR, 'cli.mjs')} rebuild-binding\` (repairs every broken install, not just this one)`);
     issues++;
   } else if (breakage) {
     const ageH = Math.round((Date.now() - (breakage.ts || 0)) / 3600000);
@@ -1593,6 +1651,11 @@ async function doctor() {
     ok('Plugin lifecycle: disabled cleanly (no active mem hooks)');
   } else if (hasHooks) {
     ok('Plugin lifecycle: hooks active');
+  } else if (shape.activePluginVersion) {
+    // Plugin-only: hooks come from the cache's hooks/hooks.json, and an EMPTY
+    // settings.json hooks block is the correct state — warning about it told a
+    // correctly-installed user their hooks were missing.
+    ok(`Plugin lifecycle: hooks served by the plugin manifest (v${shape.activePluginVersion.version}); settings.json correctly holds none`);
   } else {
     dwarn('Plugin lifecycle: hooks not configured');
   }
@@ -1668,15 +1731,11 @@ async function doctor() {
   // when their version segment ≠ current package.json version; dev-install
   // paths (no version segment) are never flagged.
   try {
-    const procs = execFileSync('pgrep', ['-af', 'chroma|claude-mem-lite.*(scripts/launch|server)\\.mjs|claude-mem.*worker'], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' }).trim();
+    const procs = execFileSync('pgrep', ['-af', 'chroma|claude-mem-lite.*(scripts/launch|server)\\.mjs|\\.claude-mem/.*worker'], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' }).trim();
     const lines = procs.split('\n').filter(l => l && !l.includes('pgrep'));
     let currentVersion = '';
     try { currentVersion = JSON.parse(readFileSync(join(PROJECT_DIR, 'package.json'), 'utf8')).version; } catch { /* fall through with empty version */ }
-    const stale = lines.filter(l => {
-      if (/chroma|claude-mem.*worker/.test(l)) return true;
-      const m = l.match(/claude-mem-lite\/(\d+\.\d+\.\d+)\/(scripts\/launch|server)\.mjs/);
-      return m && currentVersion && m[1] !== currentVersion;
-    });
+    const stale = lines.filter(l => isStaleMemProcess(l, currentVersion));
     if (stale.length > 0) {
       warn(`Old processes running${currentVersion ? ` (current: v${currentVersion})` : ''}:\n    ` + stale.join('\n    '));
       issues++;
@@ -1718,15 +1777,23 @@ async function doctor() {
   // class. Per #8043: "is this file present ≠ is this install consistent" —
   // missing is tracked separately by checkDevDrift but the caller MUST surface
   // it to honour #8268's "gate the all-green string on every counter" rule.
+  // Gated on the managed layout existing at all. SOURCE_FILES describes what
+  // `install` deploys into ~/.claude-mem-lite; on a plugin-only install nothing
+  // was ever deployed there, so every entry reads as "missing" and this reported
+  // `⚠ Managed files: 121 missing` + an issue on a correct install — prescribing
+  // a repair against a path that does not exist.
   try {
+    const skipDrift = !shape.managed && !!shape.activePluginVersion;
     const { checkDevDrift } = await import('./lib/doctor-drift.mjs');
-    const r = checkDevDrift(INSTALL_DIR, SOURCE_FILES);
+    const r = skipDrift ? null : checkDevDrift(INSTALL_DIR, SOURCE_FILES);
     const devRemedy = `re-run: node ${join(PROJECT_DIR, 'install.mjs')} install --dev`;
     const nameList = (files, count) => {
       const suffix = count > files.length ? ` +${count - files.length} more` : '';
       return `${files.join(', ')}${suffix}`;
     };
-    if (r.devMode) {
+    if (skipDrift) {
+      ok('Managed files: n/a (plugin-only install — code is served from the plugin cache, so ~/.claude-mem-lite holds data only)');
+    } else if (r.devMode) {
       const parts = [];
       if (r.plainCount > 0) {
         parts.push(`${r.plainCount} non-symlink: ${nameList(r.plainFiles.slice(0, 5), r.plainCount)}`);
@@ -1772,8 +1839,11 @@ async function doctor() {
       if (r.missingModuleCount > 0) {
         parts.push(`${r.missingModuleCount} module: ${nameList(r.missingModuleFiles, r.missingModuleCount)}`);
       }
+      // `claude-mem-lite update` is the observation editor (`update <id>`); the
+      // self-updater is `self-update`. Naming the wrong one sent the user to a
+      // usage error at the exact moment their install was incomplete.
       warn(`Managed files: ${r.missingCount} missing (${parts.join('; ')}) — a copy install resolves `
-        + `imports against the install dir, so these throw at hook time. Fix: claude-mem-lite update `
+        + `imports against the install dir, so these throw at hook time. Fix: claude-mem-lite self-update `
         + `(or: node ${join(INSTALL_DIR, 'install.mjs')} repair)`);
       issues++;
     }
@@ -2308,6 +2378,55 @@ function regenerateLockfile() {
 // resolves matters, i.e. the one next to this file. Rebuilding the wrong tree
 // reports success while every hook keeps failing. Fall back to INSTALL_DIR when
 // this file sits in a source-only layout with no deps of its own.
+/**
+ * Is this `pgrep -af` line a stale claude-mem process worth flagging?
+ *
+ * Extracted and tightened after CI reported `1 issue(s) found` on a healthy
+ * plugin-only install (v3.70.0 Release run 32068227636). The legacy clause was
+ * `/claude-mem.*worker/`, which matches ANY command line where `claude-mem`
+ * precedes `worker` — including vitest's own
+ * `…/claude-mem-lite/node_modules/vitest/dist/workers/forks.js` whenever the repo
+ * is checked out into a directory called `claude-mem-lite`, as GitHub Actions does.
+ * doctor then counted an issue and exited 1 while every other check was green: the
+ * exact class of false-red this release exists to remove, invisible locally only
+ * because the dev checkout is not named after the package.
+ *
+ * The legacy worker lived under the pre-v2.20 DATA dir `~/.claude-mem/`, so anchor
+ * on that dot-prefixed path segment. It cannot appear in a repo checkout path.
+ *
+ * @param {string} line One `pgrep -af` output line.
+ * @param {string} currentVersion Running package version, '' when unreadable.
+ * @returns {boolean}
+ */
+export function isStaleMemProcess(line, currentVersion) {
+  if (!line) return false;
+  const cmd = (line.match(/^\s*\d+\s+(.*)$/)?.[1] ?? line).trim();
+  if (!cmd) return false;
+  const tokens = cmd.split(/\s+/);
+  const exe = tokens[0] || '';
+
+  // A shell or wrapper that merely MENTIONS these names in its arguments is not one
+  // of our processes. Searching the whole line as free text bit twice within one
+  // release: first vitest workers under a checkout named `claude-mem-lite`, then the
+  // `git commit -F -` publishing THIS fix, whose message text contains the word
+  // "chroma". Anything that takes a program as an argument can quote us.
+  if (/(^|\/)(ba|z|k|da|c|t)?sh$/.test(exe) || /(^|\/)(env|xargs|timeout|nohup|sudo|git|grep|rg|less|vi|vim|nano|code)$/.test(exe)) {
+    return false;
+  }
+
+  // Legacy chroma server: the EXECUTABLE, not a substring of some argument.
+  if (/(^|\/)chroma$/.test(exe)) return true;
+  // Legacy worker: a script path under the pre-v2.20 DATA dir. Dot-prefixed, so a
+  // repo checkout called `claude-mem-lite` cannot produce it.
+  if (tokens.some((t) => /\.claude-mem\/[^/]*worker[^/]*$/.test(t))) return true;
+
+  // A plugin-cache launcher/server whose version segment is not the running one.
+  // Anchored at end-of-token so it is a script being executed, not prose.
+  const script = tokens.find((t) => /claude-mem-lite\/\d+\.\d+\.\d+\/(scripts\/launch|server)\.mjs$/.test(t));
+  if (!script || !currentVersion) return false;
+  return script.match(/claude-mem-lite\/(\d+\.\d+\.\d+)\//)[1] !== currentVersion;
+}
+
 function bindingHostDir() {
   return existsSync(join(PROJECT_DIR, 'node_modules', 'better-sqlite3')) ? PROJECT_DIR : INSTALL_DIR;
 }
@@ -2322,7 +2441,6 @@ function bindingHostDir() {
 // two concurrent rebuilds can clobber the .node mid-compile. A live peer → report
 // and exit 0 (it is doing this very work), never race it.
 async function rebuildBinding() {
-  const host = bindingHostDir();
   const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock'));
   if (!release) {
     // NOT exit 0: skipping is not healing. Callers key their state on the exit
@@ -2333,15 +2451,33 @@ async function rebuildBinding() {
     return;
   }
   try {
-    const verify = await ensureBetterSqlite3Working(host);
-    if (verify.ok) {
-      ok(`better-sqlite3 binding ${verify.action} for Node ${process.version} (${host})`);
-      // The fault is gone → drop the marker so session-start stops retrying.
-      clearNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
-    } else {
-      fail(`better-sqlite3 binding still unusable: ${verify.error}`);
-      log(`Try manually: cd ${host} && ${NATIVE_BINDING_REBUILD_CMD}`);
+    // Every code home on this machine, not just the one this file sits in.
+    // Pre-fix this rebuilt bindingHostDir() alone and reported `✓ ... verified`
+    // — so a user whose ~/.claude-mem-lite tree was stale (hooks silently dead,
+    // MCP server FATAL'ing) ran the documented repair, watched it succeed, and
+    // still had no memory. Falling back to INSTALL_DIR keeps a source-only
+    // layout with no deps of its own repairable.
+    const shape = detectInstallShape({ home: homedir(), projectDir: PROJECT_DIR, installDir: INSTALL_DIR });
+    const targets = shape.runtimeRoots.length > 0
+      ? shape.runtimeRoots
+      : [{ label: 'install dir', root: bindingHostDir() }];
+
+    let failed = 0;
+    for (const { label, root } of targets) {
+      const verify = await ensureBetterSqlite3Working(root);
+      if (verify.ok) {
+        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}`);
+        failed++;
+      }
+    }
+    if (failed > 0) {
       process.exitCode = 1;
+    } else {
+      // Every tree is loadable → drop the marker so session-start stops retrying.
+      clearNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
     }
   } finally {
     release();

package/lib/hook-stdout.mjs

@@ -0,0 +1,83 @@
+// lib/hook-stdout.mjs — one hook process, at most ONE JSON document on stdout.
+//
+// Claude Code parses a command hook's stdout as a SINGLE JSON document. From the
+// 2.1.233 bundle, the whole parser is:
+//
+//   function Hxi(e) {
+//     let t = e.trim();
+//     if (!t.startsWith("{")) return { plainText: e };   // whole stdout = prose
+//     try { let r = XZf(t); ... }                        // JSON.parse(WHOLE stdout) + zod
+//     catch (r) { return { plainText: e } }              // ← throw ⇒ whole stdout = prose
+//   }
+//
+// There is no line splitting anywhere in it. That matters because this codebase
+// had assumed the opposite ("Claude Code's line-based JSON parser", hook.mjs
+// flushEpisode) and shipped surfaces that emit two envelopes, or an envelope
+// plus a raw block, on one stdout. Both shapes make JSON.parse throw, so:
+//
+//   • SessionStart / UserPromptSubmit / UserPromptExpansion — the plainText is
+//     injected verbatim, so the model receives `{"suppressOutput":true,…}` as
+//     literal escaped text and suppressOutput is never honoured.
+//   • every other event — the renderer returns [] for plain text, so BOTH
+//     receipts are dropped in silence.
+//
+// So contributions are queued and written once. Callers keep their own gating
+// (RECEIPT_EVENTS, significance, etc.); this only owns the writing.
+
+let parts = [];
+let queuedEvent = null;
+
+/**
+ * Queue a contribution to this process's single stdout envelope.
+ *
+ * @param {string} hookEventName Event name for hookSpecificOutput.
+ * @param {string} text additionalContext contribution; empty/blank is ignored.
+ * @returns {void}
+ */
+export function queueHookContext(hookEventName, text) {
+  if (!hookEventName) return;
+  const body = String(text ?? '').trim();
+  if (!body) return;
+  // Mixed event names cannot be merged — Claude Code throws when
+  // hookSpecificOutput.hookEventName does not match the event it dispatched.
+  // In practice one process serves one event; keep the first and drop the
+  // stragglers rather than emit an envelope the host rejects outright.
+  if (queuedEvent && queuedEvent !== hookEventName) return;
+  queuedEvent = hookEventName;
+  parts.push(body);
+}
+
+/**
+ * Write the queued contributions as one envelope. Idempotent: a second call
+ * with nothing queued writes nothing, so calling it from both the dispatcher
+ * and an exit backstop is safe.
+ *
+ * @param {{write?: (s: string) => void}} [deps]
+ * @returns {boolean} true when an envelope was written.
+ */
+export function flushHookStdout(deps = {}) {
+  if (!queuedEvent || parts.length === 0) return false;
+  const write = deps.write || ((s) => process.stdout.write(s));
+  const payload = JSON.stringify({
+    suppressOutput: true,
+    hookSpecificOutput: {
+      hookEventName: queuedEvent,
+      additionalContext: parts.join('\n\n'),
+    },
+  }) + '\n';
+  parts = [];
+  queuedEvent = null;
+  write(payload);
+  return true;
+}
+
+/** Test seam: forget anything queued but not yet written. */
+export function resetHookStdout() {
+  parts = [];
+  queuedEvent = null;
+}
+
+/** Test seam: what is queued right now. */
+export function peekHookStdout() {
+  return { hookEventName: queuedEvent, parts: [...parts] };
+}

package/lib/install-shape.mjs

@@ -0,0 +1,218 @@
+// lib/install-shape.mjs — which code homes does this machine actually RUN?
+//
+// claude-mem-lite can occupy three code homes at once and they are not
+// interchangeable:
+//
+//   plugin cache   ~/.claude/plugins/cache/<mp>/claude-mem-lite/<ver>/
+//                  runs the manifest hooks + the plugin MCP launcher
+//   managed dir    ~/.claude-mem-lite/
+//                  runs the settings.json hooks + the registered MCP server
+//   npm-global     <prefix>/lib/node_modules/claude-mem-lite/
+//                  runs the `claude-mem-lite` shell command
+//
+// Each carries its OWN node_modules, so each has its own native binding that
+// can go stale independently. install.mjs used to answer every "is the binding
+// OK / are the files there" question about exactly one of them — the directory
+// install.mjs itself sits in. That is the right question for install.mjs's own
+// imports and the wrong one for a health check, and it failed in both
+// directions in a sandbox run of the documented install flows (2026-08-17):
+//
+//   • plugin-only user, healthy system → `✗ server.mjs: missing`,
+//     `✗ hook.mjs: missing`, `⚠ Managed files: 121 missing`, exit 1. Those
+//     files only ever exist in the managed layout, which a plugin install does
+//     not create.
+//   • npm-global CLI + a stale ~/.claude-mem-lite binding → `✓ better-sqlite3:
+//     verified`, exit 0, while the registered MCP server FATAL'd on startup
+//     ("wrong ELF class") and every hook degraded to a silent exit 0. The
+//     documented repair, `rebuild-binding`, then rebuilt the healthy tree and
+//     reported success. That is the v3.60 field failure (memory dead for four
+//     days) with the whole diagnose→repair chain reporting green.
+//
+// So: enumerate the roots, probe each, and name the one that is broken.
+
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+import { probeBindingInFreshProcess, NATIVE_BINDING_REBUILD_CMD } from './binding-probe.mjs';
+
+// Module-private: nothing outside needs these, and a new unused export is a
+// review signal against the knip baseline recorded in CLAUDE.md.
+const DEFAULT_MARKETPLACE = 'sdsrss';
+const DEFAULT_PLUGIN = 'claude-mem-lite';
+
+// Both must be present before ~/.claude-mem-lite counts as a CODE home. Either
+// one alone is a torn install, and `runtime/` + the DB alone is the data-only
+// dir every install shape creates — including plugin-only, which is exactly the
+// case that must NOT be graded against the managed layout.
+const MANAGED_ENTRY_POINTS = ['server.mjs', 'hook.mjs'];
+
+function cacheBaseFor({ home = homedir(), marketplace = DEFAULT_MARKETPLACE, plugin = DEFAULT_PLUGIN } = {}) {
+  return join(home, '.claude', 'plugins', 'cache', marketplace, plugin);
+}
+
+// Leading integer per dot-segment, so a prerelease dir (`3.70.0-rc1`) orders by its
+// numeric part instead of collapsing to "equal": `Number('0-rc1')` is NaN, and a NaN
+// difference is falsy, which silently made the comparator return 0 and left ordering
+// up to readdir insertion order (pre-tag review NOTE N5). `/^\d+\./` admits such dirs,
+// so this is reachable the moment a prerelease is ever cached.
+function semverDesc(a, b) {
+  const parts = (v) => v.split('.').map((s) => {
+    const n = parseInt(s, 10);
+    return Number.isFinite(n) ? n : 0;
+  });
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pb[i] ?? 0) - (pa[i] ?? 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+/**
+ * True when `installDir` holds a managed CODE install, not merely the data dir.
+ *
+ * @param {string} installDir
+ * @returns {boolean}
+ */
+export function hasManagedCodeInstall(installDir) {
+  if (!installDir || !existsSync(installDir)) return false;
+  return MANAGED_ENTRY_POINTS.every((f) => existsSync(join(installDir, f)));
+}
+
+/**
+ * Plugin-cache version dirs that carry runnable code, newest first.
+ *
+ * Gated on scripts/launch.mjs rather than mere directory presence: a
+ * half-pruned or half-written version dir is not something the runtime can
+ * start, and listing it would invent roots to probe.
+ *
+ * @param {{home?: string, marketplace?: string, plugin?: string}} [opts]
+ * @returns {Array<{version: string, root: string}>}
+ */
+export function listPluginCacheVersions(opts = {}) {
+  const base = cacheBaseFor(opts);
+  if (!existsSync(base)) return [];
+  const out = [];
+  let entries;
+  try { entries = readdirSync(base); } catch { return []; }
+  for (const version of entries) {
+    if (!/^\d+\./.test(version)) continue;
+    const root = join(base, version);
+    if (!existsSync(join(root, 'scripts', 'launch.mjs'))) continue;
+    out.push({ version, root });
+  }
+  return out.sort((a, b) => semverDesc(a.version, b.version));
+}
+
+/**
+ * Every distinct code home on this machine, plus the subset that owns a native
+ * binding worth probing.
+ *
+ * `runtimeRoots` deduplicates on the REALPATH OF THE BINDING, not of the root:
+ * scripts/setup.sh's fast path symlinks a plugin cache's node_modules at the
+ * managed dir's, so two distinct roots routinely share one tree. Probing it
+ * twice would double every failure message for a single fault.
+ *
+ * @param {{home?: string, projectDir?: string, installDir?: string, marketplace?: string, plugin?: string, pluginRoot?: string}} opts
+ * @returns {{managed: boolean, pluginVersions: Array<{version: string, root: string}>, activePluginVersion: {version: string, root: string}|null, runtimeRoots: Array<{label: string, root: string, depsMissing?: boolean}>}}
+ */
+export function detectInstallShape({
+  home = homedir(), projectDir, installDir, marketplace, plugin,
+  pluginRoot = process.env.CLAUDE_PLUGIN_ROOT,
+} = {}) {
+  const managed = hasManagedCodeInstall(installDir);
+  const pluginVersions = listPluginCacheVersions({ home, marketplace, plugin });
+
+  // Only ONE cache version is live. Claude Code never prunes old version dirs and
+  // each keeps its own real node_modules, so probing all of them meant a Node major
+  // upgrade left every never-started version permanently stale: doctor red forever
+  // about trees nothing loads, and rebuild-binding — which clears the breakage marker
+  // only when EVERY target succeeds — could never clear it, reproducing the
+  // "launcher re-spawns npm every 6h forever" state from 2026-08-13. Prefer the
+  // version this process was actually launched from; else the newest.
+  const activePluginVersion = pluginVersions.find((v) => pluginRoot && resolvesSame(v.root, pluginRoot))
+    || pluginVersions[0]
+    || null;
+
+  const runtimeRoots = [];
+  const byBinding = new Map();
+  const add = (label, root, { certified = false } = {}) => {
+    if (!root) return;
+    const bs3 = join(root, 'node_modules', 'better-sqlite3');
+    if (!existsSync(bs3)) {
+      // A dir that merely lacks deps is not a runtime root — but one this function
+      // just CERTIFIED as a code home is. Its hooks and MCP server load from it and
+      // throw ERR_MODULE_NOT_FOUND on every fire, and that error is not in
+      // NATIVE_BINDING_PATTERNS, so nothing else records it either. Dropping it
+      // turned a pre-v3.70 exit 1 into exit 0 (pre-tag review, SHOULD-FIX 1).
+      if (certified && existsSync(root)) runtimeRoots.push({ label, root, depsMissing: true });
+      return;
+    }
+    let key = bs3;
+    try { key = realpathSync(bs3); } catch { /* unresolvable → dedupe on the literal path */ }
+    const existing = byBinding.get(key);
+    if (existing) {
+      // Same tree reached through a second home. One probe still answers for
+      // both, but the label has to say so — otherwise a plugin user reading
+      // "managed install is broken" has no way to know their plugin shares it.
+      existing.label += `, ${label}`;
+      return;
+    }
+    const entry = { label, root };
+    byBinding.set(key, entry);
+    runtimeRoots.push(entry);
+  };
+
+  // Order is significance order for the report: the tree the user's own command
+  // runs from, then the one hooks/MCP run from, then the live plugin version.
+  add('running CLI', projectDir);
+  if (managed) add('managed install (~/.claude-mem-lite)', installDir, { certified: true });
+  if (activePluginVersion) {
+    add(`plugin cache v${activePluginVersion.version}`, activePluginVersion.root, { certified: true });
+  }
+
+  return { managed, pluginVersions, activePluginVersion, runtimeRoots };
+}
+
+/** True when two paths denote the same directory, tolerating symlinks. */
+function resolvesSame(a, b) {
+  if (a === b) return true;
+  try { return realpathSync(a) === realpathSync(b); } catch { return false; }
+}
+
+/**
+ * Probe each root's native binding out of process, carrying a per-root repair
+ * command so a failure cannot send the user to rebuild a healthy tree.
+ *
+ * @param {Array<{label: string, root: string}>} roots
+ * @param {{probe?: (root: string) => {ok: boolean, error?: string}}} [deps]
+ * @returns {Array<{label: string, root: string, ok: boolean, error?: string, repair?: string}>}
+ */
+export function probeRuntimeRoots(roots, deps = {}) {
+  const probe = deps.probe || ((root) => probeBindingInFreshProcess(root));
+  return roots.map(({ label, root, depsMissing }) => {
+    // Nothing to dlopen: the tree is absent, not stale. Say so and prescribe an
+    // install — `npm rebuild` on a missing package exits 0 and heals nothing.
+    if (depsMissing) {
+      return {
+        label,
+        root,
+        ok: false,
+        error: 'node_modules/better-sqlite3 is absent — every hook and the MCP server '
+          + 'that load this install throw ERR_MODULE_NOT_FOUND',
+        repair: `cd ${root} && npm install --omit=dev`,
+      };
+    }
+    const r = probe(root);
+    if (r.ok) return { label, root, ok: true };
+    return {
+      label,
+      root,
+      ok: false,
+      error: String(r.error || 'unknown').split('\n')[0],
+      repair: `cd ${root} && ${NATIVE_BINDING_REBUILD_CMD}`,
+    };
+  });
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.69.0",
+  "version": "3.70.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.69.0",
+      "version": "3.70.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.69.0",
+  "version": "3.70.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",
@@ -78,6 +78,8 @@
     "lib/task-imperative.mjs",
     "lib/lesson-bridge.mjs",
     "lib/binding-probe.mjs",
+    "lib/install-shape.mjs",
+    "lib/hook-stdout.mjs",
     "lib/proc-lock.mjs",
     "lib/atomic-write.mjs",
     "lib/release-digest.mjs",

package/source-files.mjs

@@ -93,6 +93,15 @@ export const SOURCE_FILES = [
   // self-heal after Node ABI changes). Missing from manifest → auto-update
   // ships a stale install that FATALs on first DB open after Node upgrade.
   'lib/binding-probe.mjs',
+  // Which code homes this machine runs (plugin cache / ~/.claude-mem-lite /
+  // npm-global) — imported by install.mjs for doctor, status and rebuild-binding.
+  // 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',
+  // 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.
+  'lib/hook-stdout.mjs',
   // audit P0/P1: inter-process install lock + atomic config writes — imported by
   // install.mjs (settings.json + install lock) and hook-update.mjs (.claude.json
   // + auto-update lock). Must ship or a partial install/update skips them.