claude-mem-lite 3.21.0 → 3.23.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.21.0",
+      "version": "3.23.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.21.0",
+  "version": "3.23.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

@@ -13,6 +13,16 @@ const CMD_WRAPPERS = new Set(['sudo', 'doas', 'env', 'time', 'command', 'nice',
 // git read subcommands whose output contains commit/log/match text, not failures.
 const GIT_READ_SUBCMDS = new Set(['grep', 'log', 'show', 'diff', 'blame', 'ls-files', 'cat-file', 'whatchanged', 'shortlog', 'reflog', 'status']);
 
+// Hard failure fingerprints — a real crash / thrown exception / non-zero-exit marker,
+// as opposed to output that merely CONTAINS the word "error" (search results, log
+// scans, prose). Deliberately strong/narrow: a JS stack frame (`\n   at fn (…)`),
+// panic/traceback/segfault, ENOENT/command-not-found, AssertionError, or a *named*
+// error class (TypeError:/ReferenceError:/…). Generic `Error:`/`exception` are
+// intentionally excluded — they appear too often in benign search/log output. Gates
+// the bugfix-shape save-nudge (lib/cite-back-hint.mjs) so `node cli.mjs search "error"`
+// + an edit in the same episode no longer looks like an unsaved fix.
+const HARD_ERROR_RE = /\bERR!|\bpanic\b|traceback|segfault|core dumped|\benoent\b|command not found|assertion\s?error|\n\s+at\s+\S|(?:type|reference|range|syntax|eval|uri)error:/i;
+
 // True when the command's PRIMARY operation (left of the first pipe, past any
 // env-assignments / wrapper like `sudo`/`env`/`time`) is a read/search — including
 // `git grep`/`git log`. Anchoring on the primary command (not "search verb appears
@@ -69,6 +79,10 @@ export function detectBashSignificance(input, response) {
   const hasHardErrorSignal = hasGreenTestSummary
     && /\bERR!|panic|traceback|enoent|command not found|exception|AssertionError|TypeError:|SyntaxError:/i.test(response);
   const isError = looksLikeError && !(hasGreenTestSummary && !hasHardErrorSignal);
+  // Strict subset of isError: a genuine failure fingerprint, not just the word "error"
+  // in benign output. Consumers that must avoid false positives (the bugfix-shape
+  // save-nudge) gate on this instead of isError.
+  const isHardError = isError && HARD_ERROR_RE.test(response);
   // Match actual test runner invocations, not commands that merely reference "test" as a keyword
   const isTest = /\b(npm\s+test|npm\s+run\s+test|yarn\s+test|pnpm\s+test|pnpm\s+run\s+test|bun\s+test|go\s+test|cargo\s+test)\b/i.test(cmd)
     || /\b(jest|pytest|vitest|mocha|cypress|playwright)\b/i.test(cmd);
@@ -85,7 +99,7 @@ export function detectBashSignificance(input, response) {
     || /\bgh\s+release\s+(?:create|edit|upload|delete)\b/i.test(cmd)
     || /\btwine\s+upload\b/i.test(cmd);
   return {
-    isError, isTest, isBuild, isGit, isDeploy,
+    isError, isHardError, isTest, isBuild, isGit, isDeploy,
     isSignificant: isError || isTest || isBuild || isGit || isDeploy,
   };
 }

package/cli/common.mjs

@@ -21,7 +21,19 @@ export function parseArgs(argv) {
   while (i < argv.length) {
     const arg = argv[i];
     if (arg.startsWith('--')) {
-      const key = arg.slice(2);
+      const body = arg.slice(2);
+      // `--key=value` (GNU long-option form). Split on the FIRST '=' so values that
+      // themselves contain '=' (e.g. `--from=2026-01-01`, a token with '=') stay intact.
+      // Without this, `--type=feature` parsed as a boolean flag literally named
+      // "type=feature"; the real `--type` stayed undefined and the default silently
+      // applied — a save landed in the wrong project / type with no error.
+      const eq = body.indexOf('=');
+      if (eq >= 0) {
+        flags[body.slice(0, eq)] = body.slice(eq + 1);
+        i++;
+        continue;
+      }
+      const key = body;
       const next = argv[i + 1];
       if (next !== undefined && !next.startsWith('--') && (!next.startsWith('-') || /^-\d/.test(next))) {
         flags[key] = next;

package/format-utils.mjs

@@ -24,6 +24,24 @@ export function truncate(str, max = 80) {
   return str.slice(0, end) + '\u2026';
 }
 
+// The block delimiters claude-mem-lite wraps injected context in. Any user-derived text
+// (observation title / lesson, handoff body) that contains one of these LITERALLY would
+// prematurely open or close the block it lands in, and the model then reads the rest as
+// undelimited context. Reachable by editing files that contain these tokens \u2014 e.g.
+// developing claude-mem-lite itself, where source/observations carry the delimiter names.
+const CONTEXT_DELIMITER_RE = /<\/?(?:claude-mem-context|memory-context|session-handoff)>/gi;
+
+/**
+ * Defang the literal context-block delimiter tags in user-derived text. Strips just the
+ * angle brackets, so `</claude-mem-context>` renders as `/claude-mem-context` \u2014 still
+ * readable, but no longer a structural delimiter. Complements `mdCell`'s pipe-escaping.
+ * @param {string} s Input string (any type; coerced)
+ * @returns {string} Text with delimiter tags defanged
+ */
+export function neutralizeContextDelimiters(s) {
+  return String(s ?? '').replace(CONTEXT_DELIMITER_RE, (m) => m.slice(1, -1));
+}
+
 /**
  * Render the PostToolUse error-recall hint block (hook.mjs::triggerErrorRecall).
  * The single most-relevant hit (rows[0]) that carries a lesson_learned gets its

package/hook-context.mjs

@@ -5,7 +5,7 @@ import { basename, join } from 'path';
 import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
 import {
   estimateTokens, truncate, typeIcon, fmtTime, inferProject,
-  debugLog, debugCatch,
+  debugLog, debugCatch, neutralizeContextDelimiters,
   DECAY_HALF_LIFE_BY_TYPE, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause,
 } from './utils.mjs';
 import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS, RUNTIME_DIR, effectiveQuiet } from './hook-shared.mjs';
@@ -462,7 +462,11 @@ export function buildSessionContextLines(db, project, now = new Date(), currentC
     }
   }
 
-  return [...summaryLines, ...handoffLines, ...deferredLines, ...obsLines].join('\n');
+  // Defang any literal block-delimiter tag carried in a title/lesson/summary so a row
+  // can't prematurely close the <claude-mem-context> block it's wrapped in (mdCell does
+  // the same for `|`). One source of truth: both the SessionStart hook and the CLI
+  // `context` command consume this return.
+  return neutralizeContextDelimiters([...summaryLines, ...handoffLines, ...deferredLines, ...obsLines].join('\n'));
 }
 
 /**

package/hook-handoff.mjs

@@ -2,7 +2,7 @@
 // Extracted for testability — hook.mjs has module-level side effects
 
 import { basename } from 'path';
-import { truncate, extractMatchKeywords, tokenizeHandoff, isSpecificTerm, scrubSecrets, LOW_SIGNAL_TITLE, EDIT_TOOLS, isMetaTriggerPrompt, notLowSignalTitleClause } from './utils.mjs';
+import { truncate, extractMatchKeywords, tokenizeHandoff, isSpecificTerm, scrubSecrets, LOW_SIGNAL_TITLE, EDIT_TOOLS, isMetaTriggerPrompt, notLowSignalTitleClause, neutralizeContextDelimiters } from './utils.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import {
   HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT, HANDOFF_ANCHOR_MAX_AGE,
@@ -418,11 +418,15 @@ function renderHandoffFromRow(handoff, db, project) {
     `<session-handoff source="${handoff.type}" age="${ageStr}" origin="hook-injected">`,
   ];
 
+  // Defang delimiter tags in the free-text fields ONLY — never the structural
+  // <session-handoff> tags in `lines`, or the block would lose its own framing. A
+  // user prompt or edit snippet carrying a literal </session-handoff> would otherwise
+  // close the block early and the rest would read as a real user message.
   if (handoff.working_on) {
-    lines.push('## Working On', handoff.working_on, '');
+    lines.push('## Working On', neutralizeContextDelimiters(handoff.working_on), '');
   }
   if (handoff.completed) {
-    lines.push('## Completed', ...handoff.completed.split('\n').map(l => `- ${l}`), '');
+    lines.push('## Completed', ...neutralizeContextDelimiters(handoff.completed).split('\n').map(l => `- ${l}`), '');
   }
   if (handoff.unfinished) {
     // Extract only the pending-work portion (before narrative history separator).
@@ -431,7 +435,7 @@ function renderHandoffFromRow(handoff, db, project) {
     // completeness claim the episode buffer can't support.
     const pending = extractUnfinishedSummary(handoff.unfinished);
     if (pending) {
-      lines.push('## Recent activity', ...pending.split('; ').map(l => `- ${l}`), '');
+      lines.push('## Recent activity', ...neutralizeContextDelimiters(pending).split('; ').map(l => `- ${l}`), '');
     }
   }
   if (handoff.key_files) {
@@ -441,7 +445,7 @@ function renderHandoffFromRow(handoff, db, project) {
     } catch {}
   }
   if (handoff.key_decisions) {
-    lines.push('## Key Decisions', ...handoff.key_decisions.split('\n').map(l => `- ${l}`), '');
+    lines.push('## Key Decisions', ...neutralizeContextDelimiters(handoff.key_decisions).split('\n').map(l => `- ${l}`), '');
   }
 
   lines.push('</session-handoff>');

package/hook-llm.mjs

@@ -803,9 +803,16 @@ ${actionList}`;
         // retry's entire purpose (a recovered bugfix lesson would silently drop
         // out of --importance 2 searches and the working tier). Gate the cap on
         // the *effective* low-signal state, not the pre-retry flag.
+        // v3.23: cap the FILE-PATH heuristic's contribution at 2. computeRuleImportance
+        // returns 3 for any entry touching schema./migration/prisma/.env/.key paths; via the
+        // Math.max below that force-promoted ordinary has-lesson episodes to "critical" imp=3
+        // even when Haiku judged them 1-2 (audit: auto imp=3 = 34.8%, e.g. a thin-lesson edit
+        // to schema.mjs). Haiku's OWN importance can still reach 3 (genuine judgment); only the
+        // path heuristic is capped. The isLessonLowSignal branch still floors no-lesson
+        // non-decision autos at ≤1; manual mem_save uses a different path and is unaffected.
         importance: isLessonLowSignal && !retryRecovered && parsed.type !== 'decision'
           ? Math.min(ruleImportance, 1)
-          : Math.max(ruleImportance, clampImportance(parsed.importance)),
+          : Math.max(Math.min(ruleImportance, 2), clampImportance(parsed.importance)),
         lessonLearned,
         searchAliases,
       };

package/hook-memory.mjs

@@ -1,7 +1,7 @@
 // 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 } from './utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters } from './utils.mjs';
 import { citeFactorJs } from './scoring-sql.mjs';
 import { recordMetric } from './lib/metrics.mjs';
 import { DB_DIR } from './schema.mjs';
@@ -123,7 +123,10 @@ export function formatMemoryLine(obs) {
     && hasFilePaths(obs.files_modified)) {
     staleHint = ' [verify-before-use]';
   }
-  return `- [${obs.type}] ${truncate(obs.title, 80)}${lessonTag} (#${obs.id})${staleHint}`;
+  // Defang any literal block-delimiter tag in title/lesson so it can't prematurely close
+  // the <memory-context> block this line is injected into (parity with hook-context's
+  // <claude-mem-context> defense).
+  return neutralizeContextDelimiters(`- [${obs.type}] ${truncate(obs.title, 80)}${lessonTag} (#${obs.id})${staleHint}`);
 }
 
 function hasFilePaths(filesModified) {

package/hook.mjs

@@ -39,6 +39,7 @@ import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
   RUNTIME_DIR, EPISODE_BUFFER_SIZE, EPISODE_TIME_GAP_MS,
   SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS,
+  HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT,
   sessionFile, getSessionId, createSessionId, openDb,
   spawnBackground, sweepOrphanEpisodeFiles,
 } from './hook-shared.mjs';
@@ -46,7 +47,7 @@ import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObse
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
-import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale } from './lib/maintain-core.mjs';
+import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
@@ -285,6 +286,9 @@ async function handlePostToolUse() {
     files,
     ts: Date.now(),
     isError: bashSig?.isError || false,
+    // isHardError gates the bugfix-shape save-nudge (lib/cite-back-hint.mjs): a real
+    // failure fingerprint, not just "error" appearing in search/log output.
+    isHardError: bashSig?.isHardError || false,
     isSignificant: EDIT_TOOLS.has(tool_name) ||
                    bashSig?.isSignificant || false,
     bashSig: bashSig || null,
@@ -696,16 +700,26 @@ function runSessionStartDbMutations(db, { sessionId, project, prevSessionId, now
       WHERE status = 'active' AND started_at_epoch < ?
     `).run(staleSessionCutoff);
 
-    // Auto-compress: mark old low-importance observations as compressed (30+ days, importance=1)
+    // Auto-compress: mark old low-importance observations as compressed (30+ days, importance<=1)
     // Lightweight: only marks rows, doesn't create summaries (full compression via mem_compress)
     // v2.56.0 #4: protect injection_count > 0 obs (proven contextually relevant
     // via hook-memory injection, even if user never explicitly fetched). Same
     // protection applied symmetrically in auto-maintain decay/mark-idle below.
+    // `<= 1` (was `= 1`): citation-decay floors importance at 0 (added v2.73.2, after this
+    // predicate was written) and the LLM low-signal filter saves at imp=0 — those rows are
+    // STRICTLY lower value than imp=1 yet escaped GC, accumulating to ~40% of a mature DB
+    // (immortal: hidden from injection by the imp>=1 floor, but visible as explicit-search noise).
     const compressed = db.prepare(`
       UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}
       WHERE COALESCE(compressed_into, 0) = 0
-        AND importance = 1
+        AND COALESCE(importance, 1) <= 1
         AND COALESCE(injection_count, 0) = 0
+        -- v3.23: never auto-hide a row that carries a real lesson. compression folds
+        -- sources into a title-only summary (lesson lost), and COMPRESSED_AUTO hides the
+        -- row from search entirely. A low-importance obs whose lesson_learned is the
+        -- distilled value must stay findable (audit: 62 lessons buried this way). The 7d
+        -- noise block below already excludes lessons; this 30d block had drifted.
+        AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
         AND created_at_epoch < ?
         AND project = ?
     `).run(autoCompressAge, project);
@@ -722,7 +736,7 @@ function runSessionStartDbMutations(db, { sessionId, project, prevSessionId, now
     const noiseCompressed = db.prepare(`
       UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}
       WHERE COALESCE(compressed_into, 0) = 0
-        AND importance = 1
+        AND COALESCE(importance, 1) <= 1
         AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
         AND (facts IS NULL OR facts = '' OR facts = '[]')
         AND (
@@ -774,6 +788,12 @@ function runSessionStartAutoMaintain(db) {
       const cleaned = cleanupBroken(db, mctx);
       if (cleaned > 0) debugLog('DEBUG', 'auto-maintain', `cleaned ${cleaned} broken observations`);
 
+      // Self-heal legacy orphans: children whose compression keeper was hard-deleted
+      // before recoverChildrenOf existed are hidden + queue-less (unreachable). Resurface
+      // them so normal decay/GC handles them on merit. Non-destructive (un-hide only).
+      const orphansRecovered = recoverOrphanedChildren(db, mctx);
+      if (orphansRecovered > 0) debugLog('DEBUG', 'auto-maintain', `recovered ${orphansRecovered} orphaned compression children`);
+
       const { decayed, idleMarked } = decayAndMarkIdle(db, mctx);
       if (decayed > 0) debugLog('DEBUG', 'auto-maintain', `decayed ${decayed} stale observations`);
       if (idleMarked > 0) debugLog('DEBUG', 'auto-maintain', `marked ${idleMarked} idle as pending-purge`);
@@ -848,6 +868,20 @@ function runSessionStartAutoMaintain(db) {
         if (swept > 0) debugLog('DEBUG', 'auto-maintain', `swept ${swept} orphan ep-flush/pending file(s)`);
       } catch (e) { debugCatch(e, 'auto-maintain-orphan-sweep'); }
 
+      // GC expired session_handoffs: the consume-DELETE (handleSessionStart) only removes
+      // the single handoff a continuation reads back; an 'exit'/'compact' that is never
+      // resumed (and every superseded 'clear') lingers forever — read paths filter by
+      // expiry but nothing reaped the rows. Delete past-expiry rows with a +1d margin so a
+      // still-readable handoff is never raced away. 'clear' 6h+1d, 'exit'/other 7d+1d.
+      try {
+        const gc = db.prepare(`
+          DELETE FROM session_handoffs
+          WHERE (type = 'clear' AND created_at_epoch < ?)
+             OR (type != 'clear' AND created_at_epoch < ?)
+        `).run(Date.now() - HANDOFF_EXPIRY_CLEAR - 86400000, Date.now() - HANDOFF_EXPIRY_EXIT - 86400000);
+        if (gc.changes > 0) debugLog('DEBUG', 'auto-maintain', `gc'd ${gc.changes} expired session_handoffs`);
+      } catch (e) { debugCatch(e, 'auto-maintain-handoff-gc'); }
+
       // Mark maintenance as done (24h gate) — even though compression runs in background
       writeFileSync(maintainFile, JSON.stringify({ epoch: Date.now() }));
       // Weekly summary grouping runs in background to avoid blocking SessionStart

package/lib/cite-back-hint.mjs

@@ -68,11 +68,17 @@ export function buildCiteBackHint(episode, cooldown) {
 // the lib so all save-prompt hints share one home + the same wording rules.
 //
 // Detection (mirrors pre-v2.83 hook.mjs:194 heuristic):
-//   • has at least one entry with isError=true
+//   • has at least one entry with a HARD failure fingerprint (isHardError) — NOT just
+//     isError. `node cli.mjs search "error"`, `npx vitest` green output, or any command
+//     whose output merely MENTIONS "error"/"failed" sets isError=true but is not a fix;
+//     gating on isError nagged on non-fixes (audit: fired on a read-only session + a
+//     scratch write). isHardError requires a real crash/exception/stack (bash-utils.mjs).
 //   • has at least one entry using an edit tool
 //   • entries.length >= 3 (rules out single-typo fixes that don't need a lesson)
 // Returns null when any condition fails or when no edited files are recoverable
 // from the entry list (defensive — episodes flushed mid-tool can have empties).
+// Legacy fallback: entries written before isHardError existed lack the field, so fall
+// back to isError for them rather than silently regress the nudge to never-fire.
 const MIN_BUGFIX_ENTRIES = 3;
 const MAX_DISPLAY_FILES = 3;
 
@@ -86,7 +92,7 @@ export function buildUnsavedBugfixHint(episode) {
   const editedFiles = new Set();
   for (const e of entries) {
     if (!e) continue;
-    if (e.isError) hasError = true;
+    if (e.isHardError !== undefined ? e.isHardError : e.isError) hasError = true;
     if (EDIT_TOOLS.has(e.tool)) {
       hasEdit = true;
       for (const f of e.files || []) editedFiles.add(f);

package/lib/compress-core.mjs

@@ -22,9 +22,12 @@ import { getVocabulary, computeVector } from '../tfidf.mjs';
 import { scrubRecord } from './scrub-record.mjs';
 
 /**
- * Low-value compression candidates: importance=1, never accessed, older than
+ * Low-value compression candidates: importance<=1, never accessed, older than
  * `cutoff`, not already compressed. `includeAutoMarked` also folds in rows the
  * hook lightweight-marked as COMPRESSED_AUTO (the hook re-summarizes those).
+ * `<= 1` (was `= 1`): citation-decay floors importance at 0 and the LLM low-signal
+ * filter saves at imp=0; those rows are strictly lower value than imp=1 and must be
+ * GC-eligible too, or they accumulate forever (parity with hook.mjs auto-compress).
  */
 export function selectCompressionCandidates(db, { cutoff, project = null, includeAutoMarked = false }) {
   const compressedFilter = includeAutoMarked
@@ -35,8 +38,12 @@ export function selectCompressionCandidates(db, { cutoff, project = null, includ
   return db.prepare(`
     SELECT id, project, type, title, created_at, created_at_epoch
     FROM observations
-    WHERE COALESCE(importance, 1) = 1
+    WHERE COALESCE(importance, 1) <= 1
       AND COALESCE(access_count, 0) = 0
+      -- v3.23: exclude rows carrying a real lesson — folding them into a title-only
+      -- weekly summary discards the lesson (the distilled value of a lessons store).
+      -- Mirrors the hook auto-compress lesson guard so neither path buries a lesson.
+      AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       AND created_at_epoch < ?
       ${compressedFilter}
       ${projectFilter}

package/lib/maintain-core.mjs

@@ -98,6 +98,25 @@ export function recoverChildrenOf(db, ids) {
   ).run(...ids, ...ids).changes;
 }
 
+// Resurface children orphaned by a keeper hard-deleted BEFORE recoverChildrenOf existed
+// (legacy data). recoverChildrenOf only fires at delete time for the keepers being deleted
+// in that call; rows whose keeper vanished in a past release are missed forever. A child
+// with compressed_into = <positive keeperId> whose keeper row no longer exists is hidden
+// from every COALESCE(compressed_into,0)=0 view AND sits in no maintenance queue (not
+// COMPRESSED_AUTO, not COMPRESSED_PENDING_PURGE), so nothing ever resurfaces or GCs it —
+// it leaks its full narrative out of reach. Setting compressed_into = NULL makes it live
+// again; normal decay/GC then handles it on merit. `compressed_into > 0` excludes the
+// negative sentinels (intentional states, not orphans). NON-DESTRUCTIVE: only un-hides
+// rows, never deletes — safe to run unconditionally, no snapshot needed.
+export function recoverOrphanedChildren(db, { projectFilter = '', baseParams = [] } = {}) {
+  return db.prepare(`
+    UPDATE observations SET compressed_into = NULL
+    WHERE compressed_into > 0
+      AND NOT EXISTS (SELECT 1 FROM observations k WHERE k.id = observations.compressed_into)
+      ${projectFilter}
+  `).run(...baseParams).changes;
+}
+
 export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP }) {
   const doomed = db.prepare(`
     SELECT id FROM observations
@@ -112,30 +131,43 @@ export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP })
 }
 
 /**
- * Decay importance of old, never-accessed, NEVER-INJECTED observations, then mark
- * the importance-1 idle ones as pending-purge. injection_count>0 is protected as
- * first-class engagement alongside access_count (unified across all three paths).
+ * Decay importance of old, never-accessed, NEVER-INJECTED observations and mark the
+ * importance-1 idle ones as pending-purge. injection_count>0 is protected as first-class
+ * engagement alongside access_count (unified across all three paths).
+ *
+ * MARK-IDLE RUNS BEFORE DECAY (audit MED-1): if decay ran first, an imp-2 row would be
+ * decayed 2→1 and then re-selected by the same call's mark-idle pass → hidden as
+ * pending-purge in ONE pass, collapsing the per-tier grace cycle and over-marking vs what
+ * `maintain scan` (stale = imp-1 only) forecasts. Marking first means each call only marks
+ * rows that were ALREADY imp-1; a freshly-decayed imp-2→1 row waits for the next call,
+ * so importance tiers each buy a grace cycle (imp3→2→1→pending across runs) and the scan
+ * forecast matches what decay actually marks.
  */
 export function decayAndMarkIdle(db, { projectFilter, baseParams, staleAge, opCap = OP_CAP }) {
-  const decayed = db.prepare(`
-    UPDATE observations SET importance = MAX(1, COALESCE(importance, 1) - 1)
+  const idleMarked = db.prepare(`
+    UPDATE observations SET compressed_into = ${COMPRESSED_PENDING_PURGE}
     WHERE id IN (
       SELECT id FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
-        AND COALESCE(importance, 1) > 1
+        AND COALESCE(importance, 1) = 1
         AND COALESCE(access_count, 0) = 0
         AND COALESCE(injection_count, 0) = 0
+        -- v3.23: never mark a lesson-bearing row idle→pending-purge. A lesson is the
+        -- distilled value of a lessons store; auto-GC must not silently purge it (parity
+        -- with the compress lesson guards in hook.mjs + compress-core.mjs). Truly stale
+        -- lessons are removed by explicit delete, not background decay.
+        AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
         AND created_at_epoch < ?
         ${projectFilter} LIMIT ${opCap}
     )
   `).run(staleAge, ...baseParams).changes;
 
-  const idleMarked = db.prepare(`
-    UPDATE observations SET compressed_into = ${COMPRESSED_PENDING_PURGE}
+  const decayed = db.prepare(`
+    UPDATE observations SET importance = MAX(1, COALESCE(importance, 1) - 1)
     WHERE id IN (
       SELECT id FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
-        AND COALESCE(importance, 1) = 1
+        AND COALESCE(importance, 1) > 1
         AND COALESCE(access_count, 0) = 0
         AND COALESCE(injection_count, 0) = 0
         AND created_at_epoch < ?

package/lib/search-core.mjs

@@ -102,7 +102,7 @@ export function searchSessionsFts(db, { ftsQuery, project = null, projectBoost =
   return db.prepare(`
     SELECT s.id, s.request, s.completed, s.project, s.created_at, s.created_at_epoch,
            ${SESS_BM25}
-             * (1.0 + EXP(-0.693 * (? - s.created_at_epoch) / ${DEFAULT_DECAY_HALF_LIFE_MS}.0))
+             * (1.0 + EXP(-0.693 * MAX(0, ? - s.created_at_epoch) / ${DEFAULT_DECAY_HALF_LIFE_MS}.0))
              * (CASE WHEN ? IS NOT NULL AND s.project = ? THEN 2.0 ELSE 1.0 END) as score
     FROM session_summaries_fts
     JOIN session_summaries s ON session_summaries_fts.rowid = s.id

package/mem-cli.mjs

@@ -18,6 +18,7 @@ import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from '
 import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
+  recoverOrphanedChildren,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD,
@@ -324,7 +325,10 @@ function cmdRecent(db, args) {
   // accepted silently; the positional path must reject garbage like the --limit flag does.
   const isValid = rawArg !== undefined && isNumericToken(rawArg) && Number.isInteger(rawLimit) && rawLimit > 0 && rawLimit <= RECENT_MAX;
   if (rawArg !== undefined && !isValid) {
-    process.stderr.write(`[mem] Invalid count "${rawArg}" (must be an integer between 1 and ${RECENT_MAX}); using default 10\n`);
+    // Name the ACTUAL fallback: a present --limit overrides the positional below, so
+    // claiming "default 10" when `recent abc --limit 5` returns 5 misled the user.
+    const fallbackLabel = flags.limit !== undefined ? '--limit' : 'default 10';
+    process.stderr.write(`[mem] Invalid count "${rawArg}" (must be an integer between 1 and ${RECENT_MAX}); using ${fallbackLabel}\n`);
   }
   // Positional [N] wins for backward-compat; --limit is sibling-parity alias
   // (search/recall/browse/stats all accept --limit). Pre-2.69 `recent --limit N`
@@ -1093,9 +1097,17 @@ async function cmdStats(db, args) {
     `SELECT AVG(COALESCE(importance,1)) as v FROM observations WHERE 1=1 ${projectFilter}`
   ).get(...baseParams);
   const thirtyDaysAgo = now - 30 * 86400000;
+  // v3.23 noise-gauge de-blinding: the prior `importance = 1` predicate was
+  // structurally blind to imp=0 — decay's floor + the LLM low-signal filter push
+  // dormant rows to 0, which on a real store is ~half the live corpus. The gauge
+  // therefore reported "0.0% noise" while the store was dormant-heavy. `<= 1` makes
+  // imp=0 visible; injection_count=0 mirrors decay's NEVER-INJECTED guard so an
+  // injected-but-decayed row (pinned noise, tracked separately) is not miscounted
+  // as "never used".
   const lowVal = db.prepare(`
     SELECT COUNT(*) as c FROM observations
-    WHERE COALESCE(importance,1) = 1 AND COALESCE(access_count,0) = 0
+    WHERE COALESCE(importance,1) <= 1 AND COALESCE(access_count,0) = 0
+      AND COALESCE(injection_count,0) = 0
       AND COALESCE(compressed_into, 0) = 0
       AND created_at_epoch < ? ${projectFilter}
   `).get(thirtyDaysAgo, ...baseParams);
@@ -1194,7 +1206,7 @@ async function cmdStats(db, args) {
   out('Data Health:');
   out(`  Est. tokens: ${tokenEst.t ?? 0}`);
   out(`  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`);
-  out(`  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
+  out(`  Low-value (imp≤1, never used, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`);
   out(`  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`);
   out(`  Compressed: ${compressedCount.c}`);
   out(`  Hook errors (last 24h): ${hookErrors24h}${hookErrors24h > 0 ? `  ← tail ${join(DB_DIR, 'runtime/hook-errors')}` : ''}`);
@@ -1423,6 +1435,12 @@ function cmdDelete(db, args) {
     return;
   }
 
+  // Snapshot before the irreversible hard-delete so a wrong-id delete has a pre-image,
+  // matching the maintain purge/cleanup hard-delete paths (audit MED-2). Best-effort
+  // (never throws, skips :memory:); rows here are confirmed + non-empty, so the delete
+  // always removes something worth backing up. Must run OUTSIDE the transaction (VACUUM).
+  snapshotDb(db, { tag: 'pre-delete' });
+
   // Transaction: clean up related_ids references + delete (aligned with MCP mem_delete)
   const deletedIds = new Set(ids);
   const deleteTx = db.transaction(() => {
@@ -1552,6 +1570,12 @@ function cmdUpdate(db, args) {
 
 function cmdExport(db, args) {
   const { flags } = parseArgs(args);
+  // Guard value-less string flags. Bare `--to` parsed to boolean `true`, and
+  // `new Date(true).getTime()` is 1 (NOT NaN), so the isNaN guard below missed it and
+  // the filter became `created_at_epoch <= 1` → an EMPTY export with exit 0. A backup
+  // script (`export --to "$END" > backup.json`) with an unset `$END` would silently
+  // write an empty backup and report success. Reject like cmdSearch does.
+  if (rejectBareStringFlags(flags, ['project', 'type', 'from', 'to'])) return;
   const wheres = [];
   const params = [];
   // --include-compressed: include compressed observations (aligned with MCP mem_export)
@@ -1743,8 +1767,10 @@ function cmdCompress(db, args) {
   // got the 30-day cutoff without knowing their input was discarded.
   let ageDays = 30;
   if (flags['age-days'] !== undefined) {
-    const parsed = parseInt(flags['age-days'], 10);
-    if (!Number.isFinite(parsed) || parsed < 1) {
+    // isNumericToken (not bare parseInt) so "1e5"→1 and "30x"→30 are rejected rather than
+    // silently mis-parsed into a far-too-broad cutoff — parity with recent/search/maintain.
+    const parsed = Number(flags['age-days']);
+    if (!isNumericToken(flags['age-days']) || !Number.isInteger(parsed) || parsed < 1) {
       fail(`[mem] Invalid --age-days "${flags['age-days']}". Must be a positive integer.`);
       return;
     }
@@ -1800,6 +1826,11 @@ function cmdMaintain(db, args) {
     fail("[mem] Usage: claude-mem-lite maintain <scan|execute> [--ops cleanup,decay,boost,demote_pinned,dedup,purge_stale,rebuild_vectors,vacuum] [--project P] [--retain-days N] [--merge-ids keepId:removeId,...] — 'scan' previews, 'execute' applies.");
     return;
   }
+  // Guard value-less string flags before any `.split()` / resolveProject runs. A bare
+  // `--merge-ids` parsed to boolean `true`, and `true.split(',')` (line ~1911) crashed
+  // with a raw stack trace — the one string-flag path that lacked this #8470 guard, and
+  // the exact form the `scan` output suggests copy-pasting (`--merge-ids <pairs>`).
+  if (rejectBareStringFlags(flags, ['ops', 'project', 'merge-ids', 'retain-days'])) return;
 
   const project = flags.project ? resolveProject(db, flags.project) : null;
   const projectFilter = project ? 'AND project = ?' : '';
@@ -1868,18 +1899,64 @@ function cmdMaintain(db, args) {
   // T2-P1-B: surface the OP_CAP hit so users know to re-run, matching MCP mem_maintain.
   const capHint = (changes) => (changes >= OP_CAP ? ' (cap reached, re-run for more)' : '');
 
-  // MED-2: snapshot the DB before the irreversible cleanup/purge hard-deletes —
-  // only when rows will actually be removed, and OUTSIDE the transaction below
-  // (VACUUM cannot run inside one). Best-effort; snapshotDb never throws.
-  const willPurge = ops.includes('purge_stale') && (flags.confirm === true || flags.confirm === 'true');
+  // Parse + validate --retain-days BEFORE the transaction so an invalid value rejects the
+  // whole command atomically. The old code validated inside db.transaction() with a bare
+  // `return`, so an earlier op (cleanup hard-delete / decay / boost) had already mutated and
+  // the transaction COMMITTED despite the exit-1 error (audit MED-2 atomicity).
+  let retainDays = 30;
+  if (ops.includes('purge_stale') && flags['retain-days'] !== undefined) {
+    // Number + isInteger (not parseInt) so "7.5"/"30x" are rejected rather than silently
+    // truncated — parity with the mem_maintain zod .int().min(7).max(365) bound.
+    const parsed = Number(flags['retain-days']);
+    if (!Number.isInteger(parsed) || parsed < 7 || parsed > 365) {
+      fail(`[mem] --retain-days must be an integer in [7, 365] (got "${flags['retain-days']}")`);
+      return;
+    }
+    retainDays = parsed;
+  }
+  const retainCutoff = Date.now() - retainDays * 86400000;
+  // purge_stale is the only DELETE here — require --confirm so a mis-typed run can't wipe rows.
+  const confirmed = flags.confirm === true || flags.confirm === 'true';
+
+  // Snapshot the DB before the irreversible cleanup/purge hard-deletes — only when rows will
+  // actually be removed, and OUTSIDE the transaction below (VACUUM cannot run inside one).
+  // Best-effort; snapshotDb never throws.
+  const willPurge = ops.includes('purge_stale') && confirmed;
   if (hardDeleteCandidateCount(db, mctx, { cleanup: ops.includes('cleanup'), purge: willPurge }) > 0) {
     snapshotDb(db, { tag: 'pre-maintain' });
   }
 
   db.transaction(() => {
+    // PURGE FIRST — matches the auto-maintain hook order (hook.mjs:766). Running decay BEFORE
+    // purge in one transaction marked a stale row pending-purge AND deleted it in the SAME call
+    // (zero grace), and the pre-txn snapshot guard counts only PRE-EXISTING pending rows so it
+    // skipped the backup → permanent, unrecoverable loss of notable imp-2/3 memories (audit
+    // HIGH-1). Purging first deletes only rows a PRIOR run marked (which the guard saw + backed
+    // up); rows decay marks below wait for the next maintain run, regaining the grace cycle.
+    if (ops.includes('purge_stale')) {
+      if (!confirmed) {
+        const previewRow = purgeStalePreview(db, mctx, retainCutoff);
+        const pushLines = [`purge_stale preview (no --confirm):`,
+          `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`];
+        if (previewRow.candidates > 0) {
+          pushLines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
+          pushLines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
+        }
+        pushLines.push(`  To delete, re-run with --confirm.`);
+        results.push(pushLines.join('\n'));
+      } else {
+        const purged = purgeStale(db, mctx, retainCutoff);
+        results.push(`Purged ${purged} stale observations (retained last ${retainDays} days)${capHint(purged)}`);
+      }
+    }
+
     if (ops.includes('cleanup')) {
       const deleted = cleanupBroken(db, mctx);
       results.push(`Cleaned up ${deleted} broken observations${capHint(deleted)}`);
+      // Self-heal legacy orphans (keeper hard-deleted pre-recoverChildrenOf): resurface
+      // unreachable children. Non-destructive — un-hide only, no delete.
+      const orphans = recoverOrphanedChildren(db, mctx);
+      if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
     }
 
     if (ops.includes('decay')) {
@@ -1926,43 +2003,6 @@ function cmdMaintain(db, args) {
       results.push('Warning: --merge-ids provided but "dedup" not in operations — merge-ids ignored');
     }
 
-    if (ops.includes('purge_stale')) {
-      // --retain-days: default 30 when absent; reject negative / 0 / NaN / out-of-range.
-      // A negative value made retainCutoff a FUTURE timestamp → purged the entire
-      // pending-purge backlog regardless of age; 0/garbage silently became 30 and
-      // masked typos. Parity with the mem_maintain MCP zod bound [7, 365].
-      let retainDays = 30;
-      if (flags['retain-days'] !== undefined) {
-        // Number + isInteger (not parseInt) so "7.5"/"30x" are rejected rather than
-        // silently truncated to 7/30 — parity with the mem_maintain zod .int() bound.
-        const parsed = Number(flags['retain-days']);
-        if (!Number.isInteger(parsed) || parsed < 7 || parsed > 365) {
-          // fail() only sets exitCode + writes stderr; it does NOT throw, so we
-          // MUST return or execution falls through to the DELETE with the bad value.
-          fail(`[mem] --retain-days must be an integer in [7, 365] (got "${flags['retain-days']}")`);
-          return;
-        }
-        retainDays = parsed;
-      }
-      const retainCutoff = Date.now() - retainDays * 86400000;
-      // T2-P0-A (CLI parity): purge_stale is the only DELETE in this code path — require
-      // --confirm so a mis-typed `maintain execute --ops purge_stale` can't wipe rows silently.
-      const confirmed = flags.confirm === true || flags.confirm === 'true';
-      if (!confirmed) {
-        const previewRow = purgeStalePreview(db, mctx, retainCutoff);
-        const pushLines = [`purge_stale preview (no --confirm):`,
-          `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`];
-        if (previewRow.candidates > 0) {
-          pushLines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
-          pushLines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
-        }
-        pushLines.push(`  To delete, re-run with --confirm.`);
-        results.push(pushLines.join('\n'));
-      } else {
-        const purged = purgeStale(db, mctx, retainCutoff);
-        results.push(`Purged ${purged} stale observations (retained last ${retainDays} days)${capHint(purged)}`);
-      }
-    }
   })();
 
   // FTS optimize

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/post-tool-use.sh

@@ -32,7 +32,11 @@ if [[ "$tool" == "Read" ]]; then
     # Sanitize project name to match utils.mjs inferProject()
     project="${project//[^a-zA-Z0-9_.-]/-}"
     project="${project:-unknown}"
-    runtime_dir="$HOME/.claude-mem-lite/runtime"
+    # Honor CLAUDE_MEM_DIR relocation (mirrors schema.mjs DB_DIR → hook-shared RUNTIME_DIR).
+    # hook.mjs flushEpisode reads reads-<project>.txt from CLAUDE_MEM_DIR/runtime; if this
+    # bash fast-path wrote to $HOME unconditionally, a relocated install would drop all
+    # Read context from episodes AND grow an uncollected reads file in $HOME forever.
+    runtime_dir="${CLAUDE_MEM_DIR:-$HOME/.claude-mem-lite}/runtime"
     mkdir -p "$runtime_dir" 2>/dev/null
     # Use printf to avoid shell interpretation of special characters in file paths
     printf '%s\n' "$file_path" >> "${runtime_dir}/reads-${project}.txt"

package/scripts/user-prompt-search.js

@@ -491,6 +491,11 @@ async function main() {
 
   let hookData;
   try { hookData = JSON.parse(raw); } catch { return; }
+  // JSON.parse('null'/'42'/'"x"') succeeds with a non-object; dereferencing .prompt on
+  // it threw a raw TypeError → unhandled rejection → exit 1 (this was the lone hook
+  // script without an exit-0 safety net, violating the "hooks never exit non-zero"
+  // invariant — exit 2 on UserPromptSubmit would even block the user's prompt).
+  if (!hookData || typeof hookData !== 'object') return;
 
   const rawPrompt = hookData.prompt || hookData.user_prompt;
   if (!rawPrompt || typeof rawPrompt !== 'string') return;
@@ -724,4 +729,8 @@ async function main() {
   }
 }
 
-main();
+// Swallow any rejection so the hook can never surface a non-zero exit (the invariant
+// every sibling hook script upholds). Deliberately NOT `.finally(process.exit(0))` —
+// this hook detaches a background `claude -p` search and a forced exit would kill it;
+// letting the loop drain naturally exits 0 once the detached child is unref'd.
+main().catch(() => {});

package/search-engine.mjs

@@ -16,8 +16,13 @@ import { extractPRFTerms, expandQueryByConcepts } from './search-scoring.mjs';
 
 // Scoring expressions — full adds project boost + access bonus; simple is for
 // expansion paths where boost would over-amplify already-loose matches.
+// `MAX(0, now - ts)` clamps the recency age to >= 0: a far-FUTURE created_at/last_accessed
+// (reachable via restore/import-jsonl, which accept arbitrary epochs) otherwise made the
+// exponent large-positive → EXP overflowed to +Infinity → score -Infinity → that row sorted
+// #1 for any match AND JSON.stringify emitted `"score": null` (numeric-contract break). A
+// future row now reads as age 0 = max (finite) recency, not Infinity.
 const FULL_SCORE = `${OBS_BM25}
-  * (1.0 + EXP(-0.693 * (? - MAX(o.created_at_epoch, COALESCE(o.last_accessed_at, o.created_at_epoch))) / ${TYPE_DECAY_CASE}))
+  * (1.0 + EXP(-0.693 * MAX(0, ? - MAX(o.created_at_epoch, COALESCE(o.last_accessed_at, o.created_at_epoch))) / ${TYPE_DECAY_CASE}))
   * ${TYPE_QUALITY_CASE}
   * (CASE WHEN ? IS NOT NULL AND o.project = ? THEN 2.0 ELSE 1.0 END)
   * (0.5 + 0.5 * COALESCE(o.importance, 1))
@@ -25,7 +30,7 @@ const FULL_SCORE = `${OBS_BM25}
   * (1.0 + 0.3 * (o.lesson_learned IS NOT NULL))`;
 
 const SIMPLE_SCORE = `${OBS_BM25}
-  * (1.0 + EXP(-0.693 * (? - MAX(o.created_at_epoch, COALESCE(o.last_accessed_at, o.created_at_epoch))) / ${TYPE_DECAY_CASE}))
+  * (1.0 + EXP(-0.693 * MAX(0, ? - MAX(o.created_at_epoch, COALESCE(o.last_accessed_at, o.created_at_epoch))) / ${TYPE_DECAY_CASE}))
   * ${TYPE_QUALITY_CASE}
   * (0.5 + 0.5 * COALESCE(o.importance, 1))
   * (1.0 + 0.3 * (o.lesson_learned IS NOT NULL))`;
@@ -320,7 +325,7 @@ export function findFtsAnchor(db, { ftsQuery, project = null, nowT = null, halfL
       AND (? IS NULL OR o.project = ?)
       AND COALESCE(o.compressed_into, 0) = 0
     ORDER BY ${OBS_BM25}
-      * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${halfLifeMs}.0))
+      * (1.0 + EXP(-0.693 * MAX(0, ? - o.created_at_epoch) / ${halfLifeMs}.0))
     LIMIT 1
   `;
   const stmt = db.prepare(sql);

package/server.mjs

@@ -17,6 +17,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, coreRunSearchPipeline } from './lib/search-core.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
+  recoverOrphanedChildren,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS,
@@ -617,6 +618,11 @@ server.registerTool(
       return { content: [{ type: 'text', text: lines.join('\n') }] };
     }
 
+    // Snapshot before the irreversible hard-delete so a wrong-id delete has a pre-image,
+    // matching the CLI delete + maintain purge/cleanup paths (audit MED-2). Best-effort
+    // (never throws, skips :memory:). Must run OUTSIDE the transaction below (VACUUM).
+    snapshotDb(db, { tag: 'pre-delete' });
+
     // Wrap cleanup + deletion in a transaction for consistency
     const deletedIds = new Set(args.ids);
     const deleteTx = db.transaction(() => {
@@ -858,9 +864,14 @@ server.registerTool(
     `).get(...baseParams);
 
     const thirtyDaysAgo = Date.now() - 30 * 86400000;
+    // v3.23 noise-gauge de-blinding (mirrors mem-cli cmdStats): `<= 1` makes the
+    // imp=0 dormant population visible (decay floor + LLM low-signal filter push
+    // ~half the live corpus to 0); injection_count=0 mirrors decay's NEVER-INJECTED
+    // guard so injected-but-decayed pinned noise isn't miscounted as "never used".
     const lowVal = db.prepare(`
       SELECT COUNT(*) as c FROM observations
-      WHERE COALESCE(importance,1) = 1 AND COALESCE(access_count,0) = 0
+      WHERE COALESCE(importance,1) <= 1 AND COALESCE(access_count,0) = 0
+        AND COALESCE(injection_count,0) = 0
         AND COALESCE(compressed_into, 0) = 0
         AND created_at_epoch < ? ${projectFilter}
     `).get(thirtyDaysAgo, ...baseParams);
@@ -910,7 +921,7 @@ server.registerTool(
       'Data Health:',
       `  Est. tokens: ${tokenEst.t ?? 0}`,
       `  Avg importance: ${(avgImp.v ?? 1).toFixed(2)}`,
-      `  Low-value (imp=1, never accessed, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`,
+      `  Low-value (imp≤1, never used, >30d): ${lowVal.c} (${(noiseRatio * 100).toFixed(1)}% noise)`,
       `  Low-signal titles (Modified/Error/Worked on…): ${lowSignalTitle.c} (${(lowSignalRatio * 100).toFixed(1)}%)`,
       `  Compressed: ${compressedCount.c}`,
       ...((noiseRatio > 0.6 || lowSignalRatio > 0.3) ? ['  ⚠️ High noise ratio — consider running mem_compress / maintain'] : []),
@@ -1088,9 +1099,26 @@ server.registerTool(
       }
 
       db.transaction(() => {
+        // PURGE FIRST — matches the auto-maintain hook order (hook.mjs:766) and the CLI
+        // cmdMaintain. Running decay BEFORE purge in one transaction marked a stale row
+        // pending-purge AND deleted it in the SAME call (zero grace), while the pre-txn
+        // snapshot guard counts only PRE-EXISTING pending rows so it skipped the backup →
+        // permanent loss of notable imp-2/3 memories (audit HIGH-1). Purging first deletes
+        // only rows a PRIOR run marked (backed up); rows decay marks below wait one cycle.
+        if (ops.includes('purge_stale')) {
+          const retainDays = args.retain_days ?? 30;
+          const retainCutoff = Date.now() - retainDays * 86400000;
+          const purged = purgeStale(db, mctx, retainCutoff);
+          results.push(`Purged ${purged} stale observations (retained last ${retainDays} days)` + (purged >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
+        }
+
         if (ops.includes('cleanup')) {
           const deleted = cleanupBroken(db, mctx);
           results.push(`Cleaned up ${deleted} broken observations` + (deleted >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
+          // Self-heal legacy orphans (keeper hard-deleted pre-recoverChildrenOf):
+          // resurface unreachable children. Non-destructive — un-hide only, no delete.
+          const orphans = recoverOrphanedChildren(db, mctx);
+          if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
         }
 
         if (ops.includes('decay')) {
@@ -1118,13 +1146,6 @@ server.registerTool(
         if (!ops.includes('dedup') && args.merge_ids) {
           results.push('Warning: merge_ids provided but "dedup" not in operations — merge_ids ignored');
         }
-
-        if (ops.includes('purge_stale')) {
-          const retainDays = args.retain_days ?? 30;
-          const retainCutoff = Date.now() - retainDays * 86400000;
-          const purged = purgeStale(db, mctx, retainCutoff);
-          results.push(`Purged ${purged} stale observations (retained last ${retainDays} days)` + (purged >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
-        }
       })();
 
       // FTS5 optimize (outside transaction)

package/utils.mjs

@@ -14,7 +14,7 @@ export { cjkBigrams, extractCjkSynonymTokens, extractCjkKeywords, extractCjkLike
 export { resolveProject, _resetProjectCache } from './project-utils.mjs';
 export { scrubSecrets, SECRET_PATTERNS } from './secret-scrub.mjs';
 export { stripPrivate } from './lib/private-strip.mjs';
-export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey, formatErrorRecallHints } from './format-utils.mjs';
+export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey, formatErrorRecallHints, neutralizeContextDelimiters } from './format-utils.mjs';
 export { computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from './hash-utils.mjs';
 export { detectBashSignificance, extractErrorKeywords, extractFilePaths, stripTestSuffix } from './bash-utils.mjs';