claude-mem-lite 3.75.0 → 3.76.0

package/.claude-plugin/marketplace.json

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

@@ -159,7 +159,7 @@ PreToolUse hook 在你 Read / Edit / Write 文件前已自动 \`mem_recall\` 该
 | 改某条 | \`${CLI_INVOKE} update <id> [--lesson "<≤500>"] [--title T] [--type T] [--importance 1-3] [--narrative T] [--concepts "a b c"]\` |
 | 事件日志 | \`${CLI_INVOKE} activity save --type <bugfix\\|lesson\\|bug\\|discovery\\|refactor\\|feature\\|observation\\|decision> "<title>" [--body T] [--files f1,f2]\` |
 
-\`maintain\` / \`optimize\` / \`compress\` 见上方「维护 / 管理类工具」；\`maintain --ops\` 取值 \`cleanup,decay,boost,demote_pinned,dedup,purge_stale,rebuild_vectors,vacuum\`，\`--retain-days\` ∈ [7,365]。
+\`maintain\` / \`optimize\` / \`compress\` 见上方「维护 / 管理类工具」；\`maintain --ops\` 取值 \`cleanup,decay,boost,demote_pinned,dedup,purge_stale,rebuild_vectors,vacuum\`，省略时默认 \`cleanup,decay,boost,demote_pinned\`（顺序有意义：demote_pinned 必须在 boost 之后）；\`--retain-days\` ∈ [7,365]。
 
 ## 卸载 / 关闭
 

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';
@@ -50,7 +50,7 @@ import { formatHookError } from './lib/native-binding-hint.mjs';
 import { recordHookError } from './lib/hook-telemetry.mjs';
 import { queueHookContext, queueHookSystemMessage, flushHookStdout } from './lib/hook-stdout.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
-import { cleanupBroken, decayAndMarkIdle, boostAccessed, markAutoCompressible, selectFuzzyDedupeIds, stampDedupSuperseded, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
+import { cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, resolveDefaultMaintainOps, markAutoCompressible, selectFuzzyDedupeIds, stampDedupSuperseded, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
@@ -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`);
@@ -1073,6 +1122,36 @@ function runSessionStartAutoMaintain(db, project) {
         }
       }
 
+      // v3.76.0: the automatic path used to promote and never demote. boostAccessed ran
+      // above; demotePinned was not even imported here, and it sat outside the default op
+      // set of the CLI and MCP faces too — so the only op that can reach a
+      // heavily-injected-but-uncited row (regular decay deliberately protects
+      // injection_count>0) ran solely when a human typed `--ops demote_pinned`. Measured
+      // on the maintainer's live DB before the fix: 148 rows demoted by citation decay,
+      // never cited, and back at importance>=3, 148/148 of them boost-eligible.
+      //
+      // Placed AFTER boost, for the obvious reason: boostAccessed lifts any
+      // access_count>3 row with importance<3, so demoting first hands the row straight
+      // back at 2 (mem-cli had exactly that order and silently undid its own demotion
+      // inside a single run).
+      //
+      // Placed AFTER fuzzy dedup, for a less obvious one, found by pre-tag review: the
+      // dedup block above re-SELECTs `importance` and selectFuzzyDedupeIds keeps the
+      // higher-importance member of a near-duplicate pair. Demoting first inverted that
+      // rule using a value rewritten 40 lines earlier in the same pass — the pinned row
+      // lost and was tombstoned, keeping the copy WITHOUT the injection history. Dedup
+      // now decides on pre-demotion importance. Nothing between boost and here reads
+      // importance, so the move is free.
+      //
+      // Whole-DB mctx (projectFilter ''), so unlike markAutoCompressibleIfDue this needs
+      // NO per-project gate: one run under the global 24h gate covers every project at
+      // once. Do not "fix" it into a per-project gate — that is the v3.75.0 regression in
+      // reverse.
+      const demotedPinned = resolveDefaultMaintainOps().includes('demote_pinned')
+        ? demotePinned(db, mctx)
+        : 0;
+      if (demotedPinned > 0) debugLog('DEBUG', 'auto-maintain', `demoted ${demotedPinned} pinned-but-uncited observations (no lesson → 1, lesson → 2)`);
+
       // Orphan sweep: remove `ep-flush-*` / `pending-*` runtime files older
       // than 1h. handleLLMEpisode normally unlinks its own tmpFile on every
       // exit path, but a crashed worker (OOM, host reboot, kill -9) leaves
