claude-mem-lite 5.1.1 → 5.2.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "5.1.1",
+      "version": "5.2.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": "5.1.1",
+  "version": "5.2.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/fts-check.mjs

@@ -18,6 +18,16 @@ export function cmdFtsCheck(db, args) {
     return;
   }
 
+  // Exit-code contract, matching `memdir-audit` — the other diagnostic in
+  // CLI_COMMANDS, whose help documents "Exit 0 if every file is compliant, 1
+  // otherwise". Both actions used to print the failure and exit 0, so
+  // `fts-check rebuild && echo repaired` announced a repair that had not
+  // happened, and an agent reading only the status code was told the index was
+  // healthy. `doctor` points users at this command precisely when it is not.
+  //
+  // Findings stay on STDOUT via out() rather than moving to fail()'s stderr:
+  // they are the report the user asked for, not an error trace, and the details
+  // are worth piping. Only process.exitCode changes.
   if (action === 'check') {
     const result = checkFTSIntegrity(db);
     if (result.healthy) {
@@ -25,6 +35,7 @@ export function cmdFtsCheck(db, args) {
     } else {
       out(`[mem] FTS5 issues found:`);
       for (const d of result.details) out(`  ${d}`);
+      process.exitCode = 1;
     }
     return;
   }
@@ -32,7 +43,10 @@ export function cmdFtsCheck(db, args) {
   if (action === 'rebuild') {
     const result = rebuildFTS(db);
     if (result.errors.length > 0) {
+      // Partial success is a failure of the requested operation: the caller asked
+      // for a rebuild and at least one index still is not rebuilt.
       out(`[mem] Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`);
+      process.exitCode = 1;
     } else {
       out(`[mem] Successfully rebuilt: ${result.rebuilt.join(', ')}`);
     }

package/hook-shared.mjs

@@ -37,7 +37,7 @@ export {
   CONTINUE_KEYWORDS,
 } from './lib/handoff-constants.mjs';
 
-import { DAY_MS } from './lib/time-constants.mjs';
+import { DAY_MS, ORPHAN_EPISODE_AGE_MS } from './lib/time-constants.mjs';
 // ─── Constants ────────────────────────────────────────────────────────────────
 
 // P1-14: one resolver, so this module honours CLAUDE_MEM_RUNTIME_DIR like the five
@@ -82,12 +82,11 @@ export const RELATED_OBS_WINDOW_MS = 7 * DAY_MS; // 7 days
 // <memory-context> injection on quiet/adopted projects where nothing renders).
 export const KEY_CONTEXT_LIMIT = 10;
 
-// Orphan-sweep threshold for `ep-flush-*` / `pending-*` runtime artifacts.
-// handleLLMEpisode's worst-case round-trip is ~60s (delay + LLM call + DB
-// write); 1h leaves a wide safety margin against deleting an in-flight file.
-// Older orphans are crashed workers or pre-shutdown buffers that no live
-// caller will ever pick up, so sweeping them on SessionStart is safe.
-export const ORPHAN_EPISODE_AGE_MS = 60 * 60 * 1000;
+// Orphan-sweep threshold for `ep-flush-*` / `pending-*` runtime artifacts. Defined in
+// lib/time-constants.mjs (the zero-import leaf) because install.mjs's manual `cleanup`
+// needs the same window and may only import from lib/; re-exported here so this module's
+// existing importers are unchanged.
+export { ORPHAN_EPISODE_AGE_MS };
 
 // `reads-<project>.txt` (bash fast-path Read tracker) is consumed by flushEpisode's
 // rename-collect on the next edit-flush, NOT by a background worker — so a project

package/install.mjs

@@ -71,6 +71,7 @@ import {
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
+import { ORPHAN_EPISODE_AGE_MS } from './lib/time-constants.mjs';
 import { acquireLock } from './lib/proc-lock.mjs';
 import { atomicWriteFileSync } from './lib/atomic-write.mjs';
 import { isMemHook, launcherEntryPath } from './lib/hook-prune.mjs';
@@ -2207,11 +2208,35 @@ function cleanup() {
   // and holding install.lock across it would block a self-heal for no reason.
   if (updateLock) updateLock();
 
-  // Clean pending-* / ep-flush-* in runtime/ (env-aware, and honouring the runtime override)
+  // Clean pending-* / ep-flush-* in runtime/ (env-aware, and honouring the runtime override).
+  //
+  // AGE-GATED, same window the automatic sweep uses (ORPHAN_EPISODE_AGE_MS, 1h). An
+  // `ep-flush-<ts>-<id>.json` is the episode handed to the summarizer, not residue: the
+  // round-trip is ~60s, and deleting one mid-flight discards that episode's observations
+  // silently while printing "✓ Removed". This block had no age gate at all, which made a
+  // documented maintenance command — the one `doctor` tells users to run — destructive
+  // against live work. Matches the P2-10 fix above (in-flight update residue) and the
+  // fixture sweep below, whose comment already states the principle: a MANUAL cleanup is
+  // the conservative one.
   const runtimeDir = MEM_RUNTIME_DIR;
   if (existsSync(runtimeDir)) {
+    const epCutoff = Date.now() - ORPHAN_EPISODE_AGE_MS;
+    let inFlight = 0;
     for (const f of readdirSync(runtimeDir)) {
       if (f.startsWith('pending-') || f.startsWith('ep-flush-')) {
+        // Unreadable mtime → treat as in-flight and skip. Failing safe here costs one
+        // stale file until the next sweep; failing open costs an episode.
+        let mtimeMs;
+        try {
+          mtimeMs = statSync(join(runtimeDir, f)).mtimeMs;
+        } catch {
+          inFlight++;
+          continue;
+        }
+        if (mtimeMs > epCutoff) {
+          inFlight++;
+          continue;
+        }
         if (dryRun) {
           ok(`Would remove: runtime/${f}`);
           removed++;
@@ -2226,6 +2251,11 @@ function cleanup() {
         }
       }
     }
+    if (inFlight > 0) {
+      log(
+        `  Kept ${inFlight} episode file(s) newer than 1h — possibly in flight, they sweep automatically once stale.`,
+      );
+    }
   }
 
   // Reap leaked test-fixture sandboxes from temp (mem-e2e-* / mem-audit-* / cite-*

package/lib/delete-core.mjs

@@ -101,5 +101,13 @@ export function previewDeleteRows(db, ids) {
   const lines = rows.map(
     (r) => `  #${r.id} [${r.type}] ${truncate(r.title || '(untitled)', 80)} | ${r.project}`,
   );
-  return { rows, lines };
+  // Requested ids with no row. Both faces used to derive this themselves and only
+  // in their CONFIRM branch, so the PREVIEW — whose entire job is to show what is
+  // about to happen — silently omitted them: `delete 42,43,44` listed two rows and
+  // the user learned 43 never existed only after confirming. Computed here so the
+  // CLI and mem_delete report the same set from one place. Order follows the
+  // caller's id order, which is the order they typed.
+  const found = new Set(rows.map((r) => r.id));
+  const missing = ids.filter((id) => !found.has(id));
+  return { rows, lines, missing };
 }

package/lib/maintain-core.mjs

@@ -65,6 +65,27 @@ export const PINNED_INJ_THRESHOLD = 8;
 // Hence: order matters, and `demote_pinned` MUST come after `boost`.
 export const DEFAULT_MAINTAIN_OPS = Object.freeze(['cleanup', 'decay', 'boost', 'demote_pinned']);
 
+// Every op `runMaintainOps` dispatches on — the SET, not a run order (the order a run
+// uses is DEFAULT_MAINTAIN_OPS' above, or the caller's array).
+//
+// Lives here because two faces validate against it and they are not allowed to drift:
+// the CLI (`mem-cli.mjs`, which rejects an unknown `--ops` value) and the MCP tool
+// schema (`tool-schemas.mjs`, a Zod `z.enum` the model reads). The MCP copy stays
+// hand-written on purpose — that enum is LLM-visible metadata, so reordering it to
+// derive from this array would be a behavioural change to tool routing for no gain —
+// and `tests/maintain-ops-invariant.test.mjs` diffs the two SETS instead, the same way
+// tests/audit-silent-20260814.test.mjs diffs the two hook sets.
+export const ALL_MAINTAIN_OPS = Object.freeze([
+  'cleanup',
+  'decay',
+  'boost',
+  'demote_pinned',
+  'dedup',
+  'purge_stale',
+  'rebuild_vectors',
+  'vacuum',
+]);
+
 // Opt-out for the v3.76.0 default change. Scoped to the DEFAULT set ONLY — an
 // explicit `--ops demote_pinned` / `operations:["demote_pinned"]` still runs. An
 // accepted value that silently means something else is worse than an unsupported

package/lib/time-constants.mjs

@@ -19,3 +19,20 @@ const MINUTE_MS = 60 * SECOND_MS;
 const HOUR_MS = 60 * MINUTE_MS;
 
 export const DAY_MS = 24 * HOUR_MS;
+
+/**
+ * How long an `ep-flush-*` / `pending-*` runtime file must sit untouched before any
+ * sweeper may treat it as an orphan rather than as work in flight.
+ *
+ * handleLLMEpisode's worst-case round-trip is ~60s (delay + LLM call + DB write), so 1h
+ * is a wide safety margin. Anything older is a crashed worker or a pre-shutdown buffer
+ * that no live caller will pick up.
+ *
+ * It lives HERE, in the zero-import leaf, because it now has two consumers that cannot
+ * share a module: the automatic sweep in `hook-shared.mjs` (which re-exports it, so its
+ * own importers are unchanged) and `install.mjs`'s manual `cleanup`, which may only
+ * import from `lib/`. That split is exactly how the two drifted: `cleanup` deleted every
+ * `ep-flush-*` with NO age gate at all, discarding a seconds-old in-flight episode while
+ * printing "✓ Removed" — and `doctor` recommends running `cleanup`.
+ */
+export const ORPHAN_EPISODE_AGE_MS = HOUR_MS;

package/mem-cli.mjs

@@ -45,6 +45,7 @@ import {
   STALE_AGE_MS,
   PINNED_INJ_THRESHOLD,
   resolveDefaultMaintainOps,
+  ALL_MAINTAIN_OPS,
 } from './lib/maintain-core.mjs';
 // snapshotDb left with maintain-core: the pre-maintain snapshot is part of the op ORDER
 // (it must see the pre-existing pending rows), so it moved into runMaintainOps (P1-5).
@@ -1898,7 +1899,7 @@ function cmdDelete(db, args) {
 
   const confirm = flags.confirm === true || flags.confirm === 'true';
   // Shared preview body (lib/delete-core, P2-12) — single source with mem_delete.
-  const { rows, lines: previewLines } = previewDeleteRows(db, ids);
+  const { rows, lines: previewLines, missing } = previewDeleteRows(db, ids);
 
   if (rows.length === 0) {
     fail('[mem] No observations found for given IDs');
@@ -1908,6 +1909,7 @@ function cmdDelete(db, args) {
   if (!confirm) {
     out(`[mem] Preview: ${rows.length} observation(s) will be deleted:`);
     for (const line of previewLines) out(line);
+    if (missing.length > 0) out(`[mem] Note: ID(s) ${missing.join(', ')} not found and will be skipped.`);
     out('[mem] Run with --confirm to execute deletion.');
     return;
   }
@@ -1916,7 +1918,6 @@ function cmdDelete(db, args) {
   // transaction) lives in lib/delete-core.mjs — single source of truth shared with the MCP
   // mem_delete path (was inlined here + kept in sync by parity comments, the #1 drift risk).
   const result = deleteObservations(db, ids);
-  const missing = ids.filter((id) => !rows.some((r) => r.id === id));
   const recoveredNote =
     result.recoveredChildren > 0
       ? ` Recovered ${result.recoveredChildren} merged/compressed child observation(s) to live.`
@@ -2498,6 +2499,13 @@ function cmdCompress(db, args) {
 
 // ─── Maintain ────────────────────────────────────────────────────────────────
 
+// Shared by BOTH maintain branches. It used to be a local const inside `execute`,
+// which is why `scan` — the preview step — silently accepted `--ops purge-stale`
+// (hyphen for underscore), printed a full report and exited 0, leaving the typo to
+// surface only on the run the preview was supposed to de-risk. The list itself now
+// comes from lib/maintain-core.mjs so this face and the MCP schema cannot drift.
+const VALID_MAINTAIN_OPS = ALL_MAINTAIN_OPS;
+
 function cmdMaintain(db, args) {
   const { positional, flags } = parseArgs(args);
   const action = positional[0];
@@ -2518,12 +2526,32 @@ function cmdMaintain(db, args) {
   const baseParams = project ? [project] : [];
 
   if (action === 'scan') {
+    // Validate --ops here too, with the same list and the same message `execute`
+    // uses. Catching the typo in the PREVIEW is the whole point: this is the step a
+    // user runs to find out what would happen, and it used to ignore the flag
+    // wholesale. Only validated when present — a plain `maintain scan` is unchanged.
+    if (flags.ops !== undefined) {
+      const scanOps = String(flags.ops)
+        .split(',')
+        .map((s) => s.trim());
+      const invalid = scanOps.filter((op) => !VALID_MAINTAIN_OPS.includes(op));
+      if (invalid.length > 0) {
+        fail(`[mem] Unknown operation(s): ${invalid.join(', ')}. Valid: ${VALID_MAINTAIN_OPS.join(', ')}`);
+        return;
+      }
+    }
+
     const staleAge = Date.now() - STALE_AGE_MS;
     const mctx = { projectFilter, baseParams, staleAge };
     const duplicates = findDuplicates(db, mctx);
     const stats = maintenanceStats(db, mctx);
 
     out(`[mem] Maintenance scan:`);
+    // The ops are valid but scan is not scoped by them — say so instead of letting a
+    // scoped-looking invocation imply a scoped report.
+    if (flags.ops !== undefined) {
+      out(`  (--ops is an execute-time filter; this scan reports every category)`);
+    }
     out(`  Total active: ${stats.total}`);
     out(`  Near-duplicate pairs: ${duplicates.length}`);
     out(`  Stale (>30d, imp=1, no access, never injected): ${stats.stale}`);
@@ -2567,27 +2595,17 @@ function cmdMaintain(db, args) {
   }
 
   // Execute
-  const VALID_OPS = [
-    'cleanup',
-    'decay',
-    'boost',
-    'demote_pinned',
-    'dedup',
-    'purge_stale',
-    'rebuild_vectors',
-    'vacuum',
-  ];
   // Distinguish flag-absent (use default op set) from flag-present-but-empty
   // (`--ops ""`, e.g. an unset shell var). The latter previously coerced via `||`
-  // to the destructive default set and EXECUTED it; route it to the VALID_OPS check
+  // to the destructive default set and EXECUTED it; route it to the VALID_MAINTAIN_OPS check
   // below instead so it's rejected like `--ops " "` / `--ops "decay,"`. (That default
   // was the literal `cleanup,decay,boost` when this was written; it now comes from
   // DEFAULT_MAINTAIN_OPS, which is why the list is no longer spelled out here.)
   const opsStr = flags.ops === undefined ? resolveDefaultMaintainOps().join(',') : String(flags.ops);
   const ops = opsStr.split(',').map((s) => s.trim());
-  const invalidOps = ops.filter((op) => !VALID_OPS.includes(op));
+  const invalidOps = ops.filter((op) => !VALID_MAINTAIN_OPS.includes(op));
   if (invalidOps.length > 0) {
-    fail(`[mem] Unknown operation(s): ${invalidOps.join(', ')}. Valid: ${VALID_OPS.join(', ')}`);
+    fail(`[mem] Unknown operation(s): ${invalidOps.join(', ')}. Valid: ${VALID_MAINTAIN_OPS.join(', ')}`);
     return;
   }
   const staleAge = Date.now() - STALE_AGE_MS;
@@ -3182,6 +3200,8 @@ Commands:
     --json              Machine-readable output (plain doctor run)
 
   fts-check <check|rebuild>  FTS5 index check or rebuild
+                        Exit 0 when every index is healthy / rebuilt, 1 otherwise —
+                        so "fts-check rebuild && <next step>" is safe to chain.
 
   stats                 Show memory statistics
     --project P         Filter by project

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "5.1.1",
+      "version": "5.2.0",
       "os": [
         "darwin",
         "linux"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "5.1.1",
+  "version": "5.2.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/server.mjs

@@ -961,7 +961,7 @@ server.registerTool(
   },
   safeHandler(async (args) => {
     // Shared preview body (lib/delete-core, P2-12) — single source with CLI delete.
-    const { rows, lines: previewLines } = previewDeleteRows(db, args.ids);
+    const { rows, lines: previewLines, missing } = previewDeleteRows(db, args.ids);
 
     if (rows.length === 0) {
       return { content: [{ type: 'text', text: 'No observations found for given IDs.' }] };
@@ -969,6 +969,8 @@ server.registerTool(
 
     if (!args.confirm) {
       const lines = [`Preview: ${rows.length} observation(s) will be deleted:\n`, ...previewLines];
+      if (missing.length > 0)
+        lines.push(`\nNote: ID(s) ${missing.join(', ')} not found and will be skipped.`);
       lines.push(`\nCall mem_delete(ids=[...], confirm=true) to execute.`);
       return { content: [{ type: 'text', text: lines.join('\n') }] };
     }
@@ -978,7 +980,6 @@ server.registerTool(
     // with the CLI `delete` path (was inlined + kept in sync by parity comments).
     const result = deleteObservations(db, args.ids);
 
-    const missing = args.ids.filter((id) => !rows.some((r) => r.id === id));
     const msg = [`Deleted ${result.deleted} observation(s).`];
     if (result.recoveredChildren > 0)
       msg.push(`Recovered ${result.recoveredChildren} merged/compressed child observation(s) to live.`);