claude-mem-lite 3.35.2 → 3.37.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.35.2",
+      "version": "3.37.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.35.2",
+  "version": "3.37.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/bash-utils.mjs

@@ -53,7 +53,13 @@ function isExcludedPath(p) {
  * @returns {{isError: boolean, isTest: boolean, isBuild: boolean, isGit: boolean, isDeploy: boolean, isSignificant: boolean}}
  */
 export function detectBashSignificance(input, response) {
-  const cmd = (input.command || '').toLowerCase();
+  // Coerce command to a string at the source. A malformed PostToolUse payload can
+  // hand us a non-string `command` (object/number); `(input.command||'').toLowerCase()`
+  // then threw, and this is called UNGUARDED in the hottest hook path (hook.mjs:309) —
+  // the throw propagated to main()'s exit(0), dropping the ENTIRE tool event (no episode
+  // entry, not even a pending file). A non-string command has nothing to analyze, so
+  // degrading to '' (no significance) is the correct, event-preserving fallback.
+  const cmd = (typeof input?.command === 'string' ? input.command : '').toLowerCase();
   // Skip error keyword matching only when the PRIMARY command is a read/search op (its
   // output naturally contains "error"-like keywords that aren't failures). Anchored on the
   // primary command — NOT "search verb appears anywhere" — so `npm run build 2>&1 | tail`

package/deep-search.mjs

@@ -454,12 +454,19 @@ export async function deepSearch(db, params, { llm, searchFn = defaultSearchFn,
     // it does on the single-query baseline path, so "never worse than baseline"
     // holds in the error dimension too — a DB failure must not be silently
     // swallowed into an empty result (F5). Only rewrite variants are best-effort.
-    if (i === 0) return searchFn(db, v, params) || [];
-    try {
-      return searchFn(db, v, params) || [];
-    } catch {
-      return [];
-    }
+    let list;
+    if (i === 0) list = searchFn(db, v, params) || [];
+    else { try { list = searchFn(db, v, params) || []; } catch { list = []; } }
+    // rrfFuseN fuses by array index as rank, so each list MUST already be in
+    // composite-score order. searchObservationsHybrid appends downweighted
+    // concept(×0.7)/PRF(×0.6) expansion rows to the TAIL unsorted and, on the
+    // vectors-disabled path, returns BEFORE the sort its vector arm applies
+    // (search-engine.mjs:430) — so a sparse variant (common in deep search, the
+    // vocabulary-mismatch path) would hand a tail-ranked expansion row to RRF at a
+    // worse rank than its score earns. Sort so index == composite rank, mirroring
+    // the in-engine sort that already guards the vector-RRF merge.
+    list.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+    return list;
   });
 
   const fused = rrfFuseN(lists, rrfK);

package/format-utils.mjs

@@ -74,10 +74,14 @@ export function neutralizeContextDelimiters(s) {
 export function formatErrorRecallHints(rows) {
   if (!rows || rows.length === 0) return '';
   const lines = rows.map((r, i) => {
-    const head = `  #${r.id} [${r.type}] ${truncate(r.title, 60)}`;
+    // Defang title + lesson: this block is written to PostToolUse stdout \u2192 model context,
+    // and observations are stored raw (defense is at the injection boundary, not at save),
+    // so a poisoned lesson carrying a forged <system-reminder>/tool tag would inject here
+    // un-neutralized. Same guard the handoff render applies to its replayed fields.
+    const head = `  #${r.id} [${r.type}] ${neutralizeContextDelimiters(truncate(r.title, 60))}`;
     // Inline the lesson body for the single most-relevant hit only (bounded payload).
     if (i === 0 && typeof r.lesson_learned === 'string' && r.lesson_learned.trim()) {
-      return `${head} \u2014 ${truncate(r.lesson_learned.trim(), 200)}`;
+      return `${head} \u2014 ${neutralizeContextDelimiters(truncate(r.lesson_learned.trim(), 200))}`;
     }
     return head;
   });

package/haiku-client.mjs

@@ -421,9 +421,12 @@ function callModelCLI(prompt, model, { timeout }) {
     return text ? { text } : null;
   } catch (e) {
     const out = e.stdout?.toString?.()?.trim() || e.output?.[1]?.toString?.()?.trim();
-    if (out && out.startsWith('{') && out.endsWith('}')) {
-      try { JSON.parse(out); return { text: out }; } catch {}
-    }
+    // Salvage a complete JSON payload from partial stdout on timeout. Haiku almost
+    // always wraps JSON in ```json fences (#8605), so a raw brace check rejects a
+    // complete-but-fenced buffer and the already-emitted JSON is discarded.
+    // parseJsonFromLLM strips fences before validating; return the raw text (the
+    // caller re-parses it identically) only when JSON is actually recoverable.
+    if (out && parseJsonFromLLM(out) !== null) return { text: out };
     debugCatch(e, `${model}-cli`);
     return null;
   }
@@ -471,9 +474,11 @@ export function callModelCLIAsync(prompt, model, { timeout }) {
     const timer = setTimeout(() => {
       try { child.kill('SIGKILL'); } catch { /* already gone */ }
       const t = stdout.trim();
-      if (t.startsWith('{') && t.endsWith('}')) {
-        try { JSON.parse(t); done({ text: t }); return; } catch { /* not complete JSON */ }
-      }
+      // Salvage fenced-or-bare JSON from partial stdout (mirrors callModelCLI). A raw
+      // brace check would discard a complete-but-```json-fenced payload (#8605);
+      // parseJsonFromLLM strips fences before validating, and the caller re-parses
+      // the returned text the same way.
+      if (t && parseJsonFromLLM(t) !== null) { done({ text: t }); return; }
       done(null);
     }, timeout);
     child.stdout?.setEncoding('utf8'); // decode multi-byte UTF-8 (CJK) across chunk boundaries
@@ -609,11 +614,12 @@ function callHaikuCLI(prompt, { timeout }) {
     const text = result.trim();
     return text ? { text } : null;
   } catch (e) {
-    // Try to extract partial output on timeout — validate JSON before returning
+    // Try to extract partial output on timeout — validate via parseJsonFromLLM
+    // (strips ```json fences per #8605) before returning. A raw brace check would
+    // discard a complete-but-fenced payload the caller could still parse, throwing
+    // away the JSON Haiku already emitted.
     const out = e.stdout?.toString?.()?.trim() || e.output?.[1]?.toString?.()?.trim();
-    if (out && out.startsWith('{') && out.endsWith('}')) {
-      try { JSON.parse(out); return { text: out }; } catch {}
-    }
+    if (out && parseJsonFromLLM(out) !== null) return { text: out };
     debugCatch(e, 'haiku-cli');
     return null;
   }

package/hook-context.mjs

@@ -79,6 +79,11 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
     SELECT id, type, title, narrative, importance, created_at_epoch, files_modified, lesson_learned
     FROM observations
     WHERE project = ? AND COALESCE(compressed_into, 0) = 0
+      -- superseded invisibility: auto-dedup (hook.mjs) sets superseded_at but leaves
+      -- compressed_into=0, so the compressed filter alone lets the hidden near-duplicate
+      -- resurface in the most-visible surface (injected every SessionStart). Sibling
+      -- keyObs already filters this; obsPool + fallbackObs must match.
+      AND superseded_at IS NULL
       AND ${notLowSignalTitleClause('')}
       AND (
         (created_at_epoch > ? AND importance >= 1)
@@ -116,7 +121,12 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
     const impBoost = 0.5 + 0.5 * (o.importance || 1);
     const lessonBoost = o.lesson_learned ? 1.3 : 1.0;
     const value = recency * typeQuality * impBoost * lessonBoost;
-    const cost = estimateTokens((o.title || '') + (o.narrative || ''));
+    // Cost = ONLY what is injected. The Recent table renders title-only (narrative is neither
+    // pushed nor emitted), so charging title+narrative made the budget measure ~5x the real
+    // injected size — it filled to ~44% of capacity and, worse, the √cost density term penalized
+    // long-narrative rows that cost nothing to inject. Title-only cost fills the budget with the
+    // rows actually shown and makes valueDensity = value per injected token.
+    const cost = estimateTokens(o.title || '');
     return { ...o, value, cost, valueDensity: cost > 0 ? value / Math.sqrt(cost) : 0 };
   });
 
@@ -294,6 +304,7 @@ export function buildSessionContextLines(db, project, now = new Date(), currentC
       SELECT id, type, title, project, created_at
       FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
+        AND superseded_at IS NULL
         AND (
           (created_at_epoch > ? AND importance >= 1)
           OR (created_at_epoch > ? AND importance >= 2)

package/hook-handoff.mjs

@@ -136,10 +136,13 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     try {
       const tasks = taskReaderModule.readProjectTasks({ projectPath: process.cwd() });
       if (tasks.length > 0) {
+        // Join with the ENTRY separator ('; '), NOT '\n': extractUnfinishedSummary
+        // and renderHandoffFromRow split pending work on UNFINISHED_ENTRY_SEP, so a
+        // '\n'-join collapsed the whole task list into one unreadable multi-line bullet.
         unfinished = tasks
           .slice(0, 5)
           .map(t => `[${t.status}] ${t.title}`)
-          .join('\n');
+          .join(UNFINISHED_ENTRY_SEP);
       }
     } catch { /* task reader is best-effort; never block handoff */ }
   }
@@ -227,7 +230,7 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     project, type, storedSessionId,
     truncate(safe.working_on, 1000),
     safe.completed,
-    safe.unfinished.length > 3000 ? safe.unfinished.slice(0, 2999) + '…' : safe.unfinished,
+    safe.unfinished.length > 3000 ? Array.from(safe.unfinished).slice(0, 2999).join('') + '…' : safe.unfinished,
     safeKeyFiles,
     safe.key_decisions,
     safe.match_keywords,
@@ -441,7 +444,10 @@ function renderHandoffFromRow(handoff, db, project) {
   if (handoff.key_files) {
     try {
       const files = JSON.parse(handoff.key_files);
-      if (files.length > 0) lines.push('## Key Files', files.map(f => basename(f)).join(', '), '');
+      // Defang basenames too: a filename on disk can contain a literal authority tag
+      // (Linux allows almost any char but '/'), and this is the one field in this block
+      // that was rendered raw while working_on/unfinished/key_decisions all neutralize.
+      if (files.length > 0) lines.push('## Key Files', neutralizeContextDelimiters(files.map(f => basename(f)).join(', ')), '');
     } catch {}
   }
   if (handoff.key_decisions) {

package/hook-llm.mjs

@@ -588,6 +588,58 @@ export function buildImmediateObservation(episode) {
   };
 }
 
+// ─── Haiku extraction recovery helpers ──────────────────────────────────────
+
+// Haiku's throwaway lesson sentinels + a min-length floor. A lesson equal to one
+// of these (case-insensitive) or shorter than 12 chars teaches a future session
+// nothing, so it is treated as "no lesson". Single source for the episode gate,
+// the P3 retry check, and the importance=0 discard guard (all three previously
+// duplicated the literal). Every sentinel is <12 chars, so the length floor
+// alone already excludes them — the set guards the exact-match cases.
+const LOW_SIGNAL_LESSON = new Set(['none', '', 'n/a', 'null', 'todo', 'tbd', 'na', '-', 'nothing', 'nil']);
+export function isLowSignalLesson(lesson) {
+  const t = typeof lesson === 'string' ? lesson.trim() : '';
+  return LOW_SIGNAL_LESSON.has(t.toLowerCase()) || t.length < 12;
+}
+
+// Haiku sometimes wraps the observation object in an envelope that
+// parseJsonFromLLM preserves verbatim (it strips ```json fences but does not
+// unwrap structure): a single-element array `[{...}]`, or a single object-valued
+// key such as `{"observation":{...}}`. Peel one such layer so the enrichment
+// fields (title / lesson_learned / narrative / facts) are reachable by the gate
+// in handleLLMEpisode. Returns the inner object, or `parsed` unchanged when it is
+// not a recognized envelope (incl. multi-element arrays — ambiguous, left for the
+// degraded fallback). Only unwraps when there is no usable top-level title, so a
+// legitimate `{title, ...}` observation is never disturbed.
+export function unwrapObservationEnvelope(parsed) {
+  if (Array.isArray(parsed)) {
+    const [only] = parsed;
+    return parsed.length === 1 && only && typeof only === 'object' && !Array.isArray(only) ? only : parsed;
+  }
+  if (parsed && typeof parsed === 'object' && typeof parsed.title !== 'string') {
+    const keys = Object.keys(parsed);
+    if (keys.length === 1) {
+      const inner = parsed[keys[0]];
+      if (inner && typeof inner === 'object' && !Array.isArray(inner)) return inner;
+    }
+  }
+  return parsed;
+}
+
+// True when a parsed Haiku object carries content worth preserving even if its
+// title is unusable: a substantive lesson (not a low-signal sentinel / too short),
+// a non-empty narrative, or >=1 non-empty fact. Gates the title-recovery path in
+// handleLLMEpisode so a genuinely empty parse still falls through to the
+// episode-inferred degraded observation (which classifies type/importance better
+// than a forced 'change' would).
+export function hasEnrichmentContent(parsed) {
+  if (!parsed || typeof parsed !== 'object') return false;
+  if (typeof parsed.lesson_learned === 'string' && !isLowSignalLesson(parsed.lesson_learned)) return true;
+  if (typeof parsed.narrative === 'string' && parsed.narrative.trim().length > 0) return true;
+  if (Array.isArray(parsed.facts) && parsed.facts.some(f => typeof f === 'string' && f.trim().length > 0)) return true;
+  return false;
+}
+
 // ─── Lesson retry prompt (P3) ───────────────────────────────────────────────
 
 /**
@@ -712,14 +764,36 @@ ${actionList}`;
       releaseLLMSlot();
     }
 
-    // Require a STRING title: a truthy non-string (LLM returned title as an array/number/
-    // object) would pass a bare `parsed.title` check, then crash truncate() downstream,
-    // aborting the worker before tmpFile cleanup (leak) and leaving the obs degraded.
-    if (parsed && typeof parsed.title === 'string' && parsed.title) {
+    // Recover from common Haiku envelope shapes before the title gate: a single-
+    // element array `[{...}]` or a single object-valued wrapper key
+    // `{"observation":{...}}`. parseJsonFromLLM strips fences but does NOT peel
+    // these, so the payload (title AND lesson) sits one level down. See
+    // unwrapObservationEnvelope.
+    if (parsed && typeof parsed === 'object') parsed = unwrapObservationEnvelope(parsed);
+
+    // Enter enrichment whenever Haiku returned a usable object — even if its TITLE
+    // is missing/empty/non-string. The gate was previously `typeof parsed.title ===
+    // 'string' && parsed.title` (guarding a truncate() crash on non-string titles),
+    // so a valid extraction with a bad title silently discarded Haiku's
+    // lesson_learned / narrative / facts: `obs` stayed undefined and control fell to
+    // the degraded fallback. Now, when there is substantive content but no usable
+    // title, degrade ONLY the title (buildDegradedTitle) and keep the lesson. A parse
+    // with neither a usable title nor content still falls through to
+    // buildImmediateObservation, which infers type/importance from the episode.
+    const titleUsable = parsed && typeof parsed.title === 'string' && !!parsed.title;
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && (titleUsable || hasEnrichmentContent(parsed))) {
+      // Synthesize a rule-based title when Haiku's is unusable (crash-safe, and the
+      // lesson survives). Only the title degrades; every other field is kept.
+      if (!titleUsable) parsed.title = buildDegradedTitle(episode);
       // Normalize narrative to a string too — same non-string crash risk in truncate().
       if (typeof parsed.narrative !== 'string') parsed.narrative = '';
-      // Discard if LLM judges observation has no learning value
-      if (parsed.importance === 0 || parsed.importance === '0') {
+      const rawLesson = typeof parsed.lesson_learned === 'string' ? parsed.lesson_learned.trim() : '';
+      // Discard if LLM judges observation has no learning value — UNLESS it co-emitted
+      // a substantive lesson. importance=0 + a real lesson is contradictory (Haiku
+      // flags "zero value" yet still teaches something); the lesson is the
+      // higher-value signal, so keep the row (importance clamps to >=1 downstream)
+      // rather than deleting it. Only the genuinely empty case is dropped.
+      if ((parsed.importance === 0 || parsed.importance === '0') && isLowSignalLesson(rawLesson)) {
         debugLog('DEBUG', 'llm-episode', `Discarded low-value observation: ${parsed.title}`);
         // If pre-saved, delete it too
         if (episode.savedId) {
@@ -740,9 +814,7 @@ ${actionList}`;
       // When filtered, downgrade importance to 0 so rule-based fallback in
       // hook.mjs:saveObservation writes the obs but hook queries (which all
       // require importance >= 1) ignore it.
-      const rawLesson = typeof parsed.lesson_learned === 'string' ? parsed.lesson_learned.trim() : '';
-      const lowSignalLesson = new Set(['none', '', 'n/a', 'null', 'todo', 'tbd', 'na', '-', 'nothing', 'nil']);
-      const isLessonLowSignal = lowSignalLesson.has(rawLesson.toLowerCase()) || rawLesson.length < 12;
+      const isLessonLowSignal = isLowSignalLesson(rawLesson);
       let lessonLearned = isLessonLowSignal ? null : rawLesson.slice(0, 500);
 
       // P3: for bugfix/decision, retry once with a lesson-focused prompt.
@@ -768,7 +840,7 @@ ${actionList}`;
           if (retryRaw) {
             const retry = parseJsonFromLLM(retryRaw);
             const retryLesson = typeof retry?.lesson === 'string' ? retry.lesson.trim() : '';
-            const retryIsLow = lowSignalLesson.has(retryLesson.toLowerCase()) || retryLesson.length < 12;
+            const retryIsLow = isLowSignalLesson(retryLesson);
             if (!retryIsLow) {
               lessonLearned = retryLesson.slice(0, 500);
               retryRecovered = true;
@@ -1044,7 +1116,28 @@ ${obsList}`;
       releaseLLMSlot();
     }
 
-    if (llmParsed && llmParsed.request) {
+    // Coerce a prose field to a string before scrub/bind. Haiku sometimes returns a LIST for
+    // completed/next_steps/remaining_items; binding a non-string straight to SQL throws
+    // ("Too many parameter values") out of this try/finally and drops the WHOLE summary incl.
+    // lessons + key_decisions. Join array items; non-strings → ''. (lessons/key_decisions are
+    // JSON.stringify'd separately below.)
+    const asText = v => Array.isArray(v)
+      ? v.filter(x => typeof x === 'string' && x.trim()).join('; ')
+      : (typeof v === 'string' ? v : '');
+
+    // Persist when ANY meaningful field is present — not just `request`. Gating on `request`
+    // alone dropped the whole INSERT/UPDATE (losing the session's highest-value fields:
+    // lessons + key_decisions) whenever Haiku returned an empty request string but a rich
+    // `{completed, lessons, key_decisions}` — a common degraded shape. Downstream tolerates an
+    // empty request: INSERT writes '' and the UPDATE COALESCE(NULLIF(?, ''), request) preserves
+    // the prior value. Use asText in the gate so a non-string / empty-array field can't falsely
+    // trigger it.
+    const hasSummaryContent = llmParsed && (
+      asText(llmParsed.request) || asText(llmParsed.completed) || asText(llmParsed.remaining_items) || asText(llmParsed.next_steps) ||
+      (Array.isArray(llmParsed.lessons) && llmParsed.lessons.length > 0) ||
+      (Array.isArray(llmParsed.key_decisions) && llmParsed.key_decisions.length > 0)
+    );
+    if (hasSummaryContent) {
       const now = new Date();
       const lessonsJson = Array.isArray(llmParsed.lessons) && llmParsed.lessons.length > 0
         ? JSON.stringify(llmParsed.lessons) : null;
@@ -1072,12 +1165,12 @@ ${obsList}`;
         // pre-scrub remains safer in principle but would diverge from the
         // merged INSERT contract.
         const safe = scrubRecord('session_summaries', {
-          request: llmParsed.request || '',
-          investigated: llmParsed.investigated || '',
-          learned: llmParsed.learned || '',
-          completed: llmParsed.completed || '',
-          next_steps: llmParsed.next_steps || '',
-          remaining_items: llmParsed.remaining_items || '',
+          request: asText(llmParsed.request),
+          investigated: asText(llmParsed.investigated),
+          learned: asText(llmParsed.learned),
+          completed: asText(llmParsed.completed),
+          next_steps: asText(llmParsed.next_steps),
+          remaining_items: asText(llmParsed.remaining_items),
           lessons: lessonsJson,
           key_decisions: decisionsJson,
         });
@@ -1105,12 +1198,12 @@ ${obsList}`;
         );
       } else {
         const safe = scrubRecord('session_summaries', {
-          request: llmParsed.request || '',
-          investigated: llmParsed.investigated || '',
-          learned: llmParsed.learned || '',
-          completed: llmParsed.completed || '',
-          next_steps: llmParsed.next_steps || '',
-          remaining_items: llmParsed.remaining_items || '',
+          request: asText(llmParsed.request),
+          investigated: asText(llmParsed.investigated),
+          learned: asText(llmParsed.learned),
+          completed: asText(llmParsed.completed),
+          next_steps: asText(llmParsed.next_steps),
+          remaining_items: asText(llmParsed.remaining_items),
           lessons: lessonsJson,
           key_decisions: decisionsJson,
         });

package/hook-memory.mjs

@@ -118,7 +118,12 @@ const STALE_OBS_THRESHOLD_MS = 30 * 86400000;
  * @returns {string} `- [type] title[ | Lesson: X] (#id)[ [verify-before-use]]`
  */
 export function formatMemoryLine(obs) {
-  const lessonTag = obs.lesson_learned ? ` | Lesson: ${obs.lesson_learned}` : '';
+  // truncate (not raw): caps the per-hit token cost (an unbounded lesson bloated every
+  // memory-context line) AND collapses newlines — a multi-line lesson pushed the trailing
+  // "(#NN)" onto a later physical line that failed the "- [" prefix gate in
+  // citation-tracker's UserPromptSubmit extractor, so the obs never entered the
+  // citation-decay denominator (its promote/demote loop was silently dead).
+  const lessonTag = obs.lesson_learned ? ` | Lesson: ${truncate(obs.lesson_learned, 200)}` : '';
   let staleHint = '';
   if (typeof obs.created_at_epoch === 'number'
     && Date.now() - obs.created_at_epoch > STALE_OBS_THRESHOLD_MS
@@ -310,7 +315,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     // Adaptive threshold: scales with corpus size to filter noise.
     // Each result must individually exceed the threshold (not just the top one).
     const obsCount = db.prepare(
-      'SELECT COUNT(*) as c FROM observations WHERE project = ? AND COALESCE(compressed_into, 0) = 0',
+      'SELECT COUNT(*) as c FROM observations WHERE project = ? AND COALESCE(compressed_into, 0) = 0 AND superseded_at IS NULL',
     ).get(project)?.c || 0;
     const { TINY, SMALL, MEDIUM, LARGE } = BM25_THRESHOLD;
     const threshold = obsCount < 5 ? TINY : obsCount < 100 ? SMALL : obsCount < 500 ? MEDIUM : LARGE;
@@ -422,6 +427,7 @@ export function selectImperativeLesson(db, userPrompt, project, excludeIds = [])
       FROM observations
       WHERE project = ?
         AND COALESCE(compressed_into, 0) = 0
+        AND superseded_at IS NULL
         AND COALESCE(importance, 1) >= 2
         AND lesson_learned IS NOT NULL
         AND TRIM(lesson_learned) != ''

package/hook-optimize.mjs

@@ -81,7 +81,7 @@ export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', proje
   const projectClause = project ? 'AND project = ?' : '';
   if (scope === 'wide') {
     const stmt = db.prepare(`
-      SELECT id, title, narrative, type, subtitle, concepts, facts, project
+      SELECT id, title, narrative, type, subtitle, concepts, facts, search_aliases, project
       FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
         AND superseded_at IS NULL
@@ -140,7 +140,13 @@ search_aliases: 2-6 alternative search terms (include CJK if applicable).`;
       const parsed = await callModelJSON(prompt, 'haiku', { timeout: 15000, maxTokens: 500 });
       if (!parsed || !parsed.title) { skipped++; continue; }
 
-      if (parsed.importance === 0 || parsed.importance === '0') {
+      // Auto-hide on importance:0 targets fully-degraded NARROW rows (this branch predates
+      // the wide-scope widening). A wide candidate has a substantive narrative (>100 chars)
+      // and a real bugfix/feature/decision type by construction, and COMPRESSED_AUTO(-1) is
+      // reachable by no auto-recovery pass — so one Haiku "importance 0" misjudgment would
+      // hide a real observation until manual surgery. In wide scope, fall through and let
+      // clampImportance floor it to 1 (kept visible, low-ranked) instead of hiding.
+      if ((parsed.importance === 0 || parsed.importance === '0') && scope !== 'wide') {
         db.prepare(`UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}, optimized_at = ? WHERE id = ?`)
           .run(Date.now(), cand.id);
         processed++;
@@ -150,8 +156,14 @@ search_aliases: 2-6 alternative search terms (include CJK if applicable).`;
       const type = validTypes.has(parsed.type) ? parsed.type : cand.type || 'change';
       const concepts = Array.isArray(parsed.concepts) ? parsed.concepts.slice(0, 10) : [];
       const facts = Array.isArray(parsed.facts) ? parsed.facts.slice(0, 10) : [];
-      const conceptsText = concepts.join(' ');
-      const factsText = facts.join(' ');
+      // Preserve-on-empty: wide-scope candidates can already carry concepts/facts/aliases
+      // (findReenrichCandidates requires only lesson_learned empty), so a partial re-enrich
+      // that returns a lesson but omits/empties these must NOT wipe them — the same UPDATE
+      // sets optimized_at, locking the row out of any future re-enrich (:88), so the loss is
+      // permanent. Keep the candidate's existing value when the LLM returned nothing. (Narrow
+      // candidates are all-null on these by their WHERE, so cand.* is falsy → no-op there.)
+      const conceptsText = concepts.length ? concepts.join(' ') : (cand.concepts || '');
+      const factsText = facts.length ? facts.join(' ') : (cand.facts || '');
       // Scrub BEFORE truncate so a secret straddling the cut can't leave a sub-6-char
       // head that scrubSecrets's value-length floor no longer matches (the scrubRecord
       // below would then miss it too). Mirrors the hook-llm save-path fix.
@@ -159,8 +171,8 @@ search_aliases: 2-6 alternative search terms (include CJK if applicable).`;
         && parsed.lesson_learned.toLowerCase() !== 'none'
         && parsed.lesson_learned.trim().length > 0
         ? scrubSecrets(parsed.lesson_learned).slice(0, 500) : null;
-      const searchAliases = Array.isArray(parsed.search_aliases)
-        ? parsed.search_aliases.slice(0, 6).join(' ') : null;
+      const searchAliases = Array.isArray(parsed.search_aliases) && parsed.search_aliases.length
+        ? parsed.search_aliases.slice(0, 6).join(' ') : (cand.search_aliases || null);
       const title = truncate(scrubSecrets(parsed.title || ''), 120);
       const narrative = truncate(scrubSecrets(parsed.narrative || cand.narrative || ''), 500);
       const importance = clampImportance(parsed.importance);
@@ -361,9 +373,10 @@ export function findMergeCandidates(db, maxClusters = 5, { project } = {}) {
   const cutoff = Date.now() - MERGE_TIME_WINDOW_MS;
   const projectClause = project ? 'AND project = ?' : '';
   const stmt = db.prepare(`
-    SELECT id, title, narrative, project, type, access_count, importance, created_at_epoch, minhash_sig
+    SELECT id, title, narrative, project, type, access_count, importance, created_at_epoch, minhash_sig, lesson_learned
     FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
+      AND superseded_at IS NULL
       AND optimized_at IS NULL
       AND title IS NOT NULL AND title != ''
       AND created_at_epoch > ?
@@ -453,9 +466,25 @@ Return ONLY valid JSON:
     // already-scrubbed text so a straddling secret can't leak a sub-floor head.
     const title = truncate(scrubSecrets(parsed.merged_title || ''), 120);
     const narrative = truncate(scrubSecrets(parsed.merged_narrative || ''), 800);
-    const lessonLearned = typeof parsed.merged_lesson === 'string'
+    // Preserve-on-empty. The merge overwrites the keeper in place and hides every non-keeper
+    // member (compressed_into=keeper.id), so if the LLM returns merged_lesson:null (the prompt
+    // at :429 explicitly permits it) every cluster lesson would leave all live surfaces at once
+    // with no auto-recovery — the keeper snapshot and hidden members sit at compressed_into>0,
+    // which recoverBuriedLessons (compressed_into=0 only) skips. So use the LLM's synthesized
+    // lesson when non-empty, else fall back to the union of the members' own non-empty lessons.
+    // findMergeCandidates filters superseded_at IS NULL, so the union pulls only LIVE members
+    // (a tombstoned/retired lesson can't resurrect onto the keeper). The union is scrubbed then
+    // capped at 500 chars like a single lesson, so an unusually long union may truncate trailing
+    // members — still strictly better than the prior unconditional null (partial > total loss).
+    let lessonLearned = typeof parsed.merged_lesson === 'string'
       && parsed.merged_lesson.trim().length > 0
       ? scrubSecrets(parsed.merged_lesson).slice(0, 500) : null;
+    if (!lessonLearned) {
+      const memberLessons = [...new Set(cluster
+        .map(o => (o.lesson_learned || '').trim())
+        .filter(l => l && l.toLowerCase() !== 'none'))];
+      if (memberLessons.length) lessonLearned = scrubSecrets(memberLessons.join(' — ')).slice(0, 500);
+    }
 
     const bigramText = cjkBigrams((title || '') + ' ' + (narrative || ''));
     const textField = [conceptsText, factsText, bigramText].filter(Boolean).join(' ');
@@ -539,6 +568,14 @@ export function findSmartCompressCandidates(db, ageDays = 30, { project } = {})
     WHERE COALESCE(compressed_into, 0) = 0
       AND COALESCE(importance, 1) = 1
       AND COALESCE(access_count, 0) = 0
+      -- Never auto-compress a lesson-bearing row. Smart-compress sets compressed_into
+      -- on the originals (line ~693), which hides them from every injection/search
+      -- surface AND puts them out of recoverBuriedLessons' reach (it only lifts
+      -- compressed_into=0). A lesson demoted to imp=1 by citation-decay would be
+      -- silently buried by the unattended 24h llm-optimize run. Exact parity with the
+      -- canonical compress sibling selectCompressionCandidates (compress-core.mjs) —
+      -- "lessons never auto-GC" (also enforced in decayAndMarkIdle, maintain-core.mjs).
+      AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       AND created_at_epoch < ?
       ${projectClause}
     ORDER BY project, created_at_epoch

package/hook-shared.mjs

@@ -75,22 +75,35 @@ export const CONTINUE_KEYWORDS = /继续|接着|上次|之前的|前面的|刚
 // caller will ever pick up, so sweeping them on SessionStart is safe.
 export const ORPHAN_EPISODE_AGE_MS = 60 * 60 * 1000;
 
-// Sweep stale `ep-flush-*` and `pending-*` files in `runtimeDir` whose mtime
-// is older than `ageMs` (default 1h). Returns the number of files removed.
-// fs-only — no DB / no network. Used by handleSessionStart auto-maintain to
-// prevent the doctor "Stale temp files" warning from accumulating across
-// crashes; equivalent to the manual path in `node install.mjs cleanup` but
-// age-gated so concurrent in-flight workers are never raced.
-export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, now = Date.now() } = {}) {
+// `reads-<project>.txt` (bash fast-path Read tracker) is consumed by flushEpisode's
+// rename-collect on the next edit-flush, NOT by a background worker — so a project
+// that reads but never triggers an edit-flush leaves it uncollected and unswept, and
+// it grows without bound (the 1h episode threshold is far too eager: a long read-only
+// investigation legitimately appends to it for hours). A dedicated 24h floor sweeps
+// only genuinely-abandoned trackers (no append AND no flush in a day → its paths are
+// stale to any current episode) while leaving every active session's file untouched.
+export const ORPHAN_READS_AGE_MS = 24 * 60 * 60 * 1000;
+
+// Sweep stale `ep-flush-*` / `pending-*` (older than `ageMs`, default 1h) and
+// `reads-*.txt` (older than `readsAgeMs`, default 24h) files in `runtimeDir` by
+// mtime. Returns the number of files removed. fs-only — no DB / no network. Used by
+// handleSessionStart auto-maintain to prevent the doctor "Stale temp files" warning
+// from accumulating across crashes; equivalent to the manual path in
+// `node install.mjs cleanup` but age-gated so concurrent in-flight workers / active
+// read sessions are never raced.
+export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, readsAgeMs = ORPHAN_READS_AGE_MS, now = Date.now() } = {}) {
   let entries;
   try { entries = readdirSync(runtimeDir); } catch { return 0; }
   const cutoff = now - ageMs;
+  const readsCutoff = now - readsAgeMs;
   let count = 0;
   for (const f of entries) {
-    if (!(f.startsWith('ep-flush-') || f.startsWith('pending-'))) continue;
+    const isEpisode = f.startsWith('ep-flush-') || f.startsWith('pending-');
+    const isReads = f.startsWith('reads-') && f.endsWith('.txt');
+    if (!isEpisode && !isReads) continue;
     const full = join(runtimeDir, f);
     try {
-      if (statSync(full).mtimeMs < cutoff) {
+      if (statSync(full).mtimeMs < (isReads ? readsCutoff : cutoff)) {
         unlinkSync(full);
         count++;
       }

package/hook-update.mjs

@@ -187,7 +187,7 @@ function shouldCheck(state) {
 
 // ── GitHub API ─────────────────────────────────────────────
 // Try releases/latest first, fallback to tags (some repos only use tags)
-async function fetchLatestRelease() {
+export async function fetchLatestRelease() {
   const headers = {
     'Accept': 'application/vnd.github+json',
     'User-Agent': 'claude-mem-lite-updater/1.0',
@@ -235,7 +235,10 @@ async function fetchWithTimeout(url, headers) {
   const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   try {
     const res = await fetch(url, { signal: controller.signal, headers });
-    if (res.status === 403) {
+    if (res.status === 403 || res.status === 429) {
+      // 429 = GitHub secondary rate limit (403 = primary). Both must route to the 6h
+      // rate-limit backoff, not the 24h transient-failure path — else a 429 defers the
+      // next check a full day instead of retrying on the shorter rate-limit cadence.
       const state = readState();
       saveState({ ...state, rateLimited: true });
       debugLog('DEBUG', 'hook-update', 'GitHub API rate limited; will retry on the 6h rate-limit cadence');