claude-mem-lite 3.95.1 → 3.96.0

package/.claude-plugin/marketplace.json

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

@@ -1061,11 +1061,33 @@ function copyReleaseIntoStaging(sourceDir, stagingDir, manifest = { SOURCE_FILES
 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; }
+  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

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

@@ -1869,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');
     }

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

@@ -105,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 },
 ];