claude-mem-lite 3.75.0 → 3.75.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.75.0",
+      "version": "3.75.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.75.0",
+  "version": "3.75.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/haiku-client.mjs

@@ -190,8 +190,14 @@ export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500, temp
   // out-of-credit key must not silently drop background summaries.
   let primary = null;
   try {
+    // callModelAPI, not a second copy of it: the two were byte-identical apart from
+    // where the model id came from (MODEL_MAP[model] vs resolveModel().api — the same
+    // value, since resolveModel().cli is a MODEL_MAP key) and a hardcoded 'haiku-api'
+    // log label that lied under CLAUDE_MEM_MODEL=sonnet. Two copies of an HTTP client
+    // means every proxy fix has to land twice, on the path where missing the proxy is
+    // the difference between 1.4s and 13.5s.
     primary = mode === 'api'
-      ? await callHaikuAPI(prompt, { timeout, maxTokens, temperature })
+      ? await callModelAPI(prompt, resolveModel().cli, { timeout, maxTokens, temperature })
       : await callOpenRouterAPI(prompt, resolveModel().cli, { timeout, maxTokens, temperature });
   } catch (e) {
     debugCatch(e, `callHaiku:${mode}`);
@@ -683,63 +689,6 @@ export async function callModelCLIAsync(prompt, model, { timeout }) {
   return second.result;
 }
 
-// ─── API Mode ────────────────────────────────────────────────────────────────
-
-async function callHaikuAPI(prompt, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) return null;
-
-  const { api: modelId } = resolveModel();
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeout);
-
-  try {
-    const { system, user } = splitPrompt(prompt);
-    const body = {
-      model: modelId,
-      max_tokens: maxTokens,
-      temperature,
-      messages: [{ role: 'user', content: user }],
-    };
-    // See callModelAPI: cache_control on the constant system slot.
-    if (system) {
-      body.system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
-    }
-
-    // Proxy-aware, same as the OpenRouter site below. Missing it here meant the
-    // ANTHROPIC_API_KEY paths were the one keyed provider still doing a bare
-    // fetch — a silent outage behind a proxy, and one the new doctor check would
-    // have certified as healthy because it probes the hop this code was ASSUMED
-    // to use. (pre-tag review SHOULD-FIX 3)
-    const apiUrl = 'https://api.anthropic.com/v1/messages';
-    const apiHeaders = {
-      'Content-Type': 'application/json',
-      'x-api-key': apiKey,
-      'anthropic-version': '2023-06-01',
-    };
-    const apiProxy = httpConnectProxyFor(apiUrl);
-    const res = apiProxy
-      ? await postViaConnectProxy(apiProxy, apiUrl, { headers: apiHeaders, body: JSON.stringify(body), timeout })
-      : await fetch(apiUrl, {
-        method: 'POST',
-        headers: apiHeaders,
-        body: JSON.stringify(body),
-        signal: controller.signal,
-      });
-
-    if (!res.ok) {
-      debugLog('WARN', 'haiku-api', `HTTP ${res.status}`);
-      return null;
-    }
-
-    const data = await res.json();
-    const text = data.content?.[0]?.text;
-    return text ? { text } : null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 // ─── OpenRouter Mode ─────────────────────────────────────────────────────────
 
 // OpenRouter exposes an OpenAI-compatible chat-completions API (NOT the

package/hook-episode.mjs

@@ -246,37 +246,61 @@ export function mergePendingEntries(episode) {
   }
 }
 
+/** Rule 4's threshold — 8+ Read/Grep entries read as investigation. */
+const RESEARCH_ENTRY_THRESHOLD = 8;
+
 /**
- * Check if an episode has significant content worth processing with LLM.
- * Significant = contains file edits, Bash errors, or a review/research pattern
- * (8+ Read/Grep entries indicate investigation worth recording).
- * @param {object} episode The episode to check
- * @returns {boolean} true if the episode has significant content
+ * The significance decision WITH its reasoning, for instrumentation.
+ * `episodeHasSignificantContent` is the boolean face of this same body, so the meter
+ * and the decision cannot drift (audit 2026-08-22 P2-14).
+ *
+ * `grepDecisive` answers the one question the "move Grep into the bash skip list"
+ * decision is blocked on: would this episode still have been kept without its Grep
+ * entries? It is true ONLY when rule 4 decided AND the non-Grep entries alone fall
+ * short — an edit-driven episode that happens to contain Greps is not evidence that
+ * Grep carries research episodes.
+ *
+ * @param {object} episode
+ * @returns {{significant: boolean, rule: 1|2|3|4|null, readCount: number,
+ *   grepCount: number, grepDecisive: boolean}}
  */
