claude-mem-lite 3.21.0 → 3.22.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.21.0",
+      "version": "3.22.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.22.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/cli/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-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';
@@ -696,15 +697,19 @@ 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
         AND created_at_epoch < ?
         AND project = ?
@@ -722,7 +727,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 (
@@ -848,6 +853,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/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,7 +38,7 @@ 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
       AND created_at_epoch < ?
       ${compressedFilter}

package/lib/maintain-core.mjs

@@ -112,17 +112,25 @@ 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
         AND created_at_epoch < ?
@@ -130,12 +138,12 @@ export function decayAndMarkIdle(db, { projectFilter, baseParams, staleAge, opCa
     )
   `).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

@@ -324,7 +324,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`
@@ -1423,6 +1426,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 +1561,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 +1758,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 +1817,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,15 +1890,57 @@ 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)}`);
@@ -1926,43 +1990,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.22.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

@@ -617,6 +617,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(() => {
@@ -1088,6 +1093,19 @@ 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)' : ''));
@@ -1118,13 +1136,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';