claude-mem-lite 5.1.1 → 5.3.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "5.1.1",
+      "version": "5.3.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.3.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/README.md

@@ -120,7 +120,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **Schema auto-migration** -- Idempotent `ALTER TABLE` migrations run on every startup, safely adding new columns and indexes without data loss
 - **LLM concurrency control** -- File-based semaphore limits background workers to 2 concurrent LLM calls, preventing resource contention
 - **stdin overflow protection** -- Hook input truncated at 256KB with regex-based action salvage for oversized tool outputs
-- **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/clear` or `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap
+- **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap. **The `/clear` and `/compact` arm does not currently fire** (tracked as R10-P1-1). The measurement, first: on the maintainer's own install `session_handoffs` holds 4 `exit` rows and **0** `clear` rows — the `clear` snapshot has never once been written. The mechanism, as a hypothesis: SessionStart treats a session file left on disk as the marker of a previous session that ended without `Stop` (`hook.mjs:2393-2405`, whose own comment reads "Normal `/exit` deletes the file, so this only triggers for `/clear`, `/compact`, or crash recovery"), and that file is exactly what `Stop` deletes (`hook.mjs:1542`) — which would make the branch unreachable if `Stop` runs at the end of every assistant turn rather than once per session. **That last clause is NOT verified**, and it is the whole question: the fix differs depending on whether Claude Code rotates its session id across `/clear`, so a real `/clear` stdin capture comes before any code change
 - **Git-SHA continuation anchor** (v2.31.0) -- Handoff rows include `git_sha_at_handoff`; any handoff matching the current `HEAD` counts as continuation regardless of TTL. Code state is a stronger continuation signal than wall-clock time
 - **Startup dashboard** (v2.31.0) -- SessionStart hook aggregates `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + most-recent exit handoff + recent event count into a single structured block injected via `hookSpecificOutput.additionalContext`
 - **Activity namespace** (v2.31.0) -- Dedicated `events` table + FTS5 for non-memdir types (`bugfix`, `lesson`, `bug`, `discovery`, `refactor`, `feature`, `observation`, `decision`) that don't compete with `WHAT_NOT_TO_SAVE` semantics on the observations table. CLI: `claude-mem-lite activity save|search|recent|show`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic. (v3.39: the `/lesson` and `/bug` slash commands were redirected from this events table to searchable **observations** — `mem_search` never read the events table, so explicit saves were unfindable; the events table remains the auto-capture activity log.)
@@ -431,7 +431,9 @@ FTS5 indexes: `observations_fts` (title, subtitle, narrative, text, facts, conce
 
 ```
 SessionStart
-  -> Generate session ID (or save handoff snapshot on /clear)
+  -> Generate session ID
+     (the /clear|/compact handoff branch here is currently unreachable — R10-P1-1,
+      see Cross-session handoff above)
   -> Mark stale sessions (>24h active) as abandoned
   -> Clean orphaned/stale lock files
   -> Query recent observations (24h)
@@ -458,8 +460,9 @@ UserPromptSubmit (two parallel paths)
 
 Stop
   -> Flush final episode buffer
-  -> Save handoff snapshot (on /exit)
+  -> Save handoff snapshot (type 'exit')
   -> Mark session completed
+  -> Delete the session file  <- what makes the SessionStart /clear branch unreachable
   -> Spawn LLM summary worker (poll-based wait)
 ```
 
@@ -796,6 +799,7 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `MEM_OR_FALLBACK_MAX_TOKENS` | Max query tokens allowed into the OR fallback (∈ [0,50]). | `8` |
 | `CLAUDE_MEM_CJK_PREC_MIN` | Precision floor for CJK segmentation candidates. | `0.2` |
 | `CLAUDE_MEM_AUTO_DEEP` | `0` disables automatic deep-search escalation (one Haiku call rewriting a weak query into keyword/concept/HyDE variants). Explicit `deep: true` still works. | _(auto)_ |
+| `CLAUDE_MEM_DEEP_DISCLOSURE` | `off` suppresses the one-line caveat appended to a multi-variant deep result. The caveat exists because deep search fills the page even when the corpus cannot answer — measured at 10 of 10 slots on queries whose answers had been removed (`benchmark/deep-search-holdout.mjs`) — and `deep` is AUTO by default on the MCP surface, i.e. it escalates precisely when the honest answer is "nothing". It does not change retrieval, ranking, or which rows are returned. | _(on)_ |
 | `CLAUDE_MEM_AUTO_DEEP_CLI` | `0` disables the same auto-escalation on the CLI path only. | _(auto)_ |
 | `CLAUDE_MEM_VECTORS` | `1` re-enables the persisted TF-IDF vector arm (off by default; also needs a vector rebuild via `maintain`). | _(off)_ |
 | `CLAUDE_MEM_SCOPE_FILTER` | `1` stops environment-scoped observations from firing on file-triggered recall. They stay reachable via search. **Leave it off**: on the face it gates, `environment` is not the low-relevance class its premise assumes — it cites at least as well as `project` (47.5% vs 44.3%, intervals overlapping), and an earlier measurement left 173 recall groups empty with it on. | _(off)_ |
@@ -823,7 +827,7 @@ what is already stored — only whether new work runs.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `CLAUDE_MEM_SKIP_SUMMARY` | Skip the LLM session summary at Stop. | _(runs)_ |
+| `CLAUDE_MEM_SKIP_SUMMARY` | Skip the background LLM session summary at **both** of its spawn sites — `Stop`, and the SessionStart `/clear`-handoff path. Until v5.3.0 only the `Stop` one honoured it. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_EPISODE_LLM` | Skip LLM extraction on episode flush — observations are still batched, just not summarized. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_SAVE_ENRICH` | Skip the background Haiku call that backfills `lesson_learned` / search aliases after a save. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_COMPRESS` | Skip auto-compression of old observations. | _(runs)_ |

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/deep-search.mjs

