claude-mem-lite 3.95.0 → 3.96.0

package/.claude-plugin/marketplace.json

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

@@ -4,7 +4,11 @@ const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'c
 
 const cmd = process.argv[2];
 
-if (cmd === '--version' || cmd === '-v') {
+// `version` and `-V` are aliases, not extra syntax: the bare subcommand is what a user
+// types first (`claude-mem-lite version`), and it is far enough from every real command
+// name that the edit-distance suggester below fell through to the generic
+// "Run help / Run install" line — a wrong answer to a question the CLI can answer.
+if (cmd === '--version' || cmd === '-v' || cmd === '-V' || cmd === 'version') {
   const { readFileSync } = await import('fs');
   const { fileURLToPath } = await import('url');
   const { dirname, join } = await import('path');

package/hook-update.mjs

@@ -1053,7 +1053,50 @@ 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;
+  let s;
+  try { s = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { return false; }
+  const serialized = JSON.stringify(s.hooks || {});
+  if (!(serialized.includes('.claude-mem-lite/') || serialized.includes('/claude-mem-lite/'))) return false;
+  // Liveness, mirroring plugin-cache-guard.hasLiveInstallManagedHooks (see its docblock).
+  // The string test alone says settings.json MENTIONS a path of ours, not that the path
+  // still exists — and a stale entry left by a removed global install fires nothing while
+  // making this function authorise emptying the plugin manifest that does. Narrow by
+  // construction: only a command we parsed a path out of, ALL of whose paths are gone,
+  // flips the answer; an unfamiliar shape yields no path and keeps the old result.
+  let checked = 0;
+  for (const matchers of Object.values(s?.hooks || {})) {
+    if (!Array.isArray(matchers)) continue;
+    for (const m of matchers) {
+      for (const h of (Array.isArray(m?.hooks) ? m.hooks : [])) {
+        const c = typeof h?.command === 'string' ? h.command : '';
+        if (!(c.includes('.claude-mem-lite/') || c.includes('/claude-mem-lite/'))) continue;
+        let paths = [...c.matchAll(/"([^"]+)"/g)].map(x => x[1]).filter(p => p.startsWith('/'));
+        if (paths.length === 0) paths = c.split(/\s+/).filter(t => t.startsWith('/'));
+        for (const p of paths) {
+          checked++;
+          if (existsSync(p)) return true;
+        }
+      }
+    }
+  }
+  return checked === 0;
+}
 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/hook.mjs

@@ -1855,12 +1855,21 @@ async function handleSessionStart() {
   // Plugin cache self-heal: Claude Code auto-updates the marketplace plugin can
   // re-populate cache/<ver>/hooks/hooks.json, reintroducing duplicate hook
   // registration alongside install.mjs-managed settings.json entries. Silently
-  // clear — gated by hasInstallManagedHooks to avoid breaking plugin-only users.
+  // clear — gated to avoid breaking plugin-only users.
+  //
+  // The gate is hasLiveInstallManagedHooks, not the bare hasInstallManagedHooks: this
+  // branch EMPTIES the manifest, which is a dedup only while settings.json is really the
+  // other registration. A settings.json entry naming a deleted `~/.claude-mem-lite`
+  // launcher (global install removed by hand, plugin kept) satisfies the string test and
+  // fires nothing — so the self-heal read a dead registration as live and wiped the one
+  // that worked, every SessionStart. `?? hasInstallManagedHooks` keeps a guard module
+  // that predates the predicate working exactly as before.
   // Dynamic-import fallback: if plugin-cache-guard.mjs is missing (pre-2.31.2
   // auto-upgrade install), skip self-heal instead of crashing the entire hook.
   try {
     const guard = await loadCacheGuard();
-    if (guard.hasInstallManagedHooks && guard.hasInstallManagedHooks()) {
+    const ownsHooks = guard.hasLiveInstallManagedHooks ?? guard.hasInstallManagedHooks;
+    if (ownsHooks && ownsHooks()) {
       const cleared = guard.clearPluginCacheHooks({
         reason: 'Auto-healed by hook.mjs session-start — install.mjs-managed hooks active in settings.json',
       });

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');
   }
@@ -1781,7 +1869,16 @@ async function doctor() {
       // `validate` job (where the "old processes" were vitest's own workers) and it
       // reddens doctor-install-shape-e2e's "instead of going red forever" case on any
       // dev box with a previous-version session still open.
-      warn(`Old processes running${currentVersion ? ` (current: v${currentVersion})` : ''}:\n    ` + stale.join('\n    '));
+      //
+      // `dwarn`, not the bare `warn`: the first cut called the bare one, which prints the
+      // ⚠ line but never touches the `warnings` counter — so a doctor run whose ONLY
+      // finding was a stale launcher printed the ⚠ and then closed with
+      // "All checks passed!". That is the exact sentence buildDoctorSummary's docblock
+      // says must not lie, and the exact case tests/doctor-summary.test.mjs pins at the
+      // pure-function level; the counter simply never reached it from here. `dwarn`
+      // increments `warnings` only — `issues` stays 0, so the paragraph above still
+      // holds and `doctor` still exits 0.
+      dwarn(`Old processes running${currentVersion ? ` (current: v${currentVersion})` : ''}:\n    ` + stale.join('\n    '));
     } else {
       ok('No stale processes');
     }
@@ -2452,9 +2549,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/lib/import-jsonl.mjs

@@ -58,6 +58,16 @@ function importPrompt(db, ev, project, seenPrompts) {
         ? ev.message.content.filter(c => c?.type === 'text').map(c => c.text).join('\n')
         : '');
   if (!text) return false;
+  // Same sentinel the two LIVE writers refuse on (hook.mjs handleUserPrompt,
+  // scripts/user-prompt-search.js): <task-notification> is Claude Code protocol, not user
+  // input. Backfill is the third input boundary into user_prompts and was the only one
+  // persisting them — so a cold-start import seeded rows the live path would never write,
+  // which every reader then has to filter back out (`prompt_text NOT LIKE
+  // '<task-notification>%'` in search-core, search-engine and the UPS fallback). A reader
+  // that forgets the filter — `get P#N` and the timeline P# anchor do not have it — hands
+  // the agent protocol chatter as recalled context. Counted as `skipped`, which is what it
+  // is; the import stays idempotent because a skipped row was never inserted to re-match.
+  if (text.startsWith('<task-notification>')) return false;
   const sessionId = ev.sessionId || 'imported';
   const ts = ev.timestamp || new Date().toISOString();
   const safe = scrubSecrets(text.slice(0, 10000));

package/lib/recall-core.mjs

@@ -54,3 +54,34 @@ export function recallByFile(db, file, { limit = 10, includeNoise = false } = {}
 
   return { filename, rows };
 }
+
+/**
+ * Does a file-keyed recall have anything for `file`? COUNT only — no rows, and
+ * deliberately NO access_count/last_accessed_at bump.
+ *
+ * The bump in recallByFile above is correct there because a recall IS engagement and the
+ * tier/decay system feeds on it. This helper exists for the opposite situation: `search`
+ * wants to know, on a zero-result query that looks like a path, whether `recall` would
+ * have answered — a question ABOUT the store, asked on the user's behalf but not by them.
+ * Answering it through recallByFile would push the counters of rows nobody read, i.e. a
+ * measurement writing to what it measures. It shares the predicate rather than re-typing
+ * it, so `search`'s hint and `recall`'s answer can never disagree about what matches.
+ *
+ * `superseded_at IS NULL` and the LOW_SIGNAL filter come along for the same reason: a hint
+ * must promise only what the default `recall` will actually print.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} file Path or filename, same forms recallByFile accepts.
+ * @returns {number}
+ */
+export function countRecallableByFile(db, file) {
+  const { c = 0 } = db.prepare(`
+    SELECT COUNT(DISTINCT o.id) AS c
+    FROM observations o
+    JOIN observation_files of2 ON of2.obs_id = o.id
+    WHERE ${liveObsFilterSql('o')}
+      AND ${fileMatchClause('of2')}
+      AND ${notLowSignalTitleClause('o')}
+  `).get(...fileMatchParams(file)) || {};
+  return c;
+}

package/mem-cli.mjs

@@ -58,7 +58,7 @@ import { parseArgs, out, outVerbatim, fail, relativeTime, fmtDateShort, parseIdT
 import { saveObservation, saveWithClosures, formatSupersedeSkipped, formatSupersededNote } from './lib/save-observation.mjs';
 import { normalizeScope, insertObservationVector, applyObsUpdate } from './lib/observation-write.mjs';
 import { EXPORT_COLUMNS_SQL, buildExportWhere } from './lib/export-columns.mjs';
-import { recallByFile } from './lib/recall-core.mjs';
+import { recallByFile, countRecallableByFile } from './lib/recall-core.mjs';
 import { fetchRecent, RECENT_MAX } from './lib/recent-core.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
 import { buildSearchFtsQuery, parseDateBounds, parseDuration, coreRunSearchPipeline } from './lib/search-core.mjs';
@@ -90,6 +90,35 @@ import { shouldQueueSaveEnrich, queueSaveEnrich } from './lib/save-enrich.mjs';
 
 // ─── Commands ────────────────────────────────────────────────────────────────
 
+// A path query is not a text query, and `search` cannot tell the user so.
+//
+// OBS_FTS_COLUMNS (scoring-sql.mjs) indexes title/narrative/lesson/aliases/concepts — it
+// does NOT index `files`. File association lives in the observation_files junction, which
+// is `recall`'s table and only `recall`'s. So a save that named `src/payments/webhook.ts`
+// in --files and never mentioned it in prose is reachable by `recall` and unreachable by
+// `search`, and the user typing the path they were just editing gets a flat
+// "No results" — a true statement about the FTS index that reads as a false one about the
+// store. This is the one zero-result shape the CLI can positively disprove, so it does,
+// with the exact command that answers it.
+//
+// Cheap and quiet: one COUNT, only on a zero-result query that is a single whitespace-free
+// token shaped like a path or filename, and silent when that count is 0 (the ordinary case
+// — an ordinary prose query never reaches the COUNT at all). countRecallableByFile does
+// not bump access counters, so offering the hint cannot inflate the engagement signal of
+// rows the user has not read.
+function emitRecallHint(db, query) {
+  const q = String(query || '').trim();
+  if (!q || /\s/.test(q)) return;
+  if (!(q.includes('/') || q.includes('\\') || /\.[A-Za-z0-9]{1,8}$/.test(q))) return;
+  try {
+    const n = countRecallableByFile(db, q);
+    if (n > 0) {
+      out(`[mem] ${n} observation(s) are linked to that file — search indexes text, not file paths.`);
+      out(`[mem] Try: claude-mem-lite recall "${q}"`);
+    }
+  } catch { /* hint is best-effort; never break search */ }
+}
+
 async function cmdSearch(db, args, { llm } = {}) {
   const { positional, flags } = parseArgs(args);
 
@@ -295,6 +324,7 @@ async function cmdSearch(db, args, { llm } = {}) {
       out(JSON.stringify({ query, total: 0, returned: 0, offset, limit, deep: isDeep, variants: isDeep ? deepVariants : undefined, results: [] }));
     } else {
       out(`[mem] No results for "${query}"`);
+      emitRecallHint(db, query);
       // The zero-result path is where the trailer earns its keep — the D#92
       // failure chain was exactly "searched, found nothing, item was deferred".
       emitDeferredTrailer();
@@ -1696,9 +1726,24 @@ function cmdExport(db, args) {
   // truncated backup that lost rows on restore, and `--limit 5000` was REJECTED back
   // to 200 (can't back up >1000 at all). Now: omit --limit → LIMIT -1 (SQLite = no
   // limit); pass --limit N → honor any positive N (a backup may exceed 1000).
+  //
+  // The invalid-value branch has to land on that same -1, not on the sibling commands'
+  // `defaultValue: 200`. `parseIntFlag`'s warn-and-default contract is right for `search`
+  // and `recent`, where the default is a display width; here the default is COMPLETENESS,
+  // and defaulting a backup to 200 rows reopens the truncation the paragraph above closed
+  // — through the invalid door instead of the absent one. It is the same failure shape as
+  // the bare `--to` guard at the top of this function: `export --limit "$N" > backup.json`
+  // with `$N` unset or typo'd writes 200 rows, warns on a stderr the redirect usually
+  // discards, and exits 0. Recovering to the complete set is the only direction that
+  // cannot lose a row on restore.
   const limitGiven = flags.limit !== undefined && flags.limit !== null && flags.limit !== '';
   const limit = limitGiven
-    ? parseIntFlag(flags.limit, { name: '--limit', defaultValue: 200 })
+    ? parseIntFlag(flags.limit, {
+        name: '--limit',
+        defaultValue: -1,
+        warn: () => process.stderr.write(
+          `[mem] Invalid --limit "${flags.limit}" (must be an integer ≥ 1); exporting the COMPLETE matching set instead\n`),
+      })
     : -1;
   const format = flags.format || 'json';
   if (!['json', 'jsonl'].includes(format)) {
@@ -1742,7 +1787,10 @@ function cmdExport(db, args) {
     outVerbatim(JSON.stringify(rows, null, 2));
   }
 
-  if (limitGiven && rows.length >= limit) {
+  // `limit > 0`, not just `limitGiven`: an invalid `--limit` now recovers to the complete
+  // set (-1), and `rows.length >= -1` is always true — so the guard as written announced
+  // "Results capped at -1" on the one path that is guaranteed NOT to be capped.
+  if (limitGiven && limit > 0 && rows.length >= limit) {
     process.stderr.write(`[mem] Note: Results capped at ${limit}. Raise --limit or narrow --from/--to to export more.\n`);
   }
   // Fidelity caveat at backup-creation time (mirrors the restore-side note). stderr,

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.95.0",
+  "version": "3.96.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.95.0",
+      "version": "3.96.0",
       "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.96.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",

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;
@@ -75,3 +105,77 @@ export function hasInstallManagedHooks(opts) {
     return serialized.includes(`.${plugin}/`) || serialized.includes(`/${plugin}/`);
   } catch { return false; }
 }
+
+/** Every `command` string under settings.json `hooks`, in registration order. */
+function settingsHookCommands(home) {
+  const settingsPath = join(home, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return [];
+  let s;
+  try { s = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { return []; }
+  const out = [];
+  for (const matchers of Object.values(s?.hooks || {})) {
+    if (!Array.isArray(matchers)) continue;
+    for (const m of matchers) {
+      for (const h of (Array.isArray(m?.hooks) ? m.hooks : [])) {
+        if (typeof h?.command === 'string') out.push(h.command);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Absolute paths a hook command names. install.mjs writes `node "<abs>" …` /
+ * `bash "<abs>"`, so the quoted form is the shipped shape; the unquoted arm covers
+ * hand-edited and pre-quoting entries.
+ */
+function commandPaths(command) {
+  const paths = [];
+  for (const m of command.matchAll(/"([^"]+)"/g)) if (m[1].startsWith('/')) paths.push(m[1]);
+  if (paths.length === 0) {
+    for (const tok of command.split(/\s+/)) if (tok.startsWith('/')) paths.push(tok);
+  }
+  return paths;
+}
+
+/**
+ * Does settings.json register hooks we manage that can ACTUALLY RUN?
+ *
+ * `hasInstallManagedHooks` answers a string question — "does settings.json mention a
+ * path of ours" — and that is the right question for install(), which has just written
+ * those entries itself. It is the wrong question for the SessionStart self-heal, whose
+ * action is DESTRUCTIVE: clearing the plugin cache manifest is a dedup only while
+ * settings.json really is the other registration. A user who installed globally, later
+ * switched to the plugin, and removed `~/.claude-mem-lite` by hand (or by an
+ * `npm uninstall -g` that never ran our `uninstall`) leaves entries that name a deleted
+ * launcher. They fire nothing — and on that state the self-heal read them as a live
+ * registration and emptied the ONE manifest that was working, on every single
+ * SessionStart. v3.95.1 taught status/doctor to SEE that end state; this is the half
+ * that stops producing it.
+ *
+ * Deliberately narrow: a `false` is returned only when at least one managed command was
+ * parsed AND none of the paths it names exist. An unparseable or unfamiliar command shape
+ * keeps the old answer, so this can only ever remove the destructive branch from a case
+ * we positively verified as dead — never add it to one.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]
+ * @param {string} [opts.plugin]
+ * @returns {boolean}
+ */
+export function hasLiveInstallManagedHooks(opts) {
+  if (!hasInstallManagedHooks(opts)) return false;
+  const home = opts?.home || homedir();
+  const plugin = opts?.plugin || DEFAULT_PLUGIN;
+  const managed = settingsHookCommands(home)
+    .filter(c => c.includes(`.${plugin}/`) || c.includes(`/${plugin}/`));
+  let checked = 0;
+  for (const c of managed) {
+    for (const p of commandPaths(c)) {
+      checked++;
+      if (existsSync(p)) return true;
+    }
+  }
+  // No path we could check → keep hasInstallManagedHooks' answer (see docblock).
+  return checked === 0;
+}

package/scripts/prompt-search-utils.mjs

@@ -76,6 +76,19 @@ export const INTENTS = [
   { pattern: /implement|feature\b|add\s+(?:a\s+)?new|实现|添加|新功能|新增|开发|编写|创建|构建|做一个|加一个|写一个/i, type: null, limit: 3 },
   // Recall/history intent (catch-all temporal, lowest priority)
   // CJK: 刚才/历史/回顾 from real prompts; 碰到过|遇到过|见过|同样的问题 from spoken CN
+  //
+  // MEASURED AND REJECTED — do not re-add `remind me` here without a ruler (2026-09-05,
+  // 10-row typed corpus, sandbox install). The reasoning that it belongs is seductive and
+  // wrong: `remember` is already in this arm, `remind me` is its imperative twin, and its
+  // absence is the sole reason "remind me what we decided about session cookies" reaches
+  // hasExplicitSignal with no error signature, no file, no identifier and no CJK, and is
+  // dropped before FTS runs. Added, the prompt does fire — and this arm carries
+  // useRecent + limit 5, so when topical FTS comes back empty (it does: the OR floor
+  // drops a long multi-topic prompt whose best row shares only "session"/"cookies") the
+  // recency fallback spends FIVE injection slots on the five newest rows, and on the
+  // measured corpus the session-cookies decision was NOT among them. Five noise rows and
+  // no answer is worse than the silence it replaced. Any future attempt needs
+  // benchmark/citation-live-replay.mjs on the `fyi` face, not this intuition.
   { pattern: /before|previously|last time|remember|seen this|same\s+issue|之前|上次|以前|记得|刚才|历史|回顾|碰到过|遇到过|见过|同样的问题|类似的问题/i, type: null, limit: 5, useRecent: true },
 ];
 

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/)