-export function episodeHasSignificantContent(episode) {
+export function explainSignificance(episode) {
+  const entries = episode?.entries || [];
+  const grepCount = entries.filter(e => e.tool === 'Grep').length;
+  const readCount = entries.filter(e => e.tool === 'Read' || e.tool === 'Grep').length;
+  const base = { readCount, grepCount, grepDecisive: false };
+
   // 1. File edits → always significant (code changes matter)
-  const hasEdits = episode.entries.some(e => EDIT_TOOLS.has(e.tool));
-  if (hasEdits) return true;
+  if (entries.some(e => EDIT_TOOLS.has(e.tool))) return { ...base, significant: true, rule: 1 };
 
   // 2. Test/build errors → significant (actionable failures)
   // Plain bash errors without edits are noise (e.g. typos, exploration errors)
-  const hasTestOrBuildError = episode.entries.some(e =>
-    e.tool === 'Bash' && e.isError && (e.bashSig?.isTest || e.bashSig?.isBuild)
-  );
-  if (hasTestOrBuildError) return true;
+  if (entries.some(e => e.tool === 'Bash' && e.isError && (e.bashSig?.isTest || e.bashSig?.isBuild))) {
+    return { ...base, significant: true, rule: 2 };
+  }
 
   // 3. Important files touched (config, schema, security, migration)
   // Checks episode.files (all touched files, including reads) — catches important-file investigation
-  const allFiles = episode.files || [];
-  const hasImportantFile = allFiles.some(f =>
+  const allFiles = episode?.files || [];
+  if (allFiles.some(f =>
     /\.(env|yml|yaml|toml|lock|sql|prisma|proto)$/.test(f) ||
     /(config|schema|migration|auth|security)/i.test(f)
-  );
-  if (hasImportantFile) return true;
+  )) return { ...base, significant: true, rule: 3 };
 
   // 4. Research pattern: reading many files indicates investigation
-  const readCount = episode.entries.filter(e =>
-    e.tool === 'Read' || e.tool === 'Grep'
-  ).length;
-  return readCount >= 8;
+  if (readCount >= RESEARCH_ENTRY_THRESHOLD) {
+    return { ...base, significant: true, rule: 4, grepDecisive: readCount - grepCount < RESEARCH_ENTRY_THRESHOLD };
+  }
+  return { ...base, significant: false, rule: null };
+}
+
+/**
+ * Check if an episode has significant content worth processing with LLM.
+ * Significant = contains file edits, Bash errors, or a review/research pattern
+ * (8+ Read/Grep entries indicate investigation worth recording).
+ * @param {object} episode The episode to check
+ * @returns {boolean} true if the episode has significant content
+ */
+export function episodeHasSignificantContent(episode) {
+  return explainSignificance(episode).significant;
 }

package/hook-memory.mjs

@@ -1,7 +1,8 @@
 // claude-mem-lite — Semantic Memory Injection
 // Search past observations for relevant memories to inject as context at user-prompt time.
 
-import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters, basenameAnySep } from './utils.mjs';
+import { relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters, basenameAnySep } from './utils.mjs';
+import { upsFtsQuery } from './lib/ups-query.mjs';
 import { citeFactorJs, TYPE_QUALITY, TYPE_QUALITY_DEFAULT } from './scoring-sql.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { recordMetric } from './lib/metrics.mjs';
@@ -192,7 +193,12 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
   };
 
   try {
-    const ftsQuery = sanitizeFtsQuery(userPrompt);
+    // upsFtsQuery, not bare sanitizeFtsQuery: this is the SECOND hook UserPromptSubmit
+    // fires, and v3.75.0 capped only the first. This one is the worse half — its stdin
+    // ceiling is MAX_HOOK_STDIN_BYTES (256KB) against path A's 64KB, and nothing
+    // truncates between stdin and here. The caps are shared, not copied, so the two
+    // faces of one event cannot drift apart again.
+    const ftsQuery = upsFtsQuery(userPrompt);
     if (!ftsQuery) return [];
 
     const cutoff = Date.now() - MEMORY_LOOKBACK_MS;
@@ -243,7 +249,15 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     if (rows.length === 0) {
       const orQuery = relaxFtsQueryToOr(ftsQuery);
       if (orQuery && (queryIsCjkDominant || queryTokenCount <= orFallbackMaxTokens)) {
-        try { rows = selectStmt.all(orQuery, project, cutoff); usedOrFallback = true; } catch {}
+        // debugCatch, not a bare swallow: this is the injection chain's LAST query, and
+        // an FTS5 fault here (corrupt index, malformed relaxed query) degrades to an
+        // EMPTY injection that reads exactly like "nothing matched" — invisible to
+        // stats and doctor alike. Still non-fatal; the prompt must go through.
+        // (The two bare catches further down, around the per-row access bumps, are
+        // deliberately left bare: they are write-path and per-row, so logging them would
+        // flood the debug stream on the same corruption this one reports once.)
+        try { rows = selectStmt.all(orQuery, project, cutoff); usedOrFallback = true; }
+        catch (e) { debugCatch(e, 'injectMemory:orFallback'); }
       }
     }
 
@@ -274,7 +288,10 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       if (crossRows.length === 0) {
         const orQuery = relaxFtsQueryToOr(ftsQuery);
         if (orQuery && (queryIsCjkDominant || queryTokenCount <= orFallbackMaxTokens)) {
-          try { crossRows = crossStmt.all(orQuery, project, cutoff); crossUsedOr = true; } catch {}
+          // Same reasoning as the same-project OR fallback above: a fault here silently
+          // drops the cross-project half of the injection.
+          try { crossRows = crossStmt.all(orQuery, project, cutoff); crossUsedOr = true; }
+          catch (e) { debugCatch(e, 'injectMemory:crossOrFallback'); }
         }
       }
     } catch (e) { debugCatch(e, 'crossProjectSearch'); }