@@ -185,6 +185,66 @@ export function resolveDeepMode(explicitDeep, { surface, env = process.env } = {
   return surface === 'mcp' ? 'auto' : 'normal';
 }
 
+/**
+ * One-line disclosure for a deep result set, written to the channel the CALLER reads.
+ *
+ * D#3. benchmark/deep-search-holdout.mjs asks the suite's own queries of a corpus with
+ * their relevant_ids deleted, so the correct answer is zero rows and every returned row is
+ * a false positive by construction. It reads mean FP@10 = 10.00 across 12/12 queries: deep
+ * fills every slot, every time. The single-query baseline returns 1-2 rows on the same
+ * negatives — the flood is the UNION across paraphrase variants, which is also where deep's
+ * recall win comes from, so this is not a bug to be thresholded away. Three gates were
+ * tested against both arms and rejected; suppressing OR-fallback on rewrites takes deep
+ * R@10 from 0.7383 to 0.3962, because the vocab-mismatch win IS that fallback. rrfFuseN
+ * fuses by RANK, so no magnitude signal survives the merge for a downstream floor to read.
+ *
+ * The discrimination is not available at this layer, so the honest move is to hand the
+ * caller what the caller cannot otherwise see. Two things were missing:
+ *   1. `escalated` — that the widening happened BECAUSE the plain search was weak — was
+ *      announced on stderr only. On the MCP surface stderr never reaches the model, which
+ *      reads tool results; auto is the default there (resolveDeepMode, surface 'mcp'), so
+ *      the one caller who most needs the caveat was the one who could not see it.
+ *   2. Nothing said a full page can be entirely adjacent rows.
+ *
+ * Silent in two cases, and both silences are load-bearing:
+ *   - `variantCount <= 1`: with no usable rewrite, deep IS the baseline, and the existing
+ *     "== baseline" note already says so. Crying flood there would train callers to ignore
+ *     the line on the runs where it matters.
+ *   - `rowCount <= 0`: "rows above may be adjacent" is nonsense with no rows above, and
+ *     both zero-result faces ALREADY say the rewrite ran and found nothing — so the note
+ *     would restate the page's own conclusion in more words. Caught in pre-ship review,
+ *     which is also why `rowCount` is a parameter rather than a check in each face: two
+ *     surfaces deciding this separately is how they drift.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.escalated] the result came from auto-escalation, not an explicit ask
+ * @param {number} [opts.escalatedObsCount] hits the plain search returned before widening
+ * @param {number} [opts.variantCount] query variants fused (1 = rewrite produced nothing)
+ * @param {number} [opts.rowCount] rows actually shown to the caller
+ * @param {object} [opts.env=process.env] opt-out: CLAUDE_MEM_DEEP_DISCLOSURE=off
+ * @returns {string} the note, or '' when it should not be shown
+ */
+export function deepDisclosureNote({
+  escalated = false,
+  escalatedObsCount = 0,
+  variantCount = 0,
+  rowCount = 0,
+  env = process.env,
+} = {}) {
+  if (String(env.CLAUDE_MEM_DEEP_DISCLOSURE || '').toLowerCase() === 'off') return '';
+  if (!(variantCount > 1)) return '';
+  if (!(rowCount > 0)) return '';
+  const why = escalated
+    ? `auto-escalated after the plain search returned ${escalatedObsCount} hit(s)`
+    : 'explicitly requested';
+  return (
+    `[deep search: ${why}. Rows above may be ADJACENT to the query rather than answers to it — ` +
+    `on a corpus that cannot answer, the widened query still fills the page (measured: 10 of 10 ` +
+    `slots on queries whose answers had been removed). Judge each row by its own text; ` +
+    `"nothing here actually answers this" is a valid conclusion.]`
+  );
+}
+
 // Echoes hook-llm.mjs MEMORY_INPUT_GUARD (kept inline rather than imported so
 // this module — and the tests that import it — never pull in hook-llm's
 // native-heavy chain; see #8729). Same security intent: the query is untrusted.

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/hook.mjs

@@ -2038,8 +2038,15 @@ function saveHandoffAndFastSummary(
         .get(prevProject || project, 'clear', handoffScopeId);
     } catch {}
 
-    // Generate session summary for previous session (background Haiku — richer version)
-    spawnBackground('llm-summary', prevSessionId, prevProject || project);
+    // Generate session summary for previous session (background Haiku — richer version).
+    // Honours CLAUDE_MEM_SKIP_SUMMARY like the handleStop site does. This is the SAME
+    // worker, and the flag's whole purpose (see the comment at its other call site) is
+    // that llm-summary recreates a test's sandbox tree behind its cleanup — timed at
+    // 432ms there. Gating one of two call sites left the flag unable to do the one job
+    // it exists for whenever this branch is reached.
+    if (!process.env.CLAUDE_MEM_SKIP_SUMMARY) {
+      spawnBackground('llm-summary', prevSessionId, prevProject || project);
+    }
 
     // Build fast synchronous summary for immediate context availability.
     // Background llm-summary will produce a richer Haiku version later;

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

@@ -35,7 +35,13 @@ import {
   BROWSE_TIERS,
   BROWSE_TIER_LABELS,
 } from './lib/browse-core.mjs';
-import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
+import {
+  deepSearch,
+  resolveDeepMode,
+  shouldEscalateToDeep,
+  autoDeepLlmReady,
+  deepDisclosureNote,
+} from './deep-search.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import {
   runMaintainOps,
@@ -45,6 +51,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).
@@ -432,6 +439,19 @@ async function cmdSearch(db, args, { llm } = {}) {
         : '[mem] Deep search: rerank produced no usable order; kept fused order\n',
     );
   }
