claude-mem-lite 5.3.1 → 5.5.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "5.3.1",
+      "version": "5.5.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.3.1",
+  "version": "5.5.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 `/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
+- **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 fires since v5.4.0** (R10-P1-1); before that it had never once written a row — `session_handoffs` on the maintainer's install held 4 `exit` rows and **0** `clear` rows. Two host facts settled it, both measured rather than assumed. (1) `Stop` runs at the end of every assistant *turn*, not once per session, and it deleted the session file that SessionStart reads to learn which session just ended — so the branch was unreachable, and mem sessions were minted per turn (58 prompts over 16 host sessions produced 56 mem sessions and 56 summary rows, 2026-09-07). (2) Claude Code **rotates its session id across `/clear`**: of 21 real transcripts, 12 carry a `/clear` command record, and in 12/12 that record's timestamp precedes its own file's first record by ~0.1s — the command is issued in the old session and replayed into a new file under a new id. So `Stop` no longer deletes the file, SessionStart asks the host's `source` (`startup`/`clear`/`compact`/`resume`) instead of guessing from the file, and the handoff's prompt lookup falls back to the unscoped set when the new session's id matches none. Revert path: `CLAUDE_MEM_LEGACY_STOP_UNLINK=1`
 - **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,9 +431,10 @@ FTS5 indexes: `observations_fts` (title, subtitle, narrative, text, facts, conce
 
 ```
 SessionStart
-  -> Generate session ID
-     (the /clear|/compact handoff branch here is currently unreachable — R10-P1-1,
-      see Cross-session handoff above)
+  -> Read the host's `source` (startup | clear | compact | resume) from stdin
+  -> On clear/compact: read the outgoing session from the session file, save its
+     'clear' handoff, emit the Working State block  (R10-P1-1, fixed v5.4.0)
+  -> Generate session ID (overwrites the session file)
   -> Mark stale sessions (>24h active) as abandoned
   -> Clean orphaned/stale lock files
   -> Query recent observations (24h)
@@ -462,8 +463,9 @@ Stop
   -> Flush final episode buffer
   -> 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)
+  -> Keep the session file  <- Stop fires per TURN; deleting it here re-minted a mem
+     session every turn and left the SessionStart /clear branch unreachable (v5.4.0)
 ```
 
 
@@ -800,6 +802,7 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `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_REACH_DISCLOSURE` | `off` suppresses the one-line note that fires when a search's reported `total` exceeds what its pagination can hand back. The candidate pool is sized from `limit` alone and deliberately does not grow with `offset` (D#30 — an offset-scaled pool re-ranks its own prefix under RRF, so pages overlapped and gapped), while `total` is the full match count. Measured on a 128-row corpus: at the default limit of 20 the last non-empty offset is 59, so 60 of 128 rows are unreachable at any offset. The note reports that; 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)_ |
@@ -828,6 +831,7 @@ what is already stored — only whether new work runs.
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `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_LEGACY_STOP_UNLINK` | Restore the pre-v5.4.0 behaviour where `Stop` deletes the session file. Documented revert path for the session-lifecycle change, not a supported configuration: it re-mints a mem session per turn and makes the `/clear` handoff unreachable again. Only reach for it on a host that fires `Stop` once per session rather than once per turn. | _(file kept)_ |
 | `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/hook-handoff.mjs

@@ -56,25 +56,35 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   // scopeSessionId is absent or == sessionId (legacy/test/no-stdin), fall back to the
   // unfiltered query (identical to pre-D#26 behavior).
   const ccScope = scopeSessionId && scopeSessionId !== sessionId ? scopeSessionId : null;
-  const prompts = ccScope
-    ? db
-        .prepare(
-          `
+  const unscopedPrompts = () =>
+    db
+      .prepare(
+        `
         SELECT prompt_text FROM user_prompts
-        WHERE content_session_id = ? AND (cc_session_id = ? OR cc_session_id IS NULL)
+        WHERE content_session_id = ?
         ORDER BY prompt_number ASC LIMIT 5
       `,
-        )
-        .all(sessionId, ccScope)
-    : db
+      )
+      .all(sessionId);
+  let prompts = ccScope
+    ? db
         .prepare(
           `
         SELECT prompt_text FROM user_prompts
-        WHERE content_session_id = ?
+        WHERE content_session_id = ? AND (cc_session_id = ? OR cc_session_id IS NULL)
         ORDER BY prompt_number ASC LIMIT 5
       `,
         )
-        .all(sessionId);
+        .all(sessionId, ccScope)
+    : unscopedPrompts();
+  // R10-P1-1: on the /clear path the scope is the NEW session's CC id while the prompts
+  // being handed off belong to the OLD one, and the host rotates that id across /clear
+  // (measured 12/12 on real transcripts, 2026-09-07) — so the scoped query returns 0 and
+  // the whole handoff was silently skipped. Fall back to the unscoped set when, and only
+  // when, the scoped one is EMPTY: D#26 exists to stop two live sessions being MERGED into
+  // one working_on, and there is nothing to merge with when this session contributed no
+  // prompts. The alternative at that point is not a cleaner row, it is no row at all.
+  if (ccScope && prompts.length === 0) prompts = unscopedPrompts();
   if (prompts.length === 0) return; // Empty session — nothing to hand off
 
   // Filter prompts whose only content is workflow/control language ("继续",

package/hook-optimize.mjs