package/hook.mjs

@@ -33,7 +33,7 @@ import {
   readEpisodeRaw, episodeFile,
   acquireLock, releaseLock, readEpisode, writeEpisode,
   createEpisode, addFileToEpisode, planEpisodeFlush,
-  writePendingEntry, mergePendingEntries, episodeHasSignificantContent,
+  writePendingEntry, mergePendingEntries, episodeHasSignificantContent, explainSignificance,
 } from './hook-episode.mjs';
 import { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-context.mjs';
 import { entry as preCompactEntry } from './hook-precompact.mjs';
@@ -294,7 +294,21 @@ function flushEpisodeWithDb(db, episode, hookEventName) {
 // suppresses the detached enrichment spawn (test determinism; sibling of
 // CLAUDE_MEM_SKIP_COMPRESS / _OPTIMIZE) — the synchronous immediate obs still lands.
 function flushEpisodeGroup(ep, db) {
-  const isSignificant = episodeHasSignificantContent(ep);
+  const verdict = explainSignificance(ep);
+  const isSignificant = verdict.significant;
+  // Audit P2-14 instrument: moving Grep into the bash prefilter would save 85ms per Grep
+  // (91.2ms handoff vs 6.1ms for the already-skipped Read), but nothing records how many
+  // episodes are kept ONLY because of their Greps — and demoting what the product
+  // remembers on a deduction is how work disappears silently. This is that counter.
+  // Off unless CLAUDE_MEM_METRICS=1, like every other row in this sink.
+  recordMetric(join(RUNTIME_DIR, '..'), {
+    event: 'episode_significance',
+    rule: verdict.rule,
+    significant: isSignificant,
+    readCount: verdict.readCount,
+    grepCount: verdict.grepCount,
+    grepDecisive: verdict.grepDecisive,
+  });
 
   // Immediate save: rule-based observation for instant visibility; the LLM
   // background worker upgrades title/narrative/importance later. `db` is
@@ -809,10 +823,13 @@ async function handleStop() {
           } catch (e) { debugCatch(e, 'handleStop-citation-decay'); }
 
           // Persist cite-recall ratio for the next SessionStart to surface as
-          // feedback. We deliberately scan the transcript a second time here
-          // (cheap; the file is already in OS cache) rather than threading the
-          // count through `extractCitationsFromTranscript` so the bump path stays
-          // unchanged.
+          // feedback. This block re-scans the transcript rather than threading the
+          // count through `extractCitationsFromTranscript`, so the bump path stays
+          // unchanged — and since P2-8 every scanner in it shares ONE parse via
+          // lib/transcript-scan.mjs, so "scan again" costs an array iteration, not a
+          // re-read. (The old wording, "cheap; the file is already in OS cache", was
+          // arguing the pre-memo case: the OS cache saved the read, never the parse,
+          // which was ~all of the cost.)
           try {
             const stats = computeCiteRecall(transcriptPath);
             // B2 (v2.83.1): also persist the bugfix-shape nudge/save delta so
@@ -939,7 +956,48 @@ function runSessionStartDbMutations(db, { sessionId, project, prevSessionId, now
   })();
 }
 
+// Per-project 24h gate for the auto-compressible marking. Separate from the global
+// maintain gate on purpose: the marking is project-scoped work that every project needs
+// daily, while the pass it used to ride on (VACUUM snapshot + purge + decay + dedup) is
+// whole-DB work that should happen once a day in total.
+function markCompressibleGateFile(project) {
+  // Project names arrive already mangled by inferProject (`projects--mem`), but this is
+  // a filename, so do not trust that — one stray separator writes outside RUNTIME_DIR.
+  return join(RUNTIME_DIR, `last-mark-compressible-${String(project).replace(/[^A-Za-z0-9._-]/g, '-')}.json`);
+}
+
+function markAutoCompressibleIfDue(db, project) {
+  if (!project) {
+    // Every production spawn passes it (spawnBackground('auto-maintain', project)); a
+    // hand-run `hook.mjs auto-maintain` does not. Say so rather than skipping in
+    // silence — work vanishing without a word is this codebase's recurring shape.
+    debugLog('DEBUG', 'auto-maintain', 'no project argument — skipping auto-compress marking');
+    return;
+  }
+  const gate = markCompressibleGateFile(project);
+  try {
+    const last = JSON.parse(readFileSync(gate, 'utf8'));
+    if (Date.now() - last.epoch < 24 * 3600000) return;
+  } catch { /* no gate file → due */ }
+  try {
+    const marked = markAutoCompressible(db, project);
+    if (marked.aged > 0) debugLog('DEBUG', 'auto-maintain', `auto-compressed ${marked.aged} old observations`);
+    if (marked.noise > 0) debugLog('DEBUG', 'auto-maintain', `auto-compressed ${marked.noise} LOW_SIGNAL noise (7d window)`);
+    writeFileSync(gate, JSON.stringify({ epoch: Date.now() }));
+  } catch (e) { debugCatch(e, 'auto-maintain-mark-compressible'); }
+}
+
 function runSessionStartAutoMaintain(db, project) {
+  // The auto-compressible marking runs on its OWN per-project gate, before the global
+  // one below. v3.75.0 moved this work off SessionStart onto this worker (P2-11) and,
+  // by putting it inside the global `shouldMaintain` block, cut its coverage from
+  // "every project, every boot" to "one project per 24h" — RUNTIME_DIR is a single
+  // global directory, so whichever project wins the gate is the only one marked, and
+  // with N projects in rotation N-1 never get the 7-day noise pass. The move was right;
+  // the shared gate was not. Heavy work (VACUUM snapshot, purge, decay, dedup) stays on
+  // the global gate — that genuinely should run once a day, not once per project.
+  markAutoCompressibleIfDue(db, project);
+
   // Auto-maintain: cleanup + decay + boost + purge, gated to once per 24h
   const maintainFile = join(RUNTIME_DIR, 'last-auto-maintain.json');
   let shouldMaintain = true;
@@ -969,19 +1027,10 @@ function runSessionStartAutoMaintain(db, project) {
       // children (compressed_into dangling at a deleted id). purgeStale recovers them
       // first and caps at opCap. Schema has no marked_at_epoch, so retention anchors on
       // created_at_epoch: 30d marking gate + 7d grace = 37d.
-      // Mark auto-compressible rows BEFORE the purge/decay ops below, preserving the
-      // order the SessionStart transaction had relative to them (marking ran first, at
-      // boot). Project-scoped exactly as before — P2-11 moved the cadence, not the scope.
-      if (project) {
-        const marked = markAutoCompressible(db, project);
-        if (marked.aged > 0) debugLog('DEBUG', 'auto-maintain', `auto-compressed ${marked.aged} old observations`);
-        if (marked.noise > 0) debugLog('DEBUG', 'auto-maintain', `auto-compressed ${marked.noise} LOW_SIGNAL noise (7d window)`);
-      } else {
-        // Every production spawn passes it (spawnBackground('auto-maintain', project)); a
-        // hand-run `hook.mjs auto-maintain` does not. Say so rather than skipping in
-        // silence — work vanishing without a word is this codebase's recurring shape.
-        debugLog('DEBUG', 'auto-maintain', 'no project argument — skipping auto-compress marking');
-      }
+      // The marking itself already ran at the top of this function, on its own
+      // per-project gate — it must not be conditioned on the global one (see
+      // markAutoCompressibleIfDue). It still happens BEFORE the purge/decay ops below,
+      // preserving the order the SessionStart transaction had relative to them.
 
       const purged = purgeStale(db, mctx, Date.now() - 37 * DAY_MS);
       if (purged > 0) debugLog('DEBUG', 'auto-maintain', `purged ${purged} stale observations`);
@@ -1112,11 +1161,19 @@ function runSessionStartAutoMaintain(db, project) {
 // a detached `auto-maintain` worker via spawnBackground so it never blocks interactive
 // session start. The worker re-checks the same gate (idempotent) before doing the work.
 function scheduleSessionStartAutoMaintain(project) {
-  const maintainFile = join(RUNTIME_DIR, 'last-auto-maintain.json');
-  try {
-    const last = JSON.parse(readFileSync(maintainFile, 'utf8'));
-    if (Date.now() - last.epoch < 24 * 3600000) return; // not due — no spawn
-  } catch { /* no gate file → due */ }
+  // TWO gates, either of which is enough to spawn. Checking only the global one is what
+  // made the marking single-project in v3.75.0: in a multi-project rotation the global
+  // stamp is already fresh by the time the second project boots, so its worker never
+  // ran and its rows were never marked.
+  const due = (file) => {
+    try {
+      const last = JSON.parse(readFileSync(file, 'utf8'));
+      return Date.now() - last.epoch >= 24 * 3600000;
+    } catch { return true; }   // no gate file → due
+  };
+  const maintainDue = due(join(RUNTIME_DIR, 'last-auto-maintain.json'));
+  const markingDue = Boolean(project) && due(markCompressibleGateFile(project));
+  if (!maintainDue && !markingDue) return;
   if (!process.env.CLAUDE_MEM_SKIP_MAINTAIN) spawnBackground('auto-maintain', project);
 }
 

package/lib/citation-tracker.mjs

@@ -15,6 +15,9 @@ import { join } from 'path';
 import { debugCatch } from '../utils.mjs';
 import { keyContextIdsFileName } from './injected-ids.mjs';
 import { readTranscriptEntries } from './transcript-scan.mjs';
+// The emitter's own prefix — see SURFACE_MATCHERS.task_imperative. Importing it rather
+// than re-typing the framing is what keeps emit and extract from becoming two lists.
+import { TASK_IMPERATIVE_PREFIX } from './task-imperative.mjs';
 
 import { DAY_MS } from './time-constants.mjs';
 // `#123` / `#45678` at a word boundary — matches the CLAUDE.md cite pattern.
@@ -231,15 +234,21 @@ const FYI_LINE_ID_RE = /^#(\d{1,7})\s/;
 
 /**
  * The injection FACES memory can reach the model through, as stored in
- * `citation_surface_log.surface` (schema v45). The first four are
+ * `citation_surface_log.surface` (schema v45). The first five are
  * query-conditioned — a row appears there because it MATCHED something — and
  * are the ones that feed the citation-decay denominator via extractAllInjected.
  * `keyctx` is the odd one out: an unconditional SessionStart render, recorded
  * for VISIBILITY only and promotion-only in the decay loop (see
  * extractInjectedFromKeyContext).
- * @type {ReadonlyArray<'pretool'|'ups'|'error_recall'|'fyi'|'keyctx'>}
+ *
+ * `task_imperative` (v3.76) rides the SAME attachment as `ups` — one
+ * `hook.mjs user-prompt` invocation writes the `<memory-context>` block and then the
+ * imperative line — which is how it stayed unmetered since v3.23 while being a live
+ * injection: the `ups` matcher gates on `<memory-context` and collects only `- [` rows.
+ * The two faces therefore OVERLAP on attachments but never on ids.
+ * @type {ReadonlyArray<'pretool'|'ups'|'error_recall'|'fyi'|'task_imperative'|'keyctx'>}
  */
-export const CITATION_SURFACES = ['pretool', 'ups', 'error_recall', 'fyi', 'keyctx'];
+export const CITATION_SURFACES = ['pretool', 'ups', 'error_recall', 'fyi', 'task_imperative', 'keyctx'];
 
 // Single source of truth for "which attachment belongs to which face, and how
 // its ids are read off". Both the per-face extractors below AND the one-pass
@@ -307,6 +316,24 @@ const SURFACE_MATCHERS = {
       }
     },
   },
+  task_imperative: {
+    // Same hook entry as `ups`, different row. Gating on the emitter's own exported
+    // prefix (not a copy of the wording) keeps the meter tied to the framing; gating on
+    // the COMMAND too means a transcript that merely quotes the framing — a review of
+    // this code, say — is not counted as an injection.
+    accepts: ({ command, text }) =>
+      command.includes(UPS_COMMAND_SUFFIX) && text.includes(TASK_IMPERATIVE_PREFIX),
+    collect: (text, add) => {
+      for (const line of text.split('\n')) {
+        if (!line.startsWith(TASK_IMPERATIVE_PREFIX)) continue;
+        // Trailing `(#NN)` is this lesson's own id; earlier ones are cross-references
+        // inside the body (#8850 — an inlined lesson body must not pollute the set).
+        const matches = [...line.matchAll(UPS_ID_RE)];
+        if (matches.length === 0) continue;
+        add(matches[matches.length - 1][1]);
+      }
+    },
+  },
 };
 
 // The query-conditioned faces, in citation_surface_log label order. keyctx is
@@ -452,19 +479,39 @@ export function extractAllInjected(transcriptPath, opts = {}) {
   return unionSurfaces(extractInjectedBySurface(transcriptPath, opts));
 }
 
+/**
+ * Faces that are METERED (a citation_surface_log row) but deliberately kept OUT of the
+ * citation-decay denominator, with the reason each is here. Membership is a decision,
+ * never a default: `unionSurfaces` still walks every SURFACE_MATCHERS key, and a test
+ * requires each face to be either in the union or listed here — so a face added later
+ * cannot slip out of the denominator by being forgotten, only by being argued for.
+ *
+ * - `task_imperative` (v3.76): metering it is the point of adding it — D#137/D#150/D#151
+ *   are all blocked on not knowing this face's cite-rate. Widening the denominator at the
+ *   same moment would change what gets demoted in every live install on upgrade, and it
+ *   would do so on the face whose framing is itself the open question: if the imperative
+ *   framing under-performs, the penalty lands on the LESSONS it carried (imperativePick
+ *   selects high-value ones) rather than on the framing. Read the rate first, then decide.
+ *   Removing an entry from this set is the one-line change that widens the denominator.
+ */
+const DECAY_EXCLUDED_SURFACES = new Set(['task_imperative']);
+
+/** @type {ReadonlyArray<string>} faces that DO feed the decay denominator. */
+export const DECAY_DENOMINATOR_SURFACES = ATTACHMENT_SURFACES.filter((f) => !DECAY_EXCLUDED_SURFACES.has(f));
+
 /**
  * Flatten a per-face breakdown into the single injected set the decay loop
  * takes. Derived — NOT a second hand-maintained face list — so adding a face to
  * SURFACE_MATCHERS automatically widens the denominator (v45; the pre-v45 union
  * enumerated the faces a second time and that is exactly how a face goes
- * unmetered).
+ * unmetered), unless that face is argued into DECAY_EXCLUDED_SURFACES above.
  *
  * @param {Record<string, Set<number>>} bySurface
  * @returns {Set<number>}
  */
 export function unionSurfaces(bySurface) {
   const out = new Set();
-  for (const face of ATTACHMENT_SURFACES) {
+  for (const face of DECAY_DENOMINATOR_SURFACES) {
     for (const id of bySurface?.[face] || []) out.add(id);
   }
   return out;

package/lib/persist-reminder.mjs

@@ -11,7 +11,7 @@
 // the context). Remind-only by design: false positives cost one line, so the
 // signal list stays conservative and never auto-writes anything.
 
-import { readFileSync, existsSync } from 'fs';
+import { readTranscriptEntries } from './transcript-scan.mjs';
 
 // Distinctive finalization word forms (CJK + EN). Deliberately NOT included:
 // "方案 A 定" and bare "定" (too FP-prone), bare "ok/好" (noise). The list is
@@ -62,14 +62,14 @@ const MEMDIR_WRITE_RE = /[\\/]\.claude[\\/]projects[\\/][^\\/]+[\\/]memory[\\/][
  * `save` / `defer add`) in the session transcript. 0 on missing/unreadable.
  */
 export function countDeliberatePersistence(transcriptPath) {
-  if (!transcriptPath || !existsSync(transcriptPath)) return 0;
-  let raw;
-  try { raw = readFileSync(transcriptPath, 'utf8'); } catch { return 0; }
+  // Shares the Stop-time parse (lib/transcript-scan.mjs) rather than doing its own
+  // read+split+parse. It was the NINTH scanner of the same file and was missed when the
+  // other eight were collapsed — sitting two lines away from two that were migrated, so
+  // it was quietly charging a full re-parse (~20-25ms on a 5.7MB transcript) against a
+  // pass whose whole point was to stop doing that. Missing/unreadable paths still yield
+  // 0, because readTranscriptEntries returns [] for them.
   let count = 0;
-  for (const line of raw.split('\n')) {
-    if (!line.trim()) continue;
-    let entry;
-    try { entry = JSON.parse(line); } catch { continue; }
+  for (const entry of readTranscriptEntries(transcriptPath)) {
     if (entry.type !== 'assistant' && entry.message?.role !== 'assistant') continue;
     const content = entry.message?.content;
     if (!Array.isArray(content)) continue;

package/lib/task-imperative.mjs

@@ -12,11 +12,18 @@ import { neutralizeContextDelimiters } from '../format-utils.mjs';
 // dropped.
 // Spec: docs/superpowers/specs/2026-06-29-task-imperative-memory-injection-design.md
 
+// The emitted line's fixed head. Exported because lib/citation-tracker.mjs matches on
+// it to meter this face: an extractor carrying its own copy of the framing is the exact
+// shape that silenced Go panics in v3.74.0 (trigger and filter were two lists that were
+// never the same list). One constant, both directions — change the framing and the
+// meter follows, or nothing does.
+export const TASK_IMPERATIVE_PREFIX = 'Memory — a past lesson applies to THIS task.';
+
 export function formatTaskImperative(lesson, id) {
   const body = neutralizeContextDelimiters(String(lesson || '').trim().replace(/\.$/, ''));
   if (!body) return '';
   const tag = (id === undefined || id === null || id === '') ? '' : ` (#${id})`;
-  return `Memory — a past lesson applies to THIS task. You must: ${body}.${tag}`;
+  return `${TASK_IMPERATIVE_PREFIX} You must: ${body}.${tag}`;
 }
 
 // Subagent-dispatch framing. Subagents are memory-blind (plugin hooks don't fire

package/lib/ups-query.mjs

@@ -0,0 +1,26 @@
+// lib/ups-query.mjs — the ONE query-cap definition for the UserPromptSubmit event.
+//
+// That event fires two hooks: scripts/user-prompt-search.js (the FYI block) and
+// `hook.mjs user-prompt` (the <memory-context> block). v3.75.0 capped the first and left
+// the second building an uncapped query from the raw prompt — the guard-on-one-path shape
+// this codebase pays for more than any other. Both faces now import from here, so the cap
+// cannot be present on one and absent on the other.
+//
+// The caps bound what is COMPUTED, not what is read. The stdin guards upstream
+// (MAX_UPS_PROMPT_BYTES 64KB on path A, MAX_HOOK_STDIN_BYTES 256KB on path B) cap the
+// input; sanitizeFtsQuery still costs 0.8ms on a normal prompt, 6.2ms on a 64KB ASCII one
+// and 31.8ms on a 64KB CJK one (extractCjkKeywords is O(len x dict) over an unsegmented
+// run), all of it before the model sees the turn. 2000 characters is a long prompt by any
+// measure, and past ~64 meaningful AND-joined terms an FTS5 query matches nothing anyway
+// and survives only through the OR fallback.
+//
+// An explicit `claude-mem-lite search` stays UNCAPPED — a person who types a long query
+// meant it. Only these two automatic surfaces pass the caps.
+import { sanitizeFtsQuery } from '../utils.mjs';
+
+export const UPS_QUERY_CAPS = { maxChars: 2000, maxTokens: 64 };
+
+/** The capped query builder every automatic prompt-time search path goes through. */
+export function upsFtsQuery(text) {
+  return sanitizeFtsQuery(text, UPS_QUERY_CAPS);
+}

package/mem-cli.mjs

@@ -70,11 +70,12 @@ import { computeCitationFunnelTrend, computeSurfaceFunnel } from './lib/citation
 // the citation-stats face table lines up; the enum itself lives in
 // lib/citation-tracker.mjs (CITATION_SURFACES).
 const SURFACE_LABELS = {
-  pretool:      'PreToolUse recall  ',
-  ups:          'UserPromptSubmit   ',
-  error_recall: 'error-recall       ',
-  fyi:          'FYI (prompt-search)',
-  keyctx:       'Key Context        ',
+  pretool:        'PreToolUse recall  ',
+  ups:            'UserPromptSubmit   ',
+  error_recall:   'error-recall       ',
+  fyi:            'FYI (prompt-search)',
+  task_imperative: 'task-imperative   ',
+  keyctx:         'Key Context        ',
 };
 import { aggregateMetrics, readMetrics } from './lib/metrics.mjs';
 import {
@@ -2806,6 +2807,9 @@ Commands:
 
   doctor                Environment diagnostics and benchmarks
     --benchmark         Run perf benchmark and emit JSON
+    --metrics           Summarize the recorded metrics window (CLAUDE_MEM_METRICS=1)
+    --session-audit     Audit session/episode state for orphans and drift
+    --json              Machine-readable output (plain doctor run)
 
   fts-check <check|rebuild>  FTS5 index check or rebuild
 
@@ -2841,6 +2845,7 @@ Commands:
     import              Import resource --name N --resource-type T [--repo-url U] [--local-path P] [--use-cases U]
     remove              Remove resource --name N --resource-type T
     reindex             Rebuild FTS5 index
+    recommend-stats     Shadow recommendation funnel [--days N] [--sweep] [--json]
 
   import-jsonl <file-or-dir>      Import Claude Code JSONL transcripts (cold-start backfill)
     --project P         Project name (default: inferred from cwd)

package/memdir.mjs

@@ -209,7 +209,11 @@ export function writePluginSection(memdir, { slug, version, contentLine, force =
     }
   }
 
-  const next = raw.replace(match[0], freshSection);
+  // Function form, NOT the string form: a string second argument has `$&` / `$1` /
+  // "$`" / `$'` interpreted, and freshSection carries caller-supplied contentLine — a
+  // `$&` there would expand to the whole matched sentinel block. Same fix claudemd.mjs
+  // took at its own replace (v3.40); this was the twin that kept the string form.
+  const next = raw.replace(match[0], () => freshSection);
   const changed = next !== raw;
   if (changed) atomicWrite(path, next);
   writeState(memdir, slug, { version, bodyHash: freshHash, writtenAt: new Date().toISOString() });

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.75.0",
+  "version": "3.75.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.75.0",
+      "version": "3.75.1",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",
@@ -21,6 +21,7 @@
         "eslint": "^10.0.0",
         "fast-check": "^4.5.3",
         "knip": "^6.12.1",
+        "picomatch": "^4.0.4",
         "vitest": "^4.0.18"
       },
       "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.75.0",
+  "version": "3.75.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",
@@ -113,6 +113,7 @@
     "lib/maintain-core.mjs",
     "lib/fast-summary.mjs",
     "lib/transcript-scan.mjs",
+    "lib/ups-query.mjs",
     "lib/dedup-constants.mjs",
     "lib/deferred-work.mjs",
     "lib/upgrade-banner.mjs",
@@ -198,6 +199,7 @@
     "eslint": "^10.0.0",
     "fast-check": "^4.5.3",
     "knip": "^6.12.1",
+    "picomatch": "^4.0.4",
     "vitest": "^4.0.18"
   }
 }

package/schema.mjs

@@ -280,7 +280,9 @@ const CORE_SCHEMA = `
   -- v45: per-INJECTION-FACE twin of citation_log. One row per
   -- (project, session, surface); the surface column is one of the
   -- CITATION_SURFACES enum in lib/citation-tracker.mjs
-  -- (pretool | ups | error_recall | fyi | keyctx).
+  -- (pretool | ups | error_recall | fyi | task_imperative | keyctx). The column is plain
+  -- TEXT with no CHECK: the JS enum is the gate (recordCitationSurfaces drops unknown
+  -- labels), which is why adding a face needs no migration.
   --
   -- session_id is the CLAUDE CODE session id, NOT the memory session id that
   -- keys citation_log. The two tables therefore do NOT join, on purpose. The

package/scripts/user-prompt-search.js

@@ -4,9 +4,10 @@
 // Lightweight: only imports schema.mjs and utils.mjs, no MCP SDK
 
 import { ensureDb, DB_DIR, REGISTRY_DB_PATH } from '../schema.mjs';
-import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, notLowSignalTitleClause, stripPrivate, neutralizeContextDelimiters, MAX_UPS_PROMPT_BYTES } from '../utils.mjs';
+import { relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, notLowSignalTitleClause, stripPrivate, neutralizeContextDelimiters, MAX_UPS_PROMPT_BYTES } from '../utils.mjs';
 import { liveObsFilterSql, injectionRelevanceSql } from '../lib/inject-search-core.mjs';
 import { cjkPrecisionOk } from '../nlp.mjs';
+import { upsFtsQuery } from '../lib/ups-query.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
 import { join, sep } from 'path';
 import { pathToFileURL } from 'url';
@@ -343,21 +344,11 @@ export function hasExplicitSignal(text, { errSig, files, intent } = {}) {
 // ×3 runs) → VERDICT NET-POSITIVE. The only behavior delta is on-topic eagerness (naming
 // an identifier surfaces its obs) — the highest-precision injection trigger there is. The
 // prose stop-list (IDENTIFIER_STOPWORDS) keeps the extractor off ordinary English.
-export // Query caps for THIS surface only (audit 2026-08-22 P2-13). The 64KB byte guard on
-// stdin bounds what we read, not what we compute: sanitizeFtsQuery costs 0.8ms on a
-// normal prompt, 6.2ms on a 64KB ASCII one and 31.8ms on a 64KB CJK one, and this hook
-// runs on every prompt before the model sees the turn. 2000 characters is a long prompt
-// by any measure, and past ~64 meaningful AND-joined terms an FTS5 query matches nothing
-// anyway and survives only through the OR fallback. An explicit `search` stays uncapped
-// — a person who types a long query meant it.
-const UPS_QUERY_CAPS = { maxChars: 2000, maxTokens: 64 };
-
-/** The capped query builder both search paths on this surface go through. */
-export function upsFtsQuery(text) {
-  return sanitizeFtsQuery(text, UPS_QUERY_CAPS);
-}
+// Query caps live in lib/ups-query.mjs — shared with `hook.mjs user-prompt`, the OTHER
+// hook this same event fires. v3.75.0 capped this face only; a second copy of the
+// constants here is what would let them drift apart again.
 
-const IDENTIFIER_BYPASS = process.env.CLAUDE_MEM_UPS_IDENTIFIER_BYPASS !== '0';
+export const IDENTIFIER_BYPASS = process.env.CLAUDE_MEM_UPS_IDENTIFIER_BYPASS !== '0';
 const TECH_IDENTIFIER_RE_G = new RegExp(TECH_IDENTIFIER_RE.source, 'g');
 
 // All tech-identifier tokens in `text`, lowercased + de-duped (for case-insensitive

package/source-files.mjs

@@ -149,6 +149,9 @@ export const SOURCE_FILES = [
   // search-engine.mjs AND the standalone hook scripts — missing it from the
   // manifest kills every retrieval surface on auto-update.
   'lib/inject-search-core.mjs',
+  // Shared UserPromptSubmit query caps — imported by BOTH hooks that event fires
+  // (scripts/user-prompt-search.js and hook.mjs user-prompt via hook-memory.mjs).
+  'lib/ups-query.mjs',
   // P2-12 twin cores: get/browse shared data collection for the CLI/MCP pairs
   // (update lives in observation-write, delete-preview in delete-core, registry
   // stats/list in registry.mjs — all already listed).

package/utils.mjs

@@ -21,6 +21,9 @@ export { detectBashSignificance, extractErrorKeywords, planErrorRecall, extractF
 // Internal imports for functions that remain in this module
 import { truncate } from './format-utils.mjs';
 import { stripTestSuffix } from './bash-utils.mjs';
+// Static, and deliberately the dependency-free resolver (node:os + node:path only) —
+// debugCatch's sampler must not pull in the DB layer. See its comment below.
+import { resolveDataDir } from './lib/resolve-data-dir.mjs';
 
 // ─── Sentinel Values ────────────────────────────────────────────────────────
 
@@ -266,14 +269,19 @@ export function debugCatch(e, context) {
   // Sampled-to-disk surface for post-mortem. Lazy-loaded so fs-less paths
   // don't pay the module cost; wrapped in try so sampler faults never crash
   // the caller (debugCatch is the error-handler-of-last-resort path).
+  //
+  // The data dir comes from lib/resolve-data-dir.mjs (imports: node:os, node:path) and
+  // NOT from schema.mjs's DB_DIR. This is the last-resort error path, so it must not
+  // inherit the DB layer's import graph: with schema.mjs unresolvable, the sampler wrote
+  // NOTHING — the trail meant to explain a broken install disappeared with it (verified
+  // by blocking the specifier; tests/debug-catch-sampler-deps.test.mjs). Resolving at
+  // call time also honours a data dir redirected after module load, which DB_DIR (a
+  // load-time constant) does not.
   if (process.env.CLAUDE_MEM_CATCH_SAMPLE) {
     (async () => {
       try {
-        const [{ maybeSampleError }, { DB_DIR }] = await Promise.all([
-          import('./lib/err-sampler.mjs'),
-          import('./schema.mjs'),
-        ]);
-        maybeSampleError(e, context, DB_DIR);
+        const { maybeSampleError } = await import('./lib/err-sampler.mjs');
+        maybeSampleError(e, context, resolveDataDir(process.env.CLAUDE_MEM_DIR));
       } catch { /* sampler dynamic-import fault must not propagate */ }
     })();
   }