+  // D#3. Same disclosure the MCP surface puts in its payload, on the channel this face
+  // already uses for deep notes — a Bash caller reads stderr alongside stdout, so unlike
+  // MCP there is no split here. One home for the text (deep-search.mjs) because two faces
+  // writing their own wording is this repo's most-paid-for defect class.
+  if (isDeep) {
+    const disclosure = deepDisclosureNote({
+      escalated: res.escalated,
+      escalatedObsCount: res.escalatedObsCount,
+      variantCount: deepVariants?.length ?? 0,
+      rowCount: paged?.length ?? 0,
+    });
+    if (disclosure) process.stderr.write(`${disclosure}\n`);
+  }
 
   // "nothing matched" (no offset) vs "this page is empty" (with offset) — the two
   // CLI messages. preFinalizeCount is the pre-pagination population (post-tier).
@@ -1898,7 +1918,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 +1928,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 +1937,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 +2518,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 +2545,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 +2614,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 +3219,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.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "5.1.1",
+      "version": "5.3.0",
       "os": [
         "darwin",
         "linux"

package/package.json

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

@@ -10,7 +10,13 @@ import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDbWithWalRecovery, DB_PATH, DB_DIR } from './schema.mjs';
 import { reRankWithContext, runIdleCleanup, buildServerInstructions } from './search-scoring.mjs';
 import { searchObservationsHybrid } from './search-engine.mjs';
-import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
+import {
+  deepSearch,
+  resolveDeepMode,
+  shouldEscalateToDeep,
+  autoDeepLlmReady,
+  deepDisclosureNote,
+} from './deep-search.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import {
   resolveAnchorToken,
@@ -577,6 +583,18 @@ async function runSearchPipeline(db, args, { llm, rerankLlm } = {}) {
   if (r.reranked && output.content?.[0]?.type === 'text') {
     output.content[0].text += '\n\n[deep search: LLM-reranked the top candidates by relevance]';
   }
+  // D#3. The stderr line above is for humans and logs; an MCP client reads the tool RESULT,
+  // so the escalation fact and the adjacency caveat have to land in the payload or the one
+  // caller running deep=auto by default never sees either.
+  if (r.isDeep && output.content?.[0]?.type === 'text') {
+    const disclosure = deepDisclosureNote({
+      escalated: r.escalated,
+      escalatedObsCount: r.escalatedObsCount,
+      variantCount: r.variants?.length ?? 0,
+      rowCount: r.page?.length ?? 0,
+    });
+    if (disclosure) output.content[0].text += `\n\n${disclosure}`;
+  }
   appendDeferredTrailer(output);
 
   // Expose structured fields for tests + the MCP content blob.
@@ -961,7 +979,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 +987,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 +998,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.`);