claude-mem-lite 3.95.0 → 3.95.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.95.0",
+      "version": "3.95.1",
       "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.95.0",
+  "version": "3.95.1",
   "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

@@ -370,8 +370,12 @@ Slash commands `/adopt` and `/unadopt` wrap the same CLI.
   runtime-gated on sentinel presence, so projects without adoption get the
   full verbose output.
 
-See `docs/plans/2026-04-16-invited-memory-pattern.md` for the full design
-(including the reusable template other plugins can follow).
+See [the invited-memory design][invited-memory] for the full design (including the
+reusable template other plugins can follow). It is a development-time document and
+is no longer in the repository at HEAD, so that link is pinned to `v3.95.0`, the
+last release that carried it.
+
+[invited-memory]: https://github.com/sdsrss/claude-mem-lite/blob/v3.95.0/docs/plans/2026-04-16-invited-memory-pattern.md
 
 ## Database Schema
 

package/hook-update.mjs

@@ -1053,7 +1053,28 @@ function copyReleaseIntoStaging(sourceDir, stagingDir, manifest = { SOURCE_FILES
 // ── Cache hook residue clearing ────────────────────────────
 // Inline (does not import plugin-cache-guard.mjs) so hook-update.mjs keeps working
 // even if plugin-cache-guard.mjs is missing on disk in degraded installs.
+
+// Mirror of plugin-cache-guard.hasInstallManagedHooks, inlined for the reason above.
+// Kept string-identical in its match rule (`.claude-mem-lite/` or `/claude-mem-lite/`
+// appearing in a serialized hooks block) so the two cannot disagree about whether
+// settings.json owns the hooks.
+function hasInstallManagedSettingsHooks() {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return false;
+  try {
+    const s = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const serialized = JSON.stringify(s.hooks || {});
+    return serialized.includes('.claude-mem-lite/') || serialized.includes('/claude-mem-lite/');
+  } catch { return false; }
+}
 export function clearCacheHookResidue() {
+  // Same precondition plugin-cache-guard.mjs documents and hook.mjs's self-heal
+  // honours: this is a DEDUP against install.mjs-managed settings.json entries.
+  // With no such entries the cache manifest is the ONLY hook registration, and
+  // "clearing residue" unregisters all seven events — invisibly, because
+  // status/doctor then see the shape of a healthy plugin-only install. Inlined
+  // here for the same reason the rest of this function is (see header).
+  if (!hasInstallManagedSettingsHooks()) return 0;
   const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', 'sdsrss', 'claude-mem-lite');
   if (!existsSync(cacheBase)) return 0;
   let cleared = 0;

package/install.mjs

@@ -44,7 +44,7 @@ import { MARKETPLACE_KEY, PLUGIN_KEY, isPluginExplicitlyDisabled } from './lib/p
 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 { scanPluginCacheHookPollution, hasInstallManagedHooks, pluginCacheHookEvents } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
 import { probeBetterSqlite3Binding, ensureBetterSqlite3Working, NATIVE_BINDING_REBUILD_CMD } from './lib/binding-probe.mjs';
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
@@ -319,6 +319,40 @@ export function bumpJsonField(filePath, keyPath, newVal) {
   return { changed: true, prev };
 }
 
+// CLAUDE.md's `- **Version**: x.y.z` line, patched to a new version.
+//
+// Replaces the version TOKEN, not the whole line. The line carries a trailing
+// annotation ("— **this exact string is a release guard.**") and the previous
+// whole-line form deleted it on the first release after that annotation was
+// written. Every gate stayed green through the deletion — publish.yml greps the
+// `^- **Version**: <semver>` prefix and install-e2e asserts the same substring,
+// so neither can see a truncated tail. Pure + exported for the same reason
+// bumpJsonField is: syncVersions gets one testable point of truth per file shape.
+//
+// @returns patched text, or null when the line is absent (caller warns + skips).
+export function patchClaudeMdVersion(text, version) {
+  const versionLine = /^(- \*\*Version\*\*: )\d+\.\d+\.\d+(.*)$/m;
+  if (!versionLine.test(text)) return null;
+  return text.replace(versionLine, (_m, head, tail) => `${head}${version}${tail}`);
+}
+
+// Repair instruction for an unregistered hook manifest.
+//
+// The obvious advice — copy the marketplace clone over the cache copy — is a SILENT
+// NO-OP in one real sequence (pre-ship review, finding 3): `install` empties the
+// marketplace manifest too, so after `install` + `cleanup-hooks` BOTH files are
+// `{"hooks":{}}` and the cp exits 0 having changed nothing, leaving the user staring
+// 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.
+export function hookManifestRepairHint(cacheRoot, marketplaceRoot) {
+  const src = join(marketplaceRoot, 'hooks', 'hooks.json');
+  const dst = join(cacheRoot, 'hooks', 'hooks.json');
+  return pluginCacheHookEvents(marketplaceRoot).ok
+    ? `cp "${src}" "${dst}" && restart Claude Code`
+    : `no usable marketplace copy to restore from — reinstall the plugin (/plugin uninstall then /plugin install), then restart Claude Code`;
+}
+
 // Doctor's final summary line. Pure function so the 4-way contract
 // (clean / warnings-only / issues / mixed) is unit-testable without spinning
 // up the full doctor pipeline. `issues` are ✗-level (action required);
@@ -597,7 +631,7 @@ if (pluginHandlesMcp) {
 }
 }
 
-function dedupePluginCacheAndHooks() {
+function dedupePluginCacheAndHooks({ managedHooks } = {}) {
 // 3b. Deduplicate: if marketplace plugin also registers MCP + hooks,
 // clear them to prevent double execution. install.mjs hooks (in settings.json)
 // point to ~/.claude-mem-lite/ (latest code in dev mode via symlinks),
@@ -609,6 +643,32 @@ function dedupePluginCacheAndHooks() {
 const pluginDir = join(homedir(), '.claude', 'plugins', 'marketplaces', MARKETPLACE_KEY);
 const pluginHooksPath = join(pluginDir, 'hooks', 'hooks.json');
 
+// Clearing is a DEDUP, and a dedup with only one registration left is a delete.
+// Both clearers below empty a file Claude Code reads hooks from; that is correct
+// only while settings.json ALSO registers them. On a plugin-only install (no
+// install.mjs-managed entries) the cache manifest is the sole registration, so
+// clearing it silently unregisters all seven events — and status/doctor then read
+// "settings.json holds none" as the healthy plugin shape. plugin-cache-guard.mjs
+// has documented this precondition since it was written and hook.mjs's self-heal
+// honours it; these two sites did not.
+//
+// `managedHooks` comes from the caller rather than a bare hasInstallManagedHooks()
+// call, and that is the whole point: install() runs configureHooks() first, so a
+// self-read here is ALWAYS true and the guard would be decorative — the real
+// protection would be the call ORDER, which nothing pins and a future reorder
+// would silently revert (pre-ship review, finding 1). Passing the value makes the
+// dependency data, not sequence. Explicit `false` is honoured; omitted → self-read,
+// for any caller that has not just written settings.json.
+const settingsOwnsHooks = managedHooks ?? hasInstallManagedHooks();
+
+// Scope note (pre-ship review, finding 2): the gate covers the two hook-CLEARING
+// blocks only. The launch.mjs / launch-preflight.mjs sync below it is not dedup —
+// it is issue #15's dev-mode MCP routing fix — and an early return out of the whole
+// function would silently stop shipping it to plugin-cache users.
+if (!settingsOwnsHooks) {
+  log('Plugin cache: hooks left in place (plugin-only install — the cache manifest is the only registration)');
+}
+
 if (existsSync(pluginDir)) {
   // NOTE: Do NOT clear marketplace .mcp.json — Claude Code copies from
   // marketplace clone → plugin cache on updates. Clearing it causes the
@@ -617,7 +677,7 @@ if (existsSync(pluginDir)) {
 
   // Clear plugin hooks to prevent double hook execution
   try {
-    if (existsSync(pluginHooksPath)) {
+    if (settingsOwnsHooks && existsSync(pluginHooksPath)) {
       const pluginHooks = JSON.parse(readFileSync(pluginHooksPath, 'utf8'));
       if (pluginHooks.hooks && Object.keys(pluginHooks.hooks).length > 0) {
         // Atomic (audit 2026-09-02 P1-10): a torn hooks.json is not a fail-open marker —
@@ -659,7 +719,7 @@ if (existsSync(pluginDir)) {
 
         // Clear cached hooks.json (runtime reads here, not marketplace source)
         const cachedHooksPath = join(verDir, 'hooks', 'hooks.json');
-        if (existsSync(cachedHooksPath)) {
+        if (settingsOwnsHooks && existsSync(cachedHooksPath)) {
           try {
             const h = JSON.parse(readFileSync(cachedHooksPath, 'utf8'));
             if (h.hooks && Object.keys(h.hooks).length > 0) {
@@ -862,6 +922,11 @@ writeSettings(settings);
 // kept saying five after the map changed, which is how a missing registration reads as
 // a successful one.
 ok(`Hooks configured (${Object.keys(hookConfigs).join(', ')})`);
+// Returned so dedupePluginCacheAndHooks gates on a VALUE this function produced
+// rather than re-reading settings.json — see the `managedHooks` note there. This
+// function writes all seven events unconditionally, so the answer is always true;
+// returning it keeps that fact in the caller's dataflow instead of in call order.
+return true;
 }
 
 function backupLegacyClaudeMemData() {
@@ -1231,8 +1296,14 @@ async function install() {
   await installDependencies(IS_DEV);
   createCliSymlink();
   registerMcpServer();
-  dedupePluginCacheAndHooks();
-  configureHooks();
+  // configureHooks BEFORE dedupe, and its result feeds the dedup gate: dedupe now
+  // refuses to clear a hooks manifest unless install.mjs-managed hooks exist in
+  // settings.json, and on a first install those entries do not exist until
+  // configureHooks writes them. Passing the value (rather than letting dedupe
+  // re-read settings.json) is what keeps a future reorder from silently turning the
+  // dedup off — the dependency is data, not sequence.
+  const managedHooks = configureHooks();
+  dedupePluginCacheAndHooks({ managedHooks });
   backupLegacyClaudeMemData();
   await installPreinstalledResources();
   verifyDatabase();
@@ -1452,7 +1523,15 @@ async function status() {
   } 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' });
+    // Open the manifest being credited. Trusting `settings.json holds none` alone
+    // reported all-green over an emptied cache manifest — zero hooks registered.
+    const manifest = pluginCacheHookEvents(shape.activePluginVersion.root);
+    if (manifest.ok) {
+      push('ok', 'hooks', `Hooks: provided by the plugin manifest (v${shape.activePluginVersion.version} hooks/hooks.json, ${manifest.events.length} events) — settings.json correctly holds none`, { configured: false, via: 'plugin', events: manifest.events });
+    } else {
+      const repair = hookManifestRepairHint(shape.activePluginVersion.root, join(homedir(), '.claude', 'plugins', 'marketplaces', MARKETPLACE_KEY));
+      push('fail', 'hooks', `Hooks: plugin manifest v${shape.activePluginVersion.version} registers NO hooks (${manifest.reason}) and settings.json holds none — every hook is unregistered. Repair: ${repair}`, { configured: false, via: 'plugin', events: [], manifest_reason: manifest.reason });
+    }
   } else {
     push('fail', 'hooks', 'Hooks: not configured', { configured: false });
   }
@@ -1688,8 +1767,17 @@ async function doctor() {
   } 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`);
+    // correctly-installed user their hooks were missing. But "correct state" is
+    // only half the question: read the manifest too, or an emptied one passes as
+    // the healthy shape (same false green as status).
+    const manifest = pluginCacheHookEvents(shape.activePluginVersion.root);
+    if (manifest.ok) {
+      ok(`Plugin lifecycle: hooks served by the plugin manifest (v${shape.activePluginVersion.version}, ${manifest.events.length} events); settings.json correctly holds none`);
+    } else {
+      fail(`Plugin lifecycle: plugin manifest v${shape.activePluginVersion.version} registers NO hooks (${manifest.reason}) and settings.json holds none — every hook is unregistered`);
+      log(`    Repair: ${hookManifestRepairHint(shape.activePluginVersion.root, join(homedir(), '.claude', 'plugins', 'marketplaces', MARKETPLACE_KEY))}`);
+      issues++;
+    }
   } else {
     dwarn('Plugin lifecycle: hooks not configured');
   }
@@ -2452,9 +2540,8 @@ function syncVersions() {
   const claudeMdPath = join(PROJECT_DIR, 'CLAUDE.md');
   if (existsSync(claudeMdPath)) {
     const orig = readFileSync(claudeMdPath, 'utf8');
-    const versionLine = /^- \*\*Version\*\*: .+$/m;
-    if (versionLine.test(orig)) {
-      const patched = orig.replace(versionLine, `- **Version**: ${version}`);
+    const patched = patchClaudeMdVersion(orig, version);
+    if (patched !== null) {
       if (patched !== orig) {
         writeFileSync(claudeMdPath, patched);
         ok(`CLAUDE.md: → ${version}`);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.95.0",
+  "version": "3.95.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.95.0",
+      "version": "3.95.1",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.30.0",
         "better-sqlite3": "^12.11.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.95.0",
+  "version": "3.95.1",
   "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",

package/plugin-cache-guard.mjs

@@ -64,6 +64,36 @@ export function clearPluginCacheHooks(opts) {
   return cleared.sort();
 }
 
+/**
+ * What a cache version's hooks/hooks.json ACTUALLY registers.
+ *
+ * The counterpart to hasInstallManagedHooks: on a plugin-only install this file
+ * is the sole hook registration, so an EMPTY one means every hook is dead. Both
+ * status and doctor used to credit "the plugin manifest serves the hooks" from
+ * `settings.json holds none` + `an active plugin version exists` alone, never
+ * opening the manifest — and an emptied manifest looks exactly like a healthy
+ * npm-shape install from those two facts. That false green is what let a cleared
+ * cache run for a full session reporting all-green with zero hooks firing.
+ *
+ * @param {string} root Cache version dir (shape.activePluginVersion.root)
+ * @returns {{ok: boolean, events: string[], reason: string|null}}
+ *          ok=false with reason 'no-manifest' | 'unreadable' | 'empty'
+ */
+export function pluginCacheHookEvents(root) {
+  const p = join(root, 'hooks', 'hooks.json');
+  if (!existsSync(p)) return { ok: false, events: [], reason: 'no-manifest' };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return { ok: false, events: [], reason: 'unreadable' };
+  }
+  const events = Object.keys(parsed?.hooks || {});
+  return events.length > 0
+    ? { ok: true, events, reason: null }
+    : { ok: false, events: [], reason: 'empty' };
+}
+
 export function hasInstallManagedHooks(opts) {
   const home = opts?.home || homedir();
   const plugin = opts?.plugin || DEFAULT_PLUGIN;

package/scripts/setup.sh

@@ -26,7 +26,13 @@ fi
 log_ok()   { echo -e "${GREEN}✓${NC} $*" >&2; }
 log_info() { echo -e "${BLUE}ℹ${NC} $*" >&2; }
 log_warn() { echo -e "${YELLOW}⚠${NC} $*" >&2; }
-# shellcheck disable=SC2317  # kept for API symmetry with log_ok/log_info/log_warn
+# shellcheck disable=SC2317,SC2329  # kept for API symmetry with log_ok/log_info/log_warn
+# Both codes on purpose: shellcheck 0.10.0 split "this function is never invoked" out of
+# SC2317 (unreachable command) into its own SC2329. The lone SC2317 stopped matching, so
+# 0.11.0 flags this line and `npx eslint`-style local runs exit 1 while CI stays green —
+# the ubuntu-latest runner still ships a pre-0.10 shellcheck. That is a version skew, not
+# a disagreement about the code: this job gates on exit 0, so it turns red on its own the
+# day GitHub bumps the runner image. Keep SC2317 for anyone on an older shellcheck.
 log_err()  { echo -e "${RED}✗${NC} $*" >&2; }
 
 # 1. Migrate unhidden dir (~/claude-mem-lite/ → ~/.claude-mem-lite/)