@@ -102,7 +102,7 @@ export function rebuildVector(db, obsId, textPartsOrRow) {
  *
  * @param {object} db better-sqlite3 database handle
  * @param {number} limit max candidates to return
- * @param {{ scope?: 'narrow' | 'wide' | 'aliases' | 'scopes', project?: string }} [opts] Optional project filter (e.g. inferProject()-resolved name) narrows candidates to a single project — opt-in to preserve prior cross-project default.
+ * @param {{ scope?: 'narrow' | 'wide' | 'aliases' | 'scopes' | 'concepts', project?: string }} [opts] Optional project filter (e.g. inferProject()-resolved name) narrows candidates to a single project — opt-in to preserve prior cross-project default.
  */
 export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', project } = {}) {
   const projectClause = project ? 'AND project = ?' : '';
@@ -154,6 +154,39 @@ export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', proje
     `);
     return project ? stmt.all(project, limit) : stmt.all(limit);
   }
+  if (scope === 'concepts') {
+    // D#6 concepts backfill: substantive rows with no concepts, REGARDLESS of lesson,
+    // aliases or scope. Same shape and same reason as the two pools above, one column
+    // over — and this one exists because the P1-2 fix created it. save-enrich fires on
+    // every successful manual save and writes search_aliases (always) + lesson_learned
+    // (bugfix/decision) + scope, which are precisely narrow's, wide's, aliases' and
+    // scopes' predicates, so a save-enriched row matches NONE of the four and never
+    // receives concepts. Measured on the real DB 2026-09-07: 14/14 live observations
+    // conceptless, 14/14 with aliases, 0/14 with optimized_at, all four pools empty.
+    //
+    // Keyed on `concepts` ALONE, not on concepts+facts: idempotency here is "the column
+    // this pass fills becomes non-empty", the same contract aliases and scopes carry. A
+    // facts term in the predicate would re-select forever every row whose narrative
+    // yields no extractable fact.
+    //
+    // Deliberately NOT gated on optimized_at, for the reason the alias branch gives and
+    // one more: the general pass preserves-on-empty, so a re-enrich whose model returned
+    // no concepts leaves the row stamped AND conceptless. Gating on the stamp would
+    // strand exactly those rows — the R10 P2-2 shape, where one pass's bookkeeping
+    // evicts a row from a backfill it never visited.
+    const stmt = db.prepare(`
+      SELECT id, title, narrative, type, subtitle, concepts, facts, text, importance, project
+      FROM observations
+      WHERE ${liveObsFilterSql('')}
+        AND (concepts IS NULL OR concepts = '')
+        AND LENGTH(COALESCE(narrative, '')) > 100
+        AND ${notLowSignalTitleClause('')}
+        ${projectClause}
+      ORDER BY created_at_epoch DESC
+      LIMIT ?
+    `);
+    return project ? stmt.all(project, limit) : stmt.all(limit);
+  }
   if (scope === 'wide') {
     const stmt = db.prepare(`
       SELECT id, title, narrative, type, subtitle, concepts, facts, search_aliases, importance, project
@@ -298,9 +331,23 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
         // scope rides this call for free (D#135 P3). COALESCE, not a plain set:
         // an omitted or off-enum value normalizes to null and must not erase a
         // classification an earlier face already wrote.
-        db.prepare(
-          `UPDATE observations SET search_aliases = ?, text = ?, scope = COALESCE(?, scope) WHERE id = ?`,
-        ).run(safe.search_aliases, safe.text, normalizeScope(parsed.scope), cand.id);
+        // D#12: the live-row guard, on the WHERE and not merely on the SELECT that chose
+        // the row. The Haiku call above is up to BG_LLM_TIMEOUT_MS (45 s), long enough for
+        // a concurrent hook to supersede or auto-compress this row — R10 P3-3's finding,
+        // fixed then on the general branch only and carried by the concepts branch since
+        // D#6. This was the one branch of the four without it. `changes === 0` is a SKIP,
+        // not a success: it must not count as processed and must not rebuild a vector for
+        // a row that is no longer live.
+        const res = db
+          .prepare(
+            `UPDATE observations SET search_aliases = ?, text = ?, scope = COALESCE(?, scope)
+             WHERE id = ? AND ${liveObsFilterSql('')}`,
+          )
+          .run(safe.search_aliases, safe.text, normalizeScope(parsed.scope), cand.id);
+        if (res.changes === 0) {
+          skipped++;
+          continue;
+        }
         // Refresh the TF-IDF vector from the just-updated FTS text so the new
         // aliases reach the vector arm too — the narrow/wide branch rebuilds, this
         // one must as well. No-ops when the vector arm is off / vocab unbuilt.
@@ -308,6 +355,69 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
         processed++;
         continue;
       }
+      if (scope === 'concepts') {
+        // Concepts-only backfill (D#6). Writes concepts + facts and APPENDS them to the
+        // existing FTS text — never rebuilds it, for the reason the alias branch gives:
+        // a rebuild from concepts/facts drops the original narrative and alias terms and
+        // regresses recall. Never touches the user's curated title / narrative / lesson /
+        // type / importance, and never stamps optimized_at, so the wide pass keeps its
+        // own candidates exactly as the alias and scopes passes leave them.
+        const conceptsPrompt = `Extract search concepts and concrete facts from this coding memory. Return ONLY valid JSON, no markdown fences.
+
+Title: ${truncate(cand.title || '(untitled)', 200)}
+Narrative: ${truncate(cand.narrative || '(no narrative)', 500)}
+
+JSON: {"concepts":["kw1","kw2"],"facts":["specific fact 1","specific fact 2"]}
+concepts: 3-8 short keyword phrases naming what this memory is ABOUT (systems, components, error classes, techniques).
+facts: 1-4 specific, checkable statements the narrative actually asserts. Omit rather than invent.`;
+        const parsed = await callModelJSONAsync(conceptsPrompt, 'haiku', {
+          timeout: BG_LLM_TIMEOUT_MS,
+          maxTokens: 300,
+        });
+        const pickStrings = (v) =>
+          Array.isArray(v) ? v.filter((s) => typeof s === 'string' && s.trim().length > 0) : [];
+        const conceptArr = pickStrings(parsed && parsed.concepts);
+        // No concepts is a SKIP, not an empty write: writing '' would leave the row in
+        // this pool forever, and the pass would burn one Haiku call per cycle on it.
+        if (!conceptArr.length) {
+          skipped++;
+          continue;
+        }
+        const factArr = pickStrings(parsed && parsed.facts);
+        const conceptsOnly = conceptArr.slice(0, 10).join(' ');
+        const factsOnly = factArr.slice(0, 10).join(' ');
+        const appendedText = [
+          cand.text || '',
+          conceptsOnly,
+          factsOnly,
+          cjkBigrams(`${conceptsOnly} ${factsOnly}`),
+        ]
+          .filter(Boolean)
+          .join(' ');
+        const safe = scrubRecord('observations', {
+          concepts: conceptsOnly,
+          facts: factsOnly,
+          text: appendedText,
+        });
+        // Fill-only-empty on `concepts` plus the live-row guard, both on the WHERE and
+        // not merely on the SELECT: the round-trip above is up to 45 s, long enough for a
+        // concurrent hook to supersede or compress the row (R10 P3-3) or for save-enrich
+        // to fill it. `facts` rides along with preserve-on-empty for the same reason the
+        // general pass preserves it — a partial answer must not wipe a filled column.
+        const res = db
+          .prepare(
+            `UPDATE observations SET concepts = ?, facts = COALESCE(NULLIF(?, ''), facts), text = ?
+             WHERE id = ? AND (concepts IS NULL OR concepts = '') AND ${liveObsFilterSql('')}`,
+          )
+          .run(safe.concepts, safe.facts, safe.text, cand.id);
+        if (res.changes === 0) {
+          skipped++;
+          continue;
+        }
+        rebuildVector(db, cand.id, [safe.text]);
+        processed++;
+        continue;
+      }
       const prompt = `Re-enrich this observation with structured metadata. Return ONLY valid JSON, no markdown fences.
 
 Title: ${truncate(cand.title || '(untitled)', 200)}
@@ -336,9 +446,24 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
       // hide a real observation until manual surgery. In wide scope, fall through and let
       // clampImportance floor it to 1 (kept visible, low-ranked) instead of hiding.
       if ((parsed.importance === 0 || parsed.importance === '0') && scope !== 'wide') {
-        db.prepare(
-          `UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}, optimized_at = ? WHERE id = ?`,
-        ).run(Date.now(), cand.id);
+        // D#12, and this one is not a stale-write guard — it is a POINTER guard.
+        // `compressed_into` is the child -> keeper link, and COMPRESSED_AUTO is -1. If a
+        // concurrent cluster-merge or smart-compress adopts this row during the 45 s Haiku
+        // call, it holds a POSITIVE keeper id; overwriting that with -1 does not merely
+        // stamp a dead row, it destroys the link — lib/maintain-core.mjs:316 recovers
+        // orphans with `compressed_into > 0`, and recoverChildrenOf follows the same id.
+        // The sibling write in lib/maintain-core.mjs:631 already carries this predicate,
+        // so the codebase had decided the question and this site had not been updated.
+        const res = db
+          .prepare(
+            `UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}, optimized_at = ?
+             WHERE id = ? AND ${liveObsFilterSql('')}`,
+          )
+          .run(Date.now(), cand.id);
+        if (res.changes === 0) {
+          skipped++;
+          continue;
+        }
         processed++;
         continue;
       }
@@ -1016,6 +1141,52 @@ export function clusterForCompression(candidates, db) {
   return clusters;
 }
 
+/**
+ * The smart-compress prompt. Exported so a RULER can measure the shipped text.
+ *
+ * Extracted for benchmark/compress-veto-rate.mjs (D#10). It has to be one string in one
+ * place: a ruler that retypes the prompt measures its own copy, which is exactly how
+ * tests/handoff-simulation.test.mjs came to assert on a re-implementation while the real
+ * hook emitted a block no user had ever seen.
+ *
+ * D#10. This prompt used to OPEN with "Summarize these related code memory observations",
+ * asserting the premise it should have been testing, and the only bail was a missing title
+ * — so the model had no way to refuse. The sibling executeMergeCluster has had
+ * `should_merge` since it was written; these two LLM cluster paths disagreed about whether
+ * the model may say no, and this is the one that HIDES its inputs (compressed_into removes
+ * them from every injection and search surface and puts them out of recoverBuriedLessons'
+ * reach).
+ *
+ * It matters because the upstream relatedness check is not always on:
+ * clusterForCompression only computes cosine similarity when getVocabulary returns a
+ * vocabulary, and that is null whenever the vector arm is off — which is the default
+ * (CLAUDE_MEM_VECTORS !== '1'). The else branch groups by a 14-day window ALONE. Measured
+ * with a control arm 2026-09-07: three unrelated observations over 12 days form 1 cluster
+ * with the arm off and 0 with it on. Until that branch is decided (D#10 option a), this
+ * veto is the only thing standing between the heuristic and an unattended write that hides
+ * real rows.
+ *
+ * @param {Array<object>} observations cluster members
+ * @returns {string}
+ */
+export function buildCompressPrompt(observations) {
+  const obsDescriptions = observations
+    .map(
+      (o, i) =>
+        `${i + 1}. [${o.type || 'change'}] "${truncate(o.title || '(untitled)', 200)}" — ${truncate(o.narrative || '(no narrative)', 500)}${o.lesson_learned ? ` | Lesson: ${truncate(o.lesson_learned, 200)}` : ''}`,
+    )
+    .join('\n');
+
+  return `These code memory observations were grouped by a heuristic that may be wrong. FIRST decide whether they are one story worth collapsing into a single memory. Return ONLY valid JSON.
+
+Observations:
+${obsDescriptions}
+
+JSON: {"should_compress":true,"title":"descriptive summary ≤120 chars","narrative":"comprehensive summary ≤800 chars preserving key decisions and lessons","concepts":["kw1","kw2"],"facts":["all specific facts preserved"],"lesson_learned":"most important synthesized lesson or 'none'","search_aliases":["alt search 1","alt search 2"]}
+should_compress: false when these are about unrelated systems, files or problems, or when a merged summary would lose more than it saves. Compressing HIDES the originals from search, so refuse when in doubt. When false, the other fields are ignored.
+When true: preserve all important decisions, lessons, and specific facts.`;
+}
+
 export async function executeSmartCompressCluster(db, observations, project) {
   if (observations.length < 3) return { compressed: false };
 
@@ -1023,25 +1194,18 @@ export async function executeSmartCompressCluster(db, observations, project) {
   if (!gotSlot) return { compressed: false };
 
   try {
-    const obsDescriptions = observations
-      .map(
-        (o, i) =>
-          `${i + 1}. [${o.type || 'change'}] "${truncate(o.title || '(untitled)', 200)}" — ${truncate(o.narrative || '(no narrative)', 500)}${o.lesson_learned ? ` | Lesson: ${truncate(o.lesson_learned, 200)}` : ''}`,
-      )
-      .join('\n');
-
-    const prompt = `Summarize these related code memory observations into ONE comprehensive summary. Preserve all important decisions, lessons, and specific facts. Return ONLY valid JSON.
-
-Observations:
-${obsDescriptions}
-
-JSON: {"title":"descriptive summary ≤120 chars","narrative":"comprehensive summary ≤800 chars preserving key decisions and lessons","concepts":["kw1","kw2"],"facts":["all specific facts preserved"],"lesson_learned":"most important synthesized lesson or 'none'","search_aliases":["alt search 1","alt search 2"]}`;
+    const prompt = buildCompressPrompt(observations);
 
     const parsed = await callModelJSONAsync(prompt, 'sonnet', {
       timeout: BG_LLM_TIMEOUT_MS,
       maxTokens: 1000,
     });
-    if (!parsed || !parsed.title) return { compressed: false };
+    // Fail CLOSED, exactly as `should_merge` does: an omitted verdict refuses. The two
+    // failure directions are not symmetric — refusing wrongly means a compression did not
+    // happen, proceeding wrongly means unrelated observations were hidden from every
+    // surface. On a path that hides its inputs, silence is not consent.
+    if (!parsed || !parsed.should_compress) return { compressed: false };
+    if (!parsed.title) return { compressed: false };
 
     // Scrub BEFORE truncate (see re-enrich note): boundary cut on scrubbed text.
     const title = truncate(scrubSecrets(parsed.title || ''), 120);
@@ -1193,6 +1357,11 @@ export function optimizePreview(db, { project, detail = false } = {}) {
   // lesson_learned per row, so counting by materialising was the one place this
   // round pulled megabytes to print an integer. (pre-tag review NOTE 11)
   const reenrichScopes = countReenrichCandidates(db, 'scopes', project);
+  // D#6: the concepts-backfill backlog. Reported for the same reason as the three
+  // above — a pool whose size is invisible cannot be sized for a one-shot drain
+  // (`optimize --run --task re-enrich --scope concepts --max N`), and this pool is
+  // the one that holds every save-enriched manual save.
+  const reenrichConcepts = findReenrichCandidates(db, 5000, { scope: 'concepts', project }).length;
 
   const concepts = extractUniqueConcepts(db, 500, { project });
   const normalizeReady = shouldRunNormalize(project) && concepts.length >= 5;
@@ -1209,6 +1378,7 @@ export function optimizePreview(db, { project, detail = false } = {}) {
     reenrichWide,
     reenrichAliases,
     reenrichScopes,
+    reenrichConcepts,
     normalize: normalizeReady ? concepts.length : 0,
     normalizeGateOpen: shouldRunNormalize(project),
     clusterMerge,
@@ -1240,7 +1410,7 @@ export function optimizePreview(db, { project, detail = false } = {}) {
  *   is budgeted separately, up to the re-enrich slice again — see the rationale at
  *   the call site. Its calls are enum-classification only (maxTokens 60).
  * @param {boolean} [opts.force=false] Bypass time-based gates (e.g. normalize interval).
- * @param {'narrow'|'wide'|'aliases'} [opts.reenrichScope='narrow'] Scope for the re-enrich task.
+ * @param {'narrow'|'wide'|'aliases'|'concepts'} [opts.reenrichScope='narrow'] Scope for the re-enrich task.
  *   'wide' targets bugfix/refactor/feature/decision with narrative but no lesson (R-7).
  *   'aliases' (P1) backfills search_aliases on substantive alias-less rows regardless
  *   of lesson (lesson-bearing manual saves) — adds ONLY aliases, never rewrites content.
@@ -1295,16 +1465,32 @@ export async function optimizeRun(
             //     mis-prices it by an order of magnitude.
             // Cap is budget.reenrich, so the daily pass adds at most that many cheap
             // classification calls and an empty pool still costs nothing.
+            //
+            // D#6 adds a FOURTH claimant, 'concepts', and it SHARES the aliases half
+            // rather than taking one of its own. Sharing keeps the boundary this comment
+            // already describes: the main scope still gets at least half the budget, so
+            // adding a pool cannot starve the lesson enrichment that is the point of the
+            // pass. Aliases is served FIRST out of that shared half, on a stated
+            // ordering: an alias-less row is paraphrase-UNFINDABLE (a recall zero),
+            // while a conceptless row is findable and merely ranks worse — measured at
+            // +0.0846 R@10 on the benchmark fixture, which is real but is not a zero.
+            // Both pools drain (each is idempotent via the column it fills), so the
+            // ordering decides which drains first, not which gets served at all.
             const half = Math.max(1, Math.floor(budget.reenrich / 2));
             const aliasBudget = Math.min(
               half,
               findReenrichCandidates(db, half, { scope: 'aliases', project }).length,
             );
+            const conceptsBudget = Math.min(
+              half - aliasBudget,
+              findReenrichCandidates(db, Math.max(0, half - aliasBudget), { scope: 'concepts', project })
+                .length,
+            );
             const scopesBudget = Math.min(
               budget.reenrich,
               findReenrichCandidates(db, budget.reenrich, { scope: 'scopes', project }).length,
             );
-            const mainRes = await executeReenrich(db, budget.reenrich - aliasBudget, {
+            const mainRes = await executeReenrich(db, budget.reenrich - aliasBudget - conceptsBudget, {
               scope: reenrichScope,
               project,
             });
@@ -1312,14 +1498,31 @@ export async function optimizeRun(
               aliasBudget > 0
                 ? await executeReenrich(db, aliasBudget, { scope: 'aliases', project })
                 : { processed: 0, skipped: 0 };
+            const conceptsRes =
+              conceptsBudget > 0
+                ? await executeReenrich(db, conceptsBudget, { scope: 'concepts', project })
+                : { processed: 0, skipped: 0 };
             const scopesRes =
               scopesBudget > 0
                 ? await executeReenrich(db, scopesBudget, { scope: 'scopes', project })
                 : { processed: 0, skipped: 0 };
             results.reenrich = {
-              processed: (mainRes.processed || 0) + (aliasRes.processed || 0) + (scopesRes.processed || 0),
-              skipped: (mainRes.skipped || 0) + (aliasRes.skipped || 0) + (scopesRes.skipped || 0),
-              byScope: { [reenrichScope]: mainRes, aliases: aliasRes, scopes: scopesRes },
+              processed:
+                (mainRes.processed || 0) +
+                (aliasRes.processed || 0) +
+                (conceptsRes.processed || 0) +
+                (scopesRes.processed || 0),
+              skipped:
+                (mainRes.skipped || 0) +
+                (aliasRes.skipped || 0) +
+                (conceptsRes.skipped || 0) +
+                (scopesRes.skipped || 0),
+              byScope: {
+                [reenrichScope]: mainRes,
+                aliases: aliasRes,
+                concepts: conceptsRes,
+                scopes: scopesRes,
+              },
             };
           } else {
             results.reenrich = await executeReenrich(db, budget.reenrich, { scope: reenrichScope, project });

package/hook.mjs

@@ -1537,10 +1537,32 @@ async function handleStop() {
   // recreate at 432ms and watched a 300ms grace lose.
   if (!process.env.CLAUDE_MEM_SKIP_SUMMARY) spawnBackground('llm-summary', sessionId, project);
 
-  // Clean session file AFTER spawning background
-  try {
-    unlinkSync(sessionFile());
-  } catch {}
+  // The session file deliberately SURVIVES Stop (R10-P1-1). It used to be unlinked here,
+  // on the model "Stop = /exit = the session is over". The host does not work that way:
+  // Stop fires at the end of EVERY assistant turn, so the unlink minted a fresh mem
+  // session on the next event and cost two things at once —
+  //
+  //   • `sdk_sessions` / `session_summaries` counted turns, not sessions. Measured on the
+  //     maintainer's live DB 2026-09-07: 58 prompts over 16 host sessions produced 56
+  //     distinct mem sessions and 56 summary rows, 0 of which carried the LLM-only fields.
+  //   • handleSessionStart's mid-restart probe reads this file to learn which session just
+  //     ended. With it deleted every turn the probe never fired, so the /clear handoff
+  //     branch was unreachable in production — 0 `clear` rows against 21 real sessions.
+  //
+  // Lifetime is bounded by SESSION_EXPIRY_MS (12h) in getSessionId(), and every
+  // SessionStart overwrites it via createSessionId(), so "one mem session per host
+  // session" holds without anything having to delete it.
+  //
+  // CLAUDE_MEM_LEGACY_STOP_UNLINK=1 restores the pre-v5.4.0 unlink. It exists because the
+  // measurements above are from ONE host build; a host that fires Stop once per session
+  // instead of once per turn would be better served by the old shape, and a user who hits
+  // that has no other lever. It is not a supported configuration — it re-breaks the /clear
+  // handoff by design.
+  if (process.env.CLAUDE_MEM_LEGACY_STOP_UNLINK === '1') {
+    try {
+      unlinkSync(sessionFile());
+    } catch {}
+  }
 }
 
 // ─── SessionStart Handler + CLAUDE.md Persistence (Tier 1 A, E) ─────────────
@@ -2336,13 +2358,20 @@ async function handleSessionStart() {
 
   // Read CC real session_id from hook stdin — used to scope handoff rows so parallel
   // sessions for the same project don't clobber each other (see docs/bug.txt).
+  // `source` (startup | clear | compact | resume) is read here too: since Stop stopped
+  // deleting the session file, the file's survival no longer tells us WHY this session
+  // started, and the host's own word is the only non-guess (R10-P1-1).
   let ccSessionId = null;
+  let startSource = null;
   try {
     const raw = await readStdin();
     const hookData = JSON.parse(raw.text);
     if (typeof hookData?.session_id === 'string' && hookData.session_id.length > 0) {
       ccSessionId = hookData.session_id;
     }
+    if (typeof hookData?.source === 'string' && hookData.source.length > 0) {
+      startSource = hookData.source;
+    }
   } catch {
     /* stdin unavailable — legacy behavior */
   }
@@ -2390,19 +2419,32 @@ async function handleSessionStart() {
     }
   }
 
-  // Detect mid-session restart (/clear or /compact): if a recent session file exists,
-  // the previous session ended without Stop hook firing. Read BEFORE createSessionId()
-  // overwrites the session file. Normal /exit deletes the file, so this only triggers
-  // for /clear, /compact, or crash recovery.
+  // Detect mid-session restart (/clear or /compact) and carry the ending session forward.
+  // Read BEFORE createSessionId() overwrites the session file.
+  //
+  // The discriminator is the host's `source`, NOT the session file's survival. The old
+  // comment here read "normal /exit deletes the file, so this only triggers for /clear,
+  // /compact, or crash recovery" — but the deleter was Stop, which fires every turn, so
+  // the file was always gone and this branch never triggered (R10-P1-1). Now that Stop
+  // keeps the file, the file is always THERE, and asking it "why did this session start"
+  // would answer /clear for a plain launch too. Only the host knows.
+  //
+  // `startup` and `resume` mean the previous session ended on its own terms and already
+  // wrote its per-turn `exit` handoff, which UserPromptSubmit reads back — no clear
+  // snapshot is owed. A null source (no stdin: tests, legacy hosts) keeps the old
+  // file-presence behavior so nothing that used to reach this branch stops reaching it.
+  const isMidSessionRestart = startSource !== 'startup' && startSource !== 'resume';
   let prevSessionId = null;
   let prevProject = null;
-  try {
-    const data = JSON.parse(readFileSync(sessionFile(), 'utf8'));
-    if (Date.now() - data.startedAt < SESSION_EXPIRY_MS) {
-      prevSessionId = data.id;
-      prevProject = data.project;
-    }
-  } catch {} // No session file = fresh startup, nothing to recover
+  if (isMidSessionRestart) {
+    try {
+      const data = JSON.parse(readFileSync(sessionFile(), 'utf8'));
+      if (Date.now() - data.startedAt < SESSION_EXPIRY_MS) {
+        prevSessionId = data.id;
+        prevProject = data.project;
+      }
+    } catch {} // No session file = fresh startup, nothing to recover
+  }
 
   // Tier 1 A: Create unique session ID
   const sessionId = createSessionId();

package/install.mjs

@@ -509,7 +509,7 @@ function registerMcpServer() {
   }
 }
 
-function dedupePluginCacheAndHooks({ managedHooks } = {}) {
+export function dedupePluginCacheAndHooks({ managedHooks, isDev = false } = {}) {
   // 3b. Deduplicate: if marketplace plugin also registers MCP + hooks,
   // clear them to prevent double execution. install.mjs hooks (in settings.json)
   // point to ~/.claude-mem-lite/ (latest code in dev mode via symlinks),
@@ -593,17 +593,47 @@ function dedupePluginCacheAndHooks({ managedHooks } = {}) {
       const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', MARKETPLACE_KEY, 'claude-mem-lite');
       if (existsSync(cacheBase)) {
         const launchSyncFiles = ['launch.mjs', 'launch-preflight.mjs'];
+        // Read, not remembered: the cache dir names ARE versions, so the comparison has to
+        // be against what this installer actually is. A stale constant here would re-open
+        // R10-P2-11 on the next release without changing a line of this block.
+        let selfVersion = null;
+        try {
+          selfVersion = JSON.parse(readFileSync(join(PROJECT_DIR, 'package.json'), 'utf8')).version;
+        } catch {
+          /* no readable package.json — treat every version as non-matching (sync nothing) */
+        }
         let clearedHooks = 0;
         for (const ver of readdirSync(cacheBase)) {
           const verDir = join(cacheBase, ver);
 
-          // Sync launch.mjs + its preflight companion (issue #15)
-          if (existsSync(join(verDir, 'scripts'))) {
+          // Sync launch.mjs + its preflight companion (issue #15).
+          //
+          // R10-P2-11: this used to run for EVERY cached version. Issue #15 is a dev-mode
+          // routing fix — the point is that a dev tree's launch.mjs reaches the cache the
+          // MCP server starts from — but nothing gated it, so a plain `install` (and the
+          // repair that SessionStart spawns in the background) pushed the installer's entry
+          // point into every OLD version dir, where it runs against that version's own
+          // `lib/`. Entry point and library are versioned together: HEAD's launch.mjs:72-73
+          // destructures `nativeBindingRepairHint` from ../lib/binding-probe.mjs, which
+          // v3.95.0 does not export, so :110 throws inside a catch and the user's repair
+          // hint disappears — a silent downgrade of the one message that tells them how to
+          // fix a dead binding. Reproduced in tests/sandbox/phaseB-npm.mjs §B9 (the old
+          // dir came back 9802B with `nativeBindingRepairHint` in it), which is the
+          // reproduction R10 §8 required before touching install().
+          //
+          // Dev mode still syncs everything: that is the fix's whole purpose, and a dev
+          // tree has no old versions to protect. Otherwise only the version dir that
+          // matches this installer — same release, so same expectations of `lib/`.
+          const versionMatches = isDev || ver === selfVersion;
+          if (versionMatches && existsSync(join(verDir, 'scripts'))) {
             for (const f of launchSyncFiles) {
               const src = join(PROJECT_DIR, 'scripts', f);
               if (existsSync(src)) {
                 try {
-                  copyFileSync(src, join(verDir, 'scripts', f));
+                  // Atomic for the same reason the two hooks.json writes above are: a
+                  // torn launch.mjs is the MCP server's entry point, and the reader is
+                  // Claude Code starting it, not us.
+                  atomicWriteFileSync(join(verDir, 'scripts', f), readFileSync(src));
                 } catch {
                   /* keep going */
                 }
@@ -959,7 +989,7 @@ async function install() {
   // re-read settings.json) is what keeps a future reorder from silently turning the
   // dedup off — the dependency is data, not sequence.
   const managedHooks = configureHooks();
-  dedupePluginCacheAndHooks({ managedHooks });
+  dedupePluginCacheAndHooks({ managedHooks, isDev: IS_DEV });
   backupLegacyClaudeMemData();
   verifyDatabase();
   await dogfoodAutoAdopt();

package/lib/search-core.mjs

@@ -465,6 +465,67 @@ export function applyTierFilter(db, results, { tier, sourceKey, currentProject }
   });
 }
 
+/**
+ * Tell the caller when `total` promises rows this pagination can never hand back.
+ *
+ * D#5. `computePerSourceWindow` is offset-INDEPENDENT by design (D#30: an
+ * offset-scaled pool re-ranks its own prefix under RRF, so pages overlapped and
+ * gapped on a vector-populated DB). The bound is right and stays. What was never
+ * adjusted is the REPORTED NUMBER: `countSearchTotal` re-derives the full
+ * MATCH+filter population, so a search over 128 matching rows prints
+ * "Found 10 of 128" at offset 50 and "No results at offset 60" — with nothing
+ * saying that offsets past the candidate pool are empty by construction.
+ * Measured 2026-09-07 on a 128-row sandbox corpus: the last non-empty offset is
+ * 59 / 59 / 89 for limits 10 / 20 / 30, i.e. at the default `mem_search` limit of
+ * 20, 60 of 128 rows (46.9%) are unreachable at ANY offset.
+ *
+ * `reachable` is the pre-slice candidate count (`preFinalizeCount` =
+ * `results.length`), NOT a re-derived `max(limit*3, 60)`. That matters and is not
+ * a style choice: `perSourceLimit` is PER SOURCE, so a cross-source search fuses
+ * up to four such pools and its real ceiling is several times the formula. A note
+ * quoting the formula would understate the reach of every cross-source query.
+ *
+ * Silent for deep (explicit or auto-escalated): there `total` IS the fused variant
+ * set already in `results`, so `total > reachable` cannot hold and a note would be
+ * describing a bound that is not the one in force.
+ *
+ * Off switch: CLAUDE_MEM_REACH_DISCLOSURE=off (mirrors CLAUDE_MEM_DEEP_DISCLOSURE).
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.total]      the reported population (countSearchTotal)
+ * @param {number} [opts.reachable]  pre-slice candidate count (preFinalizeCount)
+ * @param {number} [opts.offset]     the offset this page asked for
+ * @param {boolean} [opts.isDeep]
+ * @param {object} [opts.env]
+ * @returns {string} the note, or '' when it should not be shown
+ */
+export function reachabilityNote({
+  total = 0,
+  reachable = 0,
+  offset = 0,
+  isDeep = false,
+  env = process.env,
+} = {}) {
+  if (String(env.CLAUDE_MEM_REACH_DISCLOSURE || '').toLowerCase() === 'off') return '';
+  if (isDeep) return '';
+  if (!Number.isFinite(total) || !Number.isFinite(reachable)) return '';
+  // Nothing came back AT ALL is a different question from "this page is past the
+  // pool" — a tier filter that dropped every candidate leaves total > 0 with
+  // reachable 0, and answering that with a pagination note would misattribute it.
+  // The CLI's own zero-result branch owns that case; D#5 is about pagination reach.
+  if (!(reachable > 0)) return '';
+  if (!(total > reachable)) return '';
+  const tail =
+    'The candidate pool is sized from `limit` alone and deliberately does not grow with ' +
+    '`offset`, so same-limit pages stay stable and disjoint (D#30). Raise the limit to widen ' +
+    'the pool, or narrow the query.';
+  return offset >= reachable
+    ? `[search: offset ${offset} is past this query's reach — ${total} rows match but only the ` +
+        `first ${reachable} are pageable. ${tail}]`
+    : `[search: ${total} rows match but only the first ${reachable} are pageable; offsets at or ` +
+        `past ${reachable} return empty. ${tail}]`;
+}
+
 /**
  * Finalize a merged, scored result set into one page: compute the TRUE
  * (limit/offset-invariant) population, slice the requested page, and attach the
@@ -485,6 +546,9 @@ export function applyTierFilter(db, results, { tier, sourceKey, currentProject }
  * expansion (concept co-occurrence / PRF / vector), and `offset` is applied
  * exactly ONCE here (the per-source SQL always saw offset 0).
  *
+ * `total` therefore reports a population LARGER than this call can ever hand back —
+ * see reachabilityNote, which is what tells the caller so.
+ *
  * @returns {{ total: number, page: object[] }}
  */
 export function finalizeSearchPage(

package/mem-cli.mjs

@@ -120,6 +120,7 @@ import {
   parseDateBounds,
   parseDuration,
   coreRunSearchPipeline,
+  reachabilityNote,
 } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
@@ -479,6 +480,19 @@ async function cmdSearch(db, args, { llm } = {}) {
     return;
   }
 
+  // D#5. Same channel and same reasoning as the deep disclosure above: `total` is the
+  // real population, the candidate pool is offset-independent by design (D#30), and
+  // nothing else tells the caller that offsets past the pool are empty by construction.
+  // Emitted BEFORE the two return paths below so it covers both the past-the-pool page
+  // and a normal page whose total is unreachable — one call, not two wordings.
+  const reachNote = reachabilityNote({
+    total,
+    reachable: res.preFinalizeCount,
+    offset,
+    isDeep,
+  });
+  if (reachNote) process.stderr.write(`${reachNote}\n`);
+
   if (paged.length === 0) {
     if (jsonOutput) {
       out(
@@ -3202,7 +3216,7 @@ Commands:
     --run-all           Execute bypassing gates
     --task T            Comma-separated: re-enrich,normalize,cluster-merge,smart-compress
     --max N             Max items per task (1-100, default 15)
-    --scope S           re-enrich scope: narrow (default) | wide | aliases | scopes
+    --scope S           re-enrich scope: narrow (default) | wide | aliases | scopes | concepts
                         (aliases: backfill search_aliases on substantive rows that
                          lack them — incl. lesson-bearing manual saves — adds ONLY
                          aliases, never rewrites title/narrative/lesson)
@@ -3477,8 +3491,8 @@ async function cmdOptimize(db, args) {
   let reenrichScope = 'narrow';
   if (scopeIdx >= 0 && args[scopeIdx + 1] !== undefined) {
     const raw = args[scopeIdx + 1];
-    if (raw !== 'narrow' && raw !== 'wide' && raw !== 'aliases' && raw !== 'scopes') {
-      fail(`[mem] Invalid --scope "${raw}". Use: narrow, wide, aliases, scopes`);
+    if (raw !== 'narrow' && raw !== 'wide' && raw !== 'aliases' && raw !== 'scopes' && raw !== 'concepts') {
+      fail(`[mem] Invalid --scope "${raw}". Use: narrow, wide, aliases, scopes, concepts`);
       return;
     }
     reenrichScope = raw;
@@ -3502,7 +3516,7 @@ async function cmdOptimize(db, args) {
     out('[mem] 🔍 LLM Optimization Preview:');
     if (project) out(`  Project filter: ${project}`);
     out(
-      `  Re-enrich candidates: ${preview.reenrich}${preview.reenrichWide !== undefined && preview.reenrichWide !== null ? `  (wide scope: ${preview.reenrichWide})` : ''}${preview.reenrichAliases ? `  (aliases scope: ${preview.reenrichAliases})` : ''}${preview.reenrichScopes ? `  (scopes scope: ${preview.reenrichScopes})` : ''}`,
+      `  Re-enrich candidates: ${preview.reenrich}${preview.reenrichWide !== undefined && preview.reenrichWide !== null ? `  (wide scope: ${preview.reenrichWide})` : ''}${preview.reenrichAliases ? `  (aliases scope: ${preview.reenrichAliases})` : ''}${preview.reenrichScopes ? `  (scopes scope: ${preview.reenrichScopes})` : ''}${preview.reenrichConcepts ? `  (concepts scope: ${preview.reenrichConcepts})` : ''}`,
     );
     out(
       `  Normalize: ${preview.normalizeGateOpen ? `${preview.normalize} unique concepts` : 'gate closed (7-day interval)'}`,

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "5.3.1",
+  "version": "5.5.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",
@@ -30,6 +30,8 @@
     "test:coverage": "vitest run --coverage",
     "benchmark": "node benchmark/benchmark.mjs",
     "benchmark:gate": "node benchmark/ci-gate.mjs",
+    "benchmark:multipliers": "node benchmark/multiplier-discrimination.mjs",
+    "benchmark:multipliers:gate": "node benchmark/multiplier-discrimination.mjs --self-check",
     "audit:inventory": "node scripts/audit-metrics.mjs --inventory",
     "audit:deps": "node scripts/audit-metrics.mjs --deps",
     "audit:selfcheck": "node scripts/audit-metrics.mjs --self-check",

package/scoring-sql.mjs

@@ -10,25 +10,55 @@ import { DAY_MS } from './lib/time-constants.mjs';
 // multipliers below encode PRODUCT PRIORS: recent / same-project / important /
 // high-signal-type / frequently-cited memories are more relevant to the CURRENT
 // dev session. A periodic audit tends to flag them as "0-lift dead weight" —
-// resist that on benchmark evidence alone. Measured (audit ②, obs #8773):
-//   * benchmark.mjs --matrix (micro-fixture, now models the full FULL_SCORE
-//     chain): type-quality is the TOP contributor (drop-type ΔnDCG=0.0082,
-//     ΔMRR=0.0166), decay +0.0043 nDCG, importance +0.0012; the chain lifts
-//     hybrid over bm25_only by +0.0093 nDCG / +0.0166 MRR (net 0 queries hurt).
-//     project, access and lesson read exactly 0 — but that is STRUCTURAL: the
-//     fixture is single-project, access_count=0, and has 0 lesson_learned rows,
-//     so it cannot vary those three axes.
+// resist that, and reach for the right instrument instead of the aggregate one.
+//
+// ALL EIGHT ARE ALIVE AND CARRY THE MAGNITUDE DECLARED HERE. Measured
+// 2026-09-07 at `main` @ f25e8ae with benchmark/multiplier-discrimination.mjs,
+// which ranks pairs of rows with byte-identical indexed text differing in one
+// column, so BM25 ties and the score quotient IS the multiplier:
+//     decay 1.9770  type 1.8333  project 2.0000  importance 2.0000
+//     access 1.5004  lesson 1.3000  noise 5.0000  cite 2.0000
+// Each matches its declared ratio to 4 decimals, hybrid ranks the preferred row
+// 12/12, and removing the term drops that to 6/12 — a coin flip.
+//
+// THE AGGREGATE MATRIX CANNOT SEE THAT, and its zeros must not be read as death.
+// Same tree, `benchmark.mjs --matrix`: bm25_only ALONE reads R@10 0.8996 /
+// P@10 0.9731 / nDCG 0.9728, so the fixture is saturated and all eight
+// multipliers together buy +0.0002 R@10. Five ablation arms (project, access,
+// lesson, noise, cite) read 0 on all four metrics, and dropping importance reads
+// BETTER (ΔnDCG -0.0019). Why each zero, corrected 2026-09-07 — an earlier
+// version of this note said "the fixture is single-project", which is false
+// (seed-data.json is 5 projects x 40 rows):
+//   * project — 29 of 30 queries set no project, and the one that does also
+//     FILTERS on it, which makes the boost a constant over the survivors and
+//     therefore rank-invariant. The harness used to pass the filter value as the
+//     boost; it now mirrors search-engine.mjs:606 and disables the boost under a
+//     filter, which is rank-invariant on the matrix (verified: all 11 delta
+//     blocks byte-identical across the change).
+//   * access / lesson / noise / cite — seed-data.json carries no access_count,
+//     no lesson_learned and no injection/cite counters at all, so those four
+//     columns are constant and the terms are 1.0x on every row.
+// A multiplier reading 0 there is a benchmark-MISMATCH artifact, NOT dead weight.
 //   * longmemeval.mjs --temporal (n=500, real dates): bit-identical to uniform —
 //     LongMemEval-S windows (mean 27.9d, 74% <30d) are far shorter than these
 //     half-lives, so decay moves no rank there either.
-// Where a multiplier reads 0 it is a benchmark-MISMATCH artifact (the instrument
-// can't vary that axis), NOT proven dead weight. Decision: KEEP them; do NOT
-// delete on "0 lift". Guardrail: the ci-gate `hybrid_over_bm25 >= -0.05` floor
-// (benchmark/ci-gate.mjs) covers the full modelled chain — D#121: cite + noise
-// joined the matrix MULT_EXPR after M-3 put them in FULL_SCORE (fixture carries
-// zero cite/noise state, so both read 0 by construction, same caveat as lesson;
-// their real-SQL direction pins live in benchmark/events-pipeline-probes.mjs).
-// Genuine validation of the prior-encoding axes needs a labeled real-dev-memory eval.
+//
+// DO NOT TRUST THE CI GATE TO CATCH A CHANGE HERE. The `hybrid_over_bm25 >= -0.05`
+// floor does NOT cover the chain, measured 2026-09-07 by mutating the real tree
+// and reverting it: neutering the importance multiplier left the gate at exit 0
+// with all four checks PASS and `hybrid_over_bm25` going UP (R 0.0002 -> 0.0019),
+// because importance is a negative contributor on that fixture; changing lesson's
+// 0.3 to 0.5 left the gate's output byte-identical. The eight per-term ablation
+// deltas the matrix prints are gated by nothing. Retune a constant in this file
+// and re-run benchmark/multiplier-discrimination.mjs, which reports MISMATCH on
+// exactly that shape — the aggregate gate will not.
+// D#121: cite + noise joined the matrix MULT_EXPR after M-3 put them in
+// FULL_SCORE; their real-SQL direction pins live in
+// benchmark/events-pipeline-probes.mjs.
+// Still open, and NOT what the ruler above answers: whether these priors help a
+// REAL user. "Wired up with the declared magnitude" is a different question from
+// "correctly calibrated", and the second one still needs a labeled
+// real-dev-memory eval.
 
 // ─── Type-Differentiated Recency Decay ──────────────────────────────────────
 

package/server.mjs

@@ -30,6 +30,7 @@ import {
   parseDateBounds,
   parseDuration,
   coreRunSearchPipeline,
+  reachabilityNote,
 } from './lib/search-core.mjs';
 import {
   runMaintainOps,
@@ -595,6 +596,20 @@ async function runSearchPipeline(db, args, { llm, rerankLlm } = {}) {
     });
     if (disclosure) output.content[0].text += `\n\n${disclosure}`;
   }
+  // D#5. Same split as the deep note: an MCP client reads the tool RESULT, not stderr,
+  // so a caller that pages past the candidate pool has to be told inside the payload or
+  // it reads "0 results" against a total it was just handed and concludes the corpus is
+  // empty. `reachable` is r.preFinalizeCount — the pre-slice candidate count — because
+  // perSourceLimit is PER SOURCE and a cross-source query fuses several of those pools.
+  if (output.content?.[0]?.type === 'text') {
+    const reachNote = reachabilityNote({
+      total: r.total,
+      reachable: r.preFinalizeCount,
+      offset,
+      isDeep: r.isDeep,
+    });
+    if (reachNote) output.content[0].text += `\n\n${reachNote}`;
+  }
   appendDeferredTrailer(output);
 
   // Expose structured fields for tests + the MCP content blob.