claude-mem-lite 5.2.0 → 5.3.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "5.2.0",
+      "version": "5.3.1",
       "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.2.0",
+  "version": "5.3.1",
   "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/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.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/lib/maintain-core.mjs

@@ -394,6 +394,21 @@ export function cleanupBroken(db, { projectFilter, baseParams, opCap = OP_CAP })
       -- lesson). Parity with the "lessons never auto-GC" guards in
       -- decayAndMarkIdle / selectCompressionCandidates / findSmartCompressCandidates.
       AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
+      -- D#4. The one HARD DELETE in this family, and until now the only site whose
+      -- exemption from liveObsFilterSql was a LIKELIHOOD argument rather than an
+      -- inertness proof: these rows have no title, narrative or lesson, so they are
+      -- absent from every injection surface, so an id that was never injected is not one
+      -- a #NN cites. Narrow, but reachable -- a hand-typed #NN, or a numeric
+      -- "save --supersedes" chain later blanked by a degenerate cluster-merge -- and what
+      -- the delete takes with it is the superseded_by that
+      -- citation-tracker.redirectSupersededIds (:1363) follows to credit a corrected
+      -- memory's #NN to its successor.
+      --
+      -- Deliberately NOT the full liveObsFilterSql. A retired row whose superseded_by is
+      -- null hands that redirect nothing: it falls through to out.add(id) (:1379-1381),
+      -- the same answer a missing row produces. Filtering on superseded_at instead would
+      -- strand every empty retired row here forever for no gain.
+      AND superseded_by IS NULL
       ${projectFilter} LIMIT ${opCap}
   `,
     )

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,
@@ -433,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).

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "5.2.0",
+  "version": "5.3.1",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/hook-launcher.mjs

@@ -124,12 +124,23 @@ if (!entryArg) {
 
 const entryAbs = entryArg.startsWith('/') ? entryArg : join(INSTALL_DIR, entryArg);
 
-// Swap barrier. An auto-update / repair renames files into the install dir one at
-// a time — atomic per file, not per file SET — so a hook process that starts
-// mid-swap can resolve its entry from the old version and an import from the new
-// one. hook-update.mjs marks that window; skip the fire instead of importing a
-// mixed module graph. Hooks are best-effort and the swap lasts ~a second, so the
-// next fire runs against a settled install.
+// Swap barrier. An auto-update renames files into the install dir one at a time —
+// atomic per file, not per file SET — so a hook process that starts mid-swap can
+// resolve its entry from the old version and an import from the new one.
+// hook-update.mjs marks that window; skip the fire instead of importing a mixed
+// module graph. Hooks are best-effort and the swap lasts ~a second, so the next
+// fire runs against a settled install.
+//
+// This covers the AUTO-UPDATE path only, and the distinction is not pedantic:
+// `hook-update.mjs:719` is the sole writer of this marker in the whole tree (name set,
+// 2026-09-07), so the barrier is never armed for `install.mjs install` — which copies the
+// same file set in place with copyFileSync (`install.mjs:341-350`) and is what
+// `install.mjs repair` ends up executing (`:2388`, after verifying the release). A repair
+// spawned in the background at SessionStart therefore overwrites this tree while hooks
+// keep firing into it. That is R10 P2-12, still open: the mechanism is settled, the runtime
+// symptom is not reproduced, and R10 §8 asks for a repro in tests/sandbox/phaseB-npm.mjs
+// before install()'s main path is touched. An earlier draft of this comment said "auto-update
+// / repair", which reads as though the repair path were already covered — it is not.
 //
 // Stale-guarded on BOTH pid and ts: an updater killed mid-swap leaves the marker
 // behind, and a marker that outlives its writer must never mute hooks permanently.

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.