claude-mem-lite 3.20.0 → 3.21.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.20.0",
+      "version": "3.21.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.21.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/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,
@@ -46,7 +46,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,
@@ -749,21 +750,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`);
 

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

@@ -238,6 +238,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/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';
@@ -1867,6 +1868,14 @@ 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');
+  if (hardDeleteCandidateCount(db, mctx, { cleanup: ops.includes('cleanup'), purge: willPurge }) > 0) {
+    snapshotDb(db, { tag: 'pre-maintain' });
+  }
+
   db.transaction(() => {
     if (ops.includes('cleanup')) {
       const deleted = cleanupBroken(db, mctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.20.0",
+  "version": "3.21.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/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';
@@ -1078,6 +1079,14 @@ 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(() => {
         if (ops.includes('cleanup')) {
           const deleted = cleanupBroken(db, mctx);

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;