@@ -1112,11 +1191,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/maintain-core.mjs

@@ -30,6 +30,45 @@ export const MINHASH_PRE_THRESHOLD = MINHASH_PRE_THRESHOLD_SRC;
 // the regular decay op can't touch (decay protects injection_count>0).
 export const PINNED_INJ_THRESHOLD = 8;
 
+// Single home for the default maintenance op set AND its order.
+//
+// Three faces run maintenance — hook.mjs auto-maintain, CLI `maintain execute`,
+// MCP `mem_maintain` — and each used to hand-list its own default set. They had
+// drifted in both ways a hand-copied list can:
+//   - `demote_pinned` was in NOBODY's default set, and hook.mjs did not even
+//     import demotePinned. Its opponent `boostAccessed` was in all three. So the
+//     automatic path promoted and never demoted: measured on the maintainer's live
+//     DB, 148 rows sat demoted-by-citation-decay, never cited, and back at
+//     importance>=3 — 148/148 of them boostAccessed-eligible (access_count>3).
+//   - the two faces that DID wire the op ran it in opposite orders: mem-cli did
+//     demote-then-boost, which hands the row straight back (importance 1 → 2);
+//     server.mjs did boost-then-demote, which lands it at 1.
+// Hence: order matters, and `demote_pinned` MUST come after `boost`.
+export const DEFAULT_MAINTAIN_OPS = Object.freeze(['cleanup', 'decay', 'boost', 'demote_pinned']);
+
+// Opt-out for the v3.76.0 default change. Scoped to the DEFAULT set ONLY — an
+// explicit `--ops demote_pinned` / `operations:["demote_pinned"]` still runs. An
+// accepted value that silently means something else is worse than an unsupported
+// one (cf. CLAUDE_MEM_RECOMMEND_MODE=live, which parses and then does not do what
+// it says).
+// The first cut of this compared `=== '1'`, which silently ignored `=true` / `=yes` /
+// `= 1` — precisely the failure mode the comment above warns about, committed three
+// lines under it. Sibling skip-flags in this repo are bare truthiness checks
+// (`if (!process.env.CLAUDE_MEM_SKIP_COMPRESS)`), so any non-empty value opts out;
+// the falsey WORDS are honoured too, because `=0` or `=false` reading as "skip" is the
+// same class of silent surprise in the other direction.
+function envFlagEnabled(raw) {
+  if (raw === undefined || raw === null) return false;
+  const v = String(raw).trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
+
+export function resolveDefaultMaintainOps(env = process.env) {
+  return envFlagEnabled(env?.CLAUDE_MEM_SKIP_DEMOTE_PINNED)
+    ? DEFAULT_MAINTAIN_OPS.filter((op) => op !== 'demote_pinned')
+    : [...DEFAULT_MAINTAIN_OPS];
+}
+
 // Two trimmed bodies count as "the same body" when both are empty (a genuine
 // no-body re-save) or their word-set Jaccard clears the floor. One-empty-one-not
 // is treated as DISTINCT so a body-bearing observation is never hidden by a
@@ -158,10 +197,23 @@ export function markAutoCompressible(db, project, {
   // The write-side capNoiseImportance already forces imp=1 on these; this only shrinks GC
   // latency so the corpus reduction materializes within a week instead of bleeding into
   // the 30-day tier.
+  //
+  // v3.76.0: `injection_count = 0` added here to match the aged pass above, which has
+  // carried it since v2.56.0. Until this release nothing could reach BOTH `importance<=1`
+  // and `injection_count>=1`, so the omission was unobservable; `demote_pinned` joining
+  // the default op set creates exactly that population. Without this clause a demoted row
+  // could be marked COMPRESSED_AUTO on the NEXT maintain run — hidden from every
+  // `COALESCE(compressed_into,0)=0` read path, therefore never injected, therefore never
+  // cited, therefore with no path back. Pre-tag review reproduced that chain end to end.
+  // Today the two passes are also protected by an interlock — the title patterns below
+  // are the same set `notLowSignalTitleClause` (lib/low-signal-patterns.mjs) keeps off the
+  // only surfaces that bump `injection_count` — but that is two hand-listed sets in two
+  // files agreeing by maintenance, which is not a guarantee. This clause is.
   const noise = db.prepare(`
     UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}
     WHERE COALESCE(compressed_into, 0) = 0
       AND COALESCE(importance, 1) <= 1
+      AND COALESCE(injection_count, 0) = 0
       AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       AND (facts IS NULL OR facts = '' OR facts = '[]')
       AND (
@@ -340,21 +392,44 @@ export function boostAccessed(db, { projectFilter, baseParams, opCap = OP_CAP })
   `).run(...baseParams).changes;
 }
 
+// Every other automatic pass in this file carries this clause verbatim (lines 179, 192,
+// 299, 334) — a lesson is the distilled value a lessons store exists to hold, and
+// background machinery must not quietly dispose of one.
+const NO_LESSON_SQL = "(lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')";
+
 /**
  * Repair the citation-decay blind spot: heavy-injection + zero-citation rows that
- * decay protects (injection_count>0) stay pinned at max importance forever. Drop
- * them to importance 1 in one pass (injection priority is binary at >=2, so a
- * single step would not de-rank). Floor 1, not purge.
+ * decay protects (injection_count>0) stay pinned at max importance forever. Floor
+ * them; never purge.
+ *
+ * TWO floors, and the asymmetry is the point. `importance >= 2` is a hard WHERE on the
+ * injection faces that actually earn citations — pre-tool-recall
+ * (scripts/pre-tool-recall.js:428,470), SessionStart Key Context (hook-context.mjs:95,315)
+ * and cross-project (hook-memory.mjs:280) — whereas `injection_count`, the signal that
+ * triggers this op at all, is incremented ONLY on the two UserPromptSubmit faces
+ * (hook-memory.mjs:367, scripts/user-prompt-search.js:979). Those are the weakest faces
+ * by measured cite-rate. Dropping straight to 1 therefore convicts a row on its weakest
+ * surface and evicts it from its strongest — which pre-tag review caught: on the
+ * maintainer's live DB, 16 of the 17 rows this op would have moved were lesson-bearing.
+ *
+ *   no lesson -> 1  (fully de-ranked; the original behaviour, unchanged)
+ *   lesson    -> 2  (loses the top tier and its ranking weight, keeps eligibility on
+ *                    every importance>=2 face)
+ *
+ * The floor doubles as the WHERE bound so a row already sitting at its floor is not
+ * re-touched: SQLite counts a same-value UPDATE in `changes`, which would otherwise
+ * report phantom demotions on every run forever.
  */
 export function demotePinned(db, { projectFilter, baseParams, opCap = OP_CAP }) {
+  const floor = `(CASE WHEN ${NO_LESSON_SQL} THEN 1 ELSE 2 END)`;
   return db.prepare(`
-    UPDATE observations SET importance = 1
+    UPDATE observations SET importance = ${floor}
     WHERE id IN (
       SELECT id FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
         AND COALESCE(injection_count, 0) >= ${PINNED_INJ_THRESHOLD}
         AND COALESCE(cited_count, 0) = 0
-        AND COALESCE(importance, 1) > 1
+        AND COALESCE(importance, 1) > ${floor}
         ${projectFilter} LIMIT ${opCap}
     )
   `).run(...baseParams).changes;

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

@@ -30,7 +30,7 @@ import {
   recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   hardDeleteCandidateCount,
-  OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD,
+  OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD, resolveDefaultMaintainOps,
 } from './lib/maintain-core.mjs';
 import { snapshotDb, listSnapshots, backupBudgetBytes } from './lib/db-backup.mjs';
 import { deleteObservations, previewDeleteRows } from './lib/delete-core.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 {
@@ -2011,7 +2012,7 @@ function cmdMaintain(db, args) {
     out(`  Stale (>30d, imp=1, no access, never injected): ${stats.stale}`);
     out(`  Broken (no title/narrative): ${stats.broken}`);
     out(`  Boostable (accessed>3, imp<3): ${stats.boostable}`);
-    out(`  Pinned-but-uncited (inj>=${PINNED_INJ_THRESHOLD}, cited=0, imp>1): ${stats.pinned} — run: maintain execute --ops demote_pinned`);
+    out(`  Pinned-but-uncited (inj>=${PINNED_INJ_THRESHOLD}, cited=0, imp>1): ${stats.pinned} — cleared by the default maintain set since v3.76.0 (opt out: CLAUDE_MEM_SKIP_DEMOTE_PINNED=1)`);
     out(formatPendingPurgeLine(stats.pendingPurge));
     if (duplicates.length > 0) {
       const autoMergeable = duplicates.filter(d => parseFloat(d.similarity) >= AUTO_MERGE_THRESHOLD);
@@ -2046,9 +2047,11 @@ function cmdMaintain(db, args) {
   const VALID_OPS = ['cleanup', 'decay', 'boost', 'demote_pinned', 'dedup', 'purge_stale', 'rebuild_vectors', 'vacuum'];
   // Distinguish flag-absent (use default op set) from flag-present-but-empty
   // (`--ops ""`, e.g. an unset shell var). The latter previously coerced via `||`
-  // to the destructive default cleanup,decay,boost and EXECUTED it; route it to the
-  // VALID_OPS check below instead so it's rejected like `--ops " "` / `--ops "decay,"`.
-  const opsStr = flags.ops === undefined ? 'cleanup,decay,boost' : String(flags.ops);
+  // to the destructive default set and EXECUTED it; route it to the VALID_OPS check
+  // below instead so it's rejected like `--ops " "` / `--ops "decay,"`. (That default
+  // was the literal `cleanup,decay,boost` when this was written; it now comes from
+  // DEFAULT_MAINTAIN_OPS, which is why the list is no longer spelled out here.)
+  const opsStr = flags.ops === undefined ? resolveDefaultMaintainOps().join(',') : String(flags.ops);
   const ops = opsStr.split(',').map(s => s.trim());
   const invalidOps = ops.filter(op => !VALID_OPS.includes(op));
   if (invalidOps.length > 0) {
@@ -2137,17 +2140,23 @@ function cmdMaintain(db, args) {
       results.push(`Decayed ${decayed} stale observations, marked ${idleMarked} idle as pending-purge${decayCap}`);
     }
 
+    if (ops.includes('boost')) {
+      const boosted = boostAccessed(db, mctx);
+      results.push(`Boosted ${boosted} frequently-accessed observations${capHint(boosted)}`);
+    }
+
+    // AFTER boost, matching server.mjs and hook.mjs. This block used to sit BEFORE
+    // it, and the order was load-bearing in the wrong direction: boostAccessed lifts
+    // any access_count>3 row with importance<3, so demoting a pinned row to 1 and
+    // then boosting handed it straight back at 2 — the demotion silently undone
+    // inside a single maintain run. DEFAULT_MAINTAIN_OPS pins the order; this block
+    // has to physically follow the boost block for that order to be real.
     if (ops.includes('demote_pinned')) {
       // Repair the citation-decay blind spot: decay protects injection_count>0, so a
       // heavily-injected-but-uncited memory stays pinned at max importance forever.
       // demotePinned (maintain-core) drops it to 1 in one pass. Floor 1, not purge.
       const demoted = demotePinned(db, mctx);
-      results.push(`Demoted ${demoted} pinned-but-uncited observations to importance 1 (inj>=${PINNED_INJ_THRESHOLD}, cited=0)${capHint(demoted)}`);
-    }
-
-    if (ops.includes('boost')) {
-      const boosted = boostAccessed(db, mctx);
-      results.push(`Boosted ${boosted} frequently-accessed observations${capHint(boosted)}`);
+      results.push(`Demoted ${demoted} pinned-but-uncited observations (inj>=${PINNED_INJ_THRESHOLD}, cited=0; no lesson → importance 1, lesson → 2)${capHint(demoted)}`);
     }
 
     if (ops.includes('dedup') && flags['merge-ids']) {
@@ -2783,10 +2792,15 @@ Commands:
 
   maintain <scan|execute>  Memory maintenance
     --ops O             Comma-separated: cleanup,decay,boost,demote_pinned,dedup,purge_stale,rebuild_vectors,vacuum
+                        Default when omitted: cleanup,decay,boost,demote_pinned (in that order)
     --merge-ids K:R,... For dedup: keepId:removeId pairs (e.g. 10:11,20:21:22)
     --project P         Filter by project
     --retain-days N     For purge_stale: keep last N days (default 30)
-                        demote_pinned: importance→1 for inj>=8 & cited=0 (clears pinned noise)
+                        demote_pinned: importance→1 for inj>=8 & cited=0 (clears pinned noise).
+                        In the default set since v3.76.0; runs AFTER boost, which would
+                        otherwise hand the row straight back. Opt out of the DEFAULT with
+                        CLAUDE_MEM_SKIP_DEMOTE_PINNED=1 — an explicit --ops demote_pinned
+                        still runs.
                         vacuum: reclaim freelist dead space (whole-DB, ignores --project)
 
   optimize              LLM-powered memory optimization (preview by default)
@@ -2806,6 +2820,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 +2858,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.76.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.75.0",
+      "version": "3.76.0",
       "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.76.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",
@@ -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/launch.mjs

@@ -42,8 +42,15 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
     //
     // `e.status` not `e.code`: execSync failures carry the exit status on `status`,
     // so the old `|| e.code` rung was dead.
+    // `?? null` not `!= null`: the loose form is the idiom, but this file is
+    // linted under `eqeqeq: always`, and rewriting it as `!== undefined` would
+    // be a BEHAVIOUR change — execSync reports a signal kill with `status: null`,
+    // which `!== undefined` accepts and would render as "npm exited null".
+    // Coalescing first keeps the original both-nullish semantics exactly, `0`
+    // included.
+    const status = e?.status ?? null;
     const detail = e?.message?.split('\n')[0]
-      || (e?.status != null ? `npm exited ${e.status}` : '')
+      || (status !== null ? `npm exited ${status}` : '')
       || (e?.signal ? `npm killed by ${e.signal}` : '')
       || 'unknown error';
     process.stderr.write(`[claude-mem-lite] npm install failed in ${ROOT} — ${detail}\n`);

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/server.mjs

@@ -19,7 +19,7 @@ import {
   recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   hardDeleteCandidateCount,
-  OP_CAP, STALE_AGE_MS,
+  OP_CAP, STALE_AGE_MS, resolveDefaultMaintainOps,
 } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import { deleteObservations, previewDeleteRows } from './lib/delete-core.mjs';
@@ -1148,7 +1148,7 @@ server.registerTool(
     if (action === 'execute') {
       const ops = args.operations && args.operations.length > 0
         ? args.operations
-        : ['cleanup', 'decay', 'boost'];
+        : resolveDefaultMaintainOps();
       // T2-P1-A: reject explicit empty array (vs. omitted → defaults above). Empty-array
       // callers are almost always mistakes; silently running only FTS5 optimize hides the error.
       if (args.operations && args.operations.length === 0) {
@@ -1239,7 +1239,7 @@ server.registerTool(
 
         if (ops.includes('demote_pinned')) {
           const demoted = demotePinned(db, mctx);
-          results.push(`Demoted ${demoted} pinned-but-uncited observations to importance 1 (inj>=8, cited=0)` + (demoted >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
+          results.push(`Demoted ${demoted} pinned-but-uncited observations (inj>=8, cited=0; no lesson → importance 1, lesson → 2)` + (demoted >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
         }
 
         if (ops.includes('dedup') && args.merge_ids) {

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/tool-schemas.mjs

@@ -247,7 +247,7 @@ export const memOptimizeSchema = {
 export const memMaintainSchema = {
   action: z.enum(['scan', 'execute']).describe('scan=analyze candidates, execute=apply changes'),
   operations: z.array(z.enum(['dedup', 'decay', 'cleanup', 'boost', 'demote_pinned', 'purge_stale', 'rebuild_vectors', 'vacuum'])).optional()
-    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, demote_pinned=importance→1 for obs injected>=8 times but never cited (clears pinned noise the decay op cannot reach), purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors, vacuum=reclaim freelist dead space (whole-DB)'),
+    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, demote_pinned=importance→1 for obs injected>=8 times but never cited (clears pinned noise the decay op cannot reach; in the default set since v3.76.0 and ordered after boost, since boost would otherwise raise the row straight back — set CLAUDE_MEM_SKIP_DEMOTE_PINNED=1 to drop it from the DEFAULT set only), purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors, vacuum=reclaim freelist dead space (whole-DB)'),
   merge_ids: z.preprocess(
     (v) => Array.isArray(v) ? v.map(g => Array.isArray(g) ? g.map(x => typeof x === 'string' ? parseInt(x, 10) : x) : g) : v,
     z.array(z.array(z.number().int()).min(2))

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 */ }
     })();
   }