claude-mem-lite 3.20.0 → 3.22.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.20.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.20.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-update.mjs

@@ -489,6 +489,51 @@ export async function verifyReleaseAuthenticity(extractedDir, assets, publicKey
 // below skips the 'node_modules' switchable path (existsSync guard), leaving
 // the target's node_modules untouched. Dependency bumps still flow through the
 // GitHub-tarball path (downloadAndInstall), which keeps skipNpmInstall=false.
+// Undo a (partial or complete) file swap: delete the freshly-installed files, then
+// rename each backup back into place. Shared by the error path and the MED-5
+// post-install smoke gate so there is ONE rollback implementation.
+function rollbackInstall(installed, backedUp, backupDir, targetDir) {
+  for (const relPath of installed.reverse()) {
+    try { rmSync(join(targetDir, relPath), { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+  for (const relPath of backedUp.reverse()) {
+    const backupPath = join(backupDir, relPath);
+    const targetPath = join(targetDir, relPath);
+    try {
+      if (existsSync(backupPath)) {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        renameSync(backupPath, targetPath);
+      }
+    } catch (restoreErr) {
+      debugCatch(restoreErr, `installExtractedRelease-restore-${relPath}`);
+    }
+  }
+}
+
+// MED-5 post-install health gate: load-test the freshly-switched code in a SEPARATE
+// process before the backup is discarded. A clean file swap can still yield an
+// install that won't boot — a syntax error, an unresolved import from a half-applied
+// mixed-version swap (renameSync loop hard-killed mid-way), or a native ABI mismatch.
+// `cli.mjs help` boots the CLI entry, which dynamically imports the mem-cli module
+// graph (maintain-core / search-engine / scoring / db-backup / schema / …) and exits
+// 0 without opening the DB or a server. hook.mjs and server.mjs auto-execute on
+// import (so they can't be import-smoked) — they get a `node --check` syntax pass.
+// execSync (not execFileSync) so the unit-test child_process mock intercepts it.
+function smokeInstalledRelease(targetDir) {
+  const q = (s) => JSON.stringify(s);
+  try {
+    execSync(`${q(process.execPath)} ${q(join(targetDir, 'cli.mjs'))} help`, { timeout: 20000, stdio: 'ignore' });
+    for (const entry of ['hook.mjs', 'server.mjs']) {
+      const p = join(targetDir, entry);
+      if (existsSync(p)) execSync(`${q(process.execPath)} --check ${q(p)}`, { timeout: 10000, stdio: 'ignore' });
+    }
+    return true;
+  } catch (e) {
+    debugLog('WARN', 'hook-update', `post-install smoke failed (rolling back): ${e.message}`);
+    return false;
+  }
+}
+
 export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR, opts = {}) {
   // Cross-process lock: concurrent SessionStart self-heals / auto-updates must
   // not interleave the rename loop below (→ mixed-version install). A live peer
@@ -541,6 +586,16 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
       installed.push(relPath);
     }
 
+    // MED-5: before discarding the rollback backup, prove the switched code boots.
+    // If it can't, restore the backup and report failure — the running (old) version
+    // keeps working rather than leaving a broken install with no way back.
+    if (!opts.skipSmoke && !smokeInstalledRelease(targetDir)) {
+      rollbackInstall(installed, backedUp, backupDir, targetDir);
+      rmSync(stagingDir, { recursive: true, force: true });
+      rmSync(backupDir, { recursive: true, force: true });
+      return false;
+    }
+
     rmSync(stagingDir, { recursive: true, force: true });
     rmSync(backupDir, { recursive: true, force: true });
 
@@ -580,25 +635,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     return true;
   } catch (err) {
     debugCatch(err, 'installExtractedRelease');
-
-    for (const relPath of installed.reverse()) {
-      try { rmSync(join(targetDir, relPath), { recursive: true, force: true }); } catch {}
-    }
-    for (const relPath of backedUp.reverse()) {
-      const backupPath = join(backupDir, relPath);
-      const targetPath = join(targetDir, relPath);
-      try {
-        if (existsSync(backupPath)) {
-          mkdirSync(dirname(targetPath), { recursive: true });
-          renameSync(backupPath, targetPath);
-        }
-      } catch (restoreErr) {
-        debugCatch(restoreErr, `installExtractedRelease-restore-${relPath}`);
-      }
-    }
-
-    try { rmSync(stagingDir, { recursive: true, force: true }); } catch {}
-    try { rmSync(backupDir, { recursive: true, force: true }); } catch {}
+    rollbackInstall(installed, backedUp, backupDir, targetDir);
+    try { rmSync(stagingDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+    try { rmSync(backupDir, { recursive: true, force: true }); } catch { /* best-effort */ }
     return false;
   } finally {
     release();

package/hook.mjs

@@ -26,7 +26,7 @@ import {
   truncate, inferProject, detectBashSignificance,
   extractErrorKeywords, extractFilePaths, isRelatedToEpisode,
   makeEntryDesc, scrubSecrets, stripPrivate, EDIT_TOOLS, debugCatch, debugLog,
-  COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25, notLowSignalTitleClause, formatErrorRecallHints,
+  COMPRESSED_AUTO, OBS_BM25, notLowSignalTitleClause, formatErrorRecallHints,
 } from './utils.mjs';
 import {
   readEpisodeRaw, episodeFile,
@@ -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,8 @@ 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 } from './lib/maintain-core.mjs';
+import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, hardDeleteCandidateCount, purgeStale } from './lib/maintain-core.mjs';
+import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
   extractAllInjected,
@@ -695,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 = ?
@@ -721,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 (
@@ -749,21 +755,27 @@ function runSessionStartAutoMaintain(db) {
     try {
       const STALE_AGE = Date.now() - 30 * 86400000;
       const OP_CAP = 500;
-
-      // Purge FIRST: delete pending-purge entries. Schema has no marked_at_epoch, so we
-      // anchor retention on created_at_epoch instead: 30d marking gate + 7d grace = 37d.
-      // Older cutoffs (e.g. 7d) were always redundant with the 30d marking filter and
-      // made purge effectively immediate on the next maintenance cycle — fix for T4-P1-A.
-      const purged = db.prepare(`
-        DELETE FROM observations WHERE compressed_into = ${COMPRESSED_PENDING_PURGE}
-          AND created_at_epoch < ?
-      `).run(Date.now() - 37 * 86400000);
-      if (purged.changes > 0) debugLog('DEBUG', 'auto-maintain', `purged ${purged.changes} stale observations`);
-
-      // cleanup / decay+mark-idle / boost via maintain-core (shared with CLI + MCP).
-      // injection_count>0 protection lives in decayAndMarkIdle. Whole-DB, cap 500.
+      // Shared maintenance context (whole-DB, cap 500) — used by every maintain-core
+      // op below AND the MED-2 snapshot guard. injection_count>0 protection lives in
+      // decayAndMarkIdle.
       const mctx = { projectFilter: '', baseParams: [], staleAge: STALE_AGE, opCap: OP_CAP };
 
+      // MED-2: snapshot the DB before the irreversible purge/cleanup hard-deletes
+      // below, but only when rows will actually be removed (cheap COUNT). Must run
+      // here, outside any transaction — VACUUM cannot run inside one. Best-effort:
+      // snapshotDb never throws, so a backup failure cannot block auto-maintain.
+      if (hardDeleteCandidateCount(db, mctx, { cleanup: true, purge: true }) > 0) {
+        snapshotDb(db, { tag: 'pre-maintain' });
+      }
+
+      // Purge FIRST via the SHARED purgeStale — was an inline DELETE that skipped
+      // recoverChildrenOf, so purging a keeper that had absorbed dups orphaned its
+      // children (compressed_into dangling at a deleted id). purgeStale recovers them
+      // first and caps at opCap. Schema has no marked_at_epoch, so retention anchors on
+      // created_at_epoch: 30d marking gate + 7d grace = 37d.
+      const purged = purgeStale(db, mctx, Date.now() - 37 * 86400000);
+      if (purged > 0) debugLog('DEBUG', 'auto-maintain', `purged ${purged} stale observations`);
+
       const cleaned = cleanupBroken(db, mctx);
       if (cleaned > 0) debugLog('DEBUG', 'auto-maintain', `cleaned ${cleaned} broken observations`);
 
@@ -841,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/db-backup.mjs

@@ -0,0 +1,55 @@
+// lib/db-backup.mjs — point-in-time DB snapshot before irreversible maintenance.
+//
+// VACUUM INTO produces a consistent, compact copy of the database (WAL-safe —
+// unlike copyFileSync, which would miss un-checkpointed WAL frames). Best-effort:
+// a failure logs a WARN and returns null so it NEVER blocks the maintenance it
+// guards (a backup that aborts a disk-full purge would be worse than no backup).
+//
+// MUST be called OUTSIDE any transaction — VACUUM cannot run inside one, which is
+// why the maintenance entry points snapshot before opening their db.transaction().
+import { readdirSync, unlinkSync } from 'fs';
+import { dirname, basename, join } from 'path';
+import { debugLog } from '../utils.mjs';
+
+// Monotonic per-process suffix so two snapshots in the same millisecond (same pid)
+// still get unique filenames (VACUUM INTO fails if the target already exists).
+let _seq = 0;
+
+/**
+ * Snapshot `db` to `<db-path>.<tag>-<ts>.bak` via VACUUM INTO, then prune to the
+ * newest `retain` snapshots. No-op (returns null) for :memory: DBs (tests) and on
+ * any error (logged). Returns the snapshot path on success.
+ * @returns {string|null}
+ */
+export function snapshotDb(db, { tag = 'pre-maintain', retain = 3 } = {}) {
+  try {
+    const dbPath = db && db.name;
+    if (!dbPath || dbPath === ':memory:') return null; // in-memory — nothing to snapshot
+    const stamp = `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}-${_seq++}`;
+    const out = `${dbPath}.${tag}-${stamp}.bak`;
+    // Path is internal (db.name from our own config), but escape single quotes
+    // defensively since VACUUM INTO takes a string literal, not a bound param.
+    db.exec(`VACUUM INTO '${out.replace(/'/g, "''")}'`);
+    pruneSnapshots(dbPath, tag, retain);
+    return out;
+  } catch (e) {
+    try { debugLog('WARN', 'db-backup', `snapshot skipped (proceeding without): ${e.message}`); } catch { /* ignore */ }
+    return null;
+  }
+}
+
+// Keep the newest `retain` `<base>.<tag>-*.bak` files, unlink the rest. The ISO
+// timestamp embedded in the name makes a lexical sort chronological.
+function pruneSnapshots(dbPath, tag, retain) {
+  try {
+    const dir = dirname(dbPath);
+    const prefix = `${basename(dbPath)}.${tag}-`;
+    const names = readdirSync(dir)
+      .filter(n => n.startsWith(prefix) && n.endsWith('.bak'))
+      .sort()
+      .reverse(); // newest first
+    for (const n of names.slice(retain)) {
+      try { unlinkSync(join(dir, n)); } catch { /* per-entry best-effort */ }
+    }
+  } catch { /* best-effort — dir may be unreadable */ }
+}

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 < ?
@@ -238,6 +246,31 @@ export function mergeDuplicates(db, groups) {
   return merged;
 }
 
+/**
+ * Count rows a destructive maintenance run would hard-DELETE: pending-purge rows
+ * (any age — a cheap proxy for "purge has something to remove", deliberately not
+ * age-filtered so the guard never under-counts) and/or broken empty-content rows
+ * (cleanupBroken's doomed set). Used by the maintenance entry points to decide
+ * whether to VACUUM-snapshot the DB first (audit MED-2) — over-counting only costs
+ * one extra bounded backup; under-counting would skip the safety net.
+ */
+export function hardDeleteCandidateCount(db, { projectFilter, baseParams }, { cleanup = false, purge = false } = {}) {
+  let n = 0;
+  if (purge) {
+    n += db.prepare(
+      `SELECT COUNT(*) AS c FROM observations WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} ${projectFilter}`
+    ).get(...baseParams).c;
+  }
+  if (cleanup) {
+    n += db.prepare(
+      `SELECT COUNT(*) AS c FROM observations
+       WHERE COALESCE(compressed_into, 0) = 0
+         AND (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '') ${projectFilter}`
+    ).get(...baseParams).c;
+  }
+  return n;
+}
+
 /** Preview pending-purge candidates older than the retain cutoff (no deletion). */
 export function purgeStalePreview(db, { projectFilter, baseParams }, retainCutoff) {
   return db.prepare(`

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

@@ -19,9 +19,10 @@ import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
-  recoverChildrenOf,
+  recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD,
 } from './lib/maintain-core.mjs';
+import { snapshotDb } from './lib/db-backup.mjs';
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
 import { buildSessionContextLines } from './hook-context.mjs';
 import { cmdAdopt, cmdUnadopt } from './adopt-cli.mjs';
@@ -323,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`
@@ -1422,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(() => {
@@ -1551,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)
@@ -1742,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;
     }
@@ -1799,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 = ?' : '';
@@ -1867,7 +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)' : '');
 
+  // 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)}`);
@@ -1917,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.20.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",
@@ -84,6 +84,7 @@
     "lib/search-core.mjs",
     "lib/rrf.mjs",
     "lib/compress-core.mjs",
+    "lib/db-backup.mjs",
     "lib/maintain-core.mjs",
     "lib/dedup-constants.mjs",
     "lib/deferred-work.mjs",

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

@@ -18,9 +18,10 @@ import { buildSearchFtsQuery, parseDateBounds, coreRunSearchPipeline } from './l
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
-  recoverChildrenOf,
+  recoverChildrenOf, hardDeleteCandidateCount,
   OP_CAP, STALE_AGE_MS,
 } from './lib/maintain-core.mjs';
+import { snapshotDb } from './lib/db-backup.mjs';
 import { effectiveQuiet, RUNTIME_DIR } from './hook-shared.mjs';
 import { TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { formatObsFieldValue } from './cli/common.mjs';
@@ -616,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(() => {
@@ -1078,7 +1084,28 @@ server.registerTool(
         return { content: [{ type: 'text', text: lines.join('\n') }] };
       }
 
+      // 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). purge_stale is already confirmed by here (the
+      // preview branch returned above otherwise). Best-effort; snapshotDb never throws.
+      if (hardDeleteCandidateCount(db, mctx, { cleanup: ops.includes('cleanup'), purge: ops.includes('purge_stale') }) > 0) {
+        snapshotDb(db, { tag: 'pre-maintain' });
+      }
+
       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)' : ''));
@@ -1109,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/source-files.mjs

@@ -131,6 +131,10 @@ export const SOURCE_FILES = [
   // Statically imported by mem-cli.mjs (cmdMaintain), server.mjs (mem_maintain),
   // and hook.mjs (handleAutoMaintain) — missing it would break maintain on auto-update.
   'lib/maintain-core.mjs',
+  // Pre-maintenance VACUUM INTO snapshot (MED-2). Statically imported by mem-cli.mjs,
+  // server.mjs, and hook.mjs before their destructive purge/cleanup — missing it
+  // would crash maintain on auto-update with an unresolved import.
+  'lib/db-backup.mjs',
   // P10 dedup/merge threshold constants — single source of truth for the Jaccard
   // dedup/merge cutoffs. Statically imported by hook.mjs, hook-llm.mjs,
   // hook-optimize.mjs, mem-cli.mjs, server.mjs, and the save/maintain cores;

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';