claude-mem-lite 3.84.1 → 3.85.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.84.1",
+      "version": "3.85.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

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

package/hook-memory.mjs

@@ -13,6 +13,49 @@ import { formatSubagentContext } from './lib/task-imperative.mjs';
 import { DAY_MS } from './lib/time-constants.mjs';
 const MAX_MEMORY_INJECTIONS = 3;
 const MEMORY_LOOKBACK_MS = 60 * DAY_MS; // 60 days
+
+/**
+ * Candidate-pool bounds for the `fyi` injection face (searchRelevantMemories).
+ *
+ * READ THESE AS REACHABILITY BOUNDS, NOT AS RANKING GATES — the same distinction
+ * D#172 cost us on IMPERATIVE_POOL_BACKSTOP, found again here by the 2026-08-29 audit
+ * (ALGO-3). The two SELECTs below `ORDER BY` RAW bm25, but the row that actually gets
+ * injected is chosen by the JS composite in `scored` (type quality × lesson bonus ×
+ * importance × cross-project × OR × noise × cite). So whatever these numbers are, a row
+ * outside the window cannot be picked however high its composite score would have been.
+ *
+ * The window has to be wide because the composite spread is enormous. Multiplying the
+ * extremes of the JS factors (same-project, AND mode): best = 1.5 decision × 1.5 lesson
+ * × 1.0 importance × 1.0 noise × 3.0 cite = 6.75; worst = 0.5 change × 1.0 no-lesson
+ * × 0.6 importance × 0.2 noise × 0.4 cite = 0.024. That is a **281× spread**, so a row
+ * ranked below the window on raw bm25 can outscore the window's contents by a wide
+ * margin. (The audit estimated ">10×"; the factor tables say 281×.)
+ *
+ * HONEST LIMIT OF THIS FIX: because the spread is 281× and bm25 magnitude decays slowly
+ * across a top-N window, NO finite pool size proves sufficiency. 30/15 is a 3× widening
+ * chosen where cost stays flat (the SELECT carries `narrative`, so the pool is the
+ * expensive term, not the sort) — it makes the bound loose, it does not remove it.
+ *
+ * The bound is REMOVABLE, and deliberately was not removed: ordering both SELECTs by the
+ * composite instead of raw bm25 is expressible in SQL today (every factor already has a
+ * clause — TYPE_QUALITY_CASE / noisePenaltyClause / citeFactorClause — and the two
+ * remaining factors, cross-project and OR, are per-QUERY constants that cannot affect
+ * within-query order). That would make LIMIT a true ranking bound. It is not done here
+ * because `lib/inject-search-core.mjs:23-25` records this surface's "BM25-sort + JS
+ * scoring" composition as a deliberate per-surface asymmetry (#8786), and this face is
+ * one `benchmark/denoise-ab.mjs` is structurally blind to (its suites drive the
+ * search-engine, not this function) — re-ranking an unmeasurable face is how this
+ * project has repeatedly shipped regressions. Widening is monotone and provable;
+ * re-ranking needs a ruler that does not exist yet.
+ *
+ * WHY WIDENING IS SAFE: the old window is a strict PREFIX of the new one (same ORDER BY,
+ * larger LIMIT), so the new candidate set is a superset. `scored` sorts by composite and
+ * the threshold filter is monotone in that score, so every row returned is at least as
+ * good as the row it displaced. The only non-monotone stage is the term-coverage filter,
+ * which is exactly why the pool needs slack rather than just `MAX_MEMORY_INJECTIONS`.
+ */
+const RERANK_POOL_SAME_PROJECT = 30;
+const RERANK_POOL_CROSS_PROJECT = 15;
 // Type weights come from scoring-sql.mjs — this was a hand-copy kept equal by an
 // "aligned with (R2)" comment (audit 2026-08-22, P2-10).
 // lesson_learned boost (1.5×) stacks for entries with a real takeaway.
@@ -225,7 +268,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
         AND ${liveObsFilterSql('o')}
         AND ${notLowSignalTitleClause('o')}
       ORDER BY ${OBS_BM25}
-      LIMIT 10
+      LIMIT ${RERANK_POOL_SAME_PROJECT}
     `);
     let rows = selectStmt.all(ftsQuery, project, cutoff);
     let usedOrFallback = false;
@@ -280,7 +323,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
           AND ${liveObsFilterSql('o')}
           AND ${notLowSignalTitleClause('o')}
         ORDER BY ${OBS_BM25}
-        LIMIT 5
+        LIMIT ${RERANK_POOL_CROSS_PROJECT}
       `);
       crossRows = crossStmt.all(ftsQuery, project, cutoff);
       if (crossRows.length === 0) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.84.1",
+  "version": "3.85.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.84.1",
+      "version": "3.85.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.84.1",
+  "version": "3.85.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/scripts/pre-tool-recall.js

@@ -61,6 +61,13 @@ const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtim
 // which already imports lib modules here, and the inlined value silently encoded the
 // same premise twice.
 import { DEDUP_STALE_MS as CROSS_HOOK_DEDUP_MS } from './prompt-search-utils.mjs';
+// Upper bound on the over-fetch the cross-hook dedup buys itself (ALGO-4). The dedup
+// runs in JS after the SELECTs, so each LIMIT is raised by the seen-set size to keep the
+// dedup a re-ranking rather than a truncation. This cap exists because the seen-set is
+// read from a file on disk: it is bounded by UPS's own per-prompt budget in practice
+// (MAX_RESULTS 3), but an unbounded value read off disk must never size a query. 5 is
+// well above that budget and still leaves the worst case at 2+5=7 rows per SELECT.
+const CROSS_HOOK_DEDUP_SLACK_MAX = 5;
 // v2.33.1: cooldown path is session-scoped so same-file-twice within one
 // session never re-injects (was: global file, 5-min window). Cross-session:
 // fresh file, fresh nudges — this is intended. No session_id → fall back to
@@ -451,7 +458,18 @@ try {
           (o.lesson_learned IS NOT NULL AND o.lesson_learned != '')
           OR (o.type IN ('bugfix', 'decision') AND ${notLowSignalSql})
         )`;
-    const obsLimit = isRead ? 1 : 2;
+    // Cross-hook dedup slack (audit 2026-08-29 ALGO-4, the D#172 shape again). The
+    // dedup below drops rows UPS already injected this prompt, and it used to run
+    // DOWNSTREAM of these LIMITs — so a deduped row left its slot EMPTY instead of
+    // yielding it to the next candidate, i.e. "dedup" was implemented as "shrink".
+    // On a Read (obsLimit 1 / eventsLimit 1) one dedup hit silenced the whole face.
+    // Read the seen-set FIRST and over-fetch by its size so the dedup removes rows
+    // from a pool that still has enough left to fill the cap. Capped at
+    // CROSS_HOOK_DEDUP_SLACK_MAX: the seen-set is bounded by UPS's own per-prompt
+    // budget in practice, but it is read off disk and must not size a query.
+    const crossHookSeen = readCrossHookInjected(project, sessionId);
+    const dedupSlack = Math.min(crossHookSeen.size, CROSS_HOOK_DEDUP_SLACK_MAX);
+    const obsLimit = (isRead ? 1 : 2) + dedupSlack;
     // A1.5 (v2.83.2): cite_factor as a tertiary sort key. When multiple file-
     // matching lessons exist, the one with proven cite history outranks the
     // merely-most-recent one. Single-match files unchanged (obsLimit=1 Read /
@@ -521,7 +539,7 @@ try {
       ? "AND body IS NOT NULL AND body != ''"
       : `AND ((body IS NOT NULL AND body != '')
           OR (event_type IN ('bugfix', 'decision', 'lesson') AND ${buildNotLowSignalSql('')}))`;
-    const eventsLimit = isRead ? 1 : 2;
+    const eventsLimit = (isRead ? 1 : 2) + dedupSlack;
     let eventRows = [];
     try {
       eventRows = db.prepare(`
@@ -548,7 +566,7 @@ try {
     // P1 (D#78): tag each row's source table — events share the numeric id
     // space with observations, and the Stop-side edge attribution must never
     // feed an event id into observation_files updates.
-    const crossHookSeen = readCrossHookInjected(project, sessionId);
+    // (crossHookSeen is read above, before the two SELECTs — it sizes their LIMITs.)
     const sourcedRows = [
       ...rows.map(r => ({ ...r, src: 'obs' })),
       ...eventRows.map(r => ({ ...r, src: 'evt' })),

package/scripts/user-prompt-search.js

@@ -50,6 +50,12 @@ const LOOKBACK_MS = 60 * DAY_MS; // 60 days
 // quality gate — only BM25 ordering — so additional rows inflate noise without
 // improving signal. Env-overridable for projects that want broader prompt recall.
 const PROMPT_FALLBACK_LIMIT = Number(process.env.CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT || 1);
+// Over-fetch factor for that cap. searchByUserPrompts filters rows in JS (cjkPrecisionOk)
+// AFTER the SQL LIMIT, so the LIMIT bounds reachability, not just output width — see the
+// comment at the query. These size the pool only; the function still returns at most
+// PROMPT_FALLBACK_LIMIT rows, so widening them cannot inflate the injection budget.
+const PROMPT_FALLBACK_POOL_FACTOR = 5;
+const PROMPT_FALLBACK_POOL_MAX = 25;
 
 // T3 (v2.31): per-row BM25 magnitude floor. OBS_BM25 (in scoring-sql.mjs)
 // returns the raw bm25() value — negative, smaller = better. Multiplied by
@@ -263,6 +269,13 @@ export function hasExplicitSignal(text, { errSig, files, intent } = {}) {
 // constants here is what would let them drift apart again.
 
 export const IDENTIFIER_BYPASS = process.env.CLAUDE_MEM_UPS_IDENTIFIER_BYPASS !== '0';
+// How far past the main LIMIT the bypass may look, and how many rows it may pull from
+// there (ALGO-2). These size the CANDIDATE POOL only — the injected set is still capped
+// by MAX_RESULTS downstream, so neither widens the injection budget. Kept small on
+// purpose: rows this deep matched the prompt weakly overall, and the identifier hit is
+// the only reason they are admitted at all.
+const IDENTIFIER_BYPASS_POOL_EXTRA = 7;
+const IDENTIFIER_BYPASS_DEEP_MAX = 2;
 const TECH_IDENTIFIER_RE_G = new RegExp(TECH_IDENTIFIER_RE.source, 'g');
 
 // All tech-identifier tokens in `text`, lowercased + de-duped (for case-insensitive
@@ -426,12 +439,20 @@ function searchByUserPrompts(db, queryText, project, limit) {
     LIMIT ?
   `;
 
-  let rows = db.prepare(sql).all(ftsQuery, project, cutoff, limit);
+  // Over-fetch, because the cjkPrecisionOk filter below runs in JS (audit 2026-08-29
+  // ALGO-5, the D#172 shape). At the shipped PROMPT_FALLBACK_LIMIT of 1 the SQL LIMIT
+  // was a REACHABILITY bound sitting upstream of a relevance filter: dropping one row
+  // dropped the whole face, so a CJK prompt whose best BM25 match happened to be a
+  // false bigram hit injected NOTHING even when rank 2 was a real match. Fetch a pool,
+  // filter, then take `limit` — same ORDER BY, so the old result is a prefix of this
+  // one and a row can only be added, never displaced by something worse.
+  const poolLimit = Math.min(limit * PROMPT_FALLBACK_POOL_FACTOR, PROMPT_FALLBACK_POOL_MAX);
+  let rows = db.prepare(sql).all(ftsQuery, project, cutoff, poolLimit);
 
   if (rows.length === 0) {
     const orQuery = relaxFtsQueryToOr(ftsQuery);
     if (orQuery) {
-      try { rows = db.prepare(sql).all(orQuery, project, cutoff, limit); } catch {}
+      try { rows = db.prepare(sql).all(orQuery, project, cutoff, poolLimit); } catch {}
     }
   }
 
@@ -439,7 +460,7 @@ function searchByUserPrompts(db, queryText, project, limit) {
   // FTS degrades CJK bigram queries to single-char AND, letting any prose
   // sharing common chars leak through. Drop rows that miss < 20% of query
   // bigrams/keywords as contiguous substrings. Non-CJK queries bypass.
-  return rows.filter(r => cjkPrecisionOk(queryText, r.prompt_text));
+  return rows.filter(r => cjkPrecisionOk(queryText, r.prompt_text)).slice(0, limit);
 }
 
 function searchRecent(db, project, limit) {
@@ -752,12 +773,24 @@ async function main() {
     } else {
       // FTS search: use the prompt as query, optionally type-filtered
       const files = filesForGate;
-      let ftsResult = searchByFts(db, promptText, project, intent?.limit || MAX_RESULTS, intent?.type || null);
+      const mainLimit = intent?.limit || MAX_RESULTS;
+      // Over-fetch ONLY to feed the identifier bypass below (audit 2026-08-29 ALGO-2,
+      // the D#172 shape). The bypass used to select from `ftsRows`, i.e. from the same
+      // LIMIT-`mainLimit` window it exists to rescue rows into — so it could only ever
+      // recover a row the composite sort had ALREADY ranked top-3, and the df=1
+      // identifier row its own docblock argues for (rare token, so BM25-strong on the
+      // term but easily out-ranked by rows matching more of the prompt) was unreachable.
+      // `ftsRows` stays the exact old head slice, so the main path is byte-identical;
+      // only the bypass sees deeper. Pool sizing is bypass-only: with the bypass off
+      // this is the old query verbatim.
+      const poolLimit = IDENTIFIER_BYPASS ? mainLimit + IDENTIFIER_BYPASS_POOL_EXTRA : mainLimit;
+      let ftsResult = searchByFts(db, promptText, project, poolLimit, intent?.type || null);
       // Fallback: if typed search returned nothing, retry without type filter
       if (ftsResult.rows.length === 0 && intent?.type) {
-        ftsResult = searchByFts(db, promptText, project, intent.limit || MAX_RESULTS, null);
+        ftsResult = searchByFts(db, promptText, project, poolLimit, null);
       }
-      let ftsRows = ftsResult.rows;
+      const ftsPool = ftsResult.rows;
+      let ftsRows = ftsPool.slice(0, mainLimit);
       const ftsMode = ftsResult.mode;
       const fileRows = files.length > 0 ? searchByFile(db, files, project, 2) : [];
 
@@ -775,9 +808,26 @@ async function main() {
       // Capture rows that exact-match a prompt identifier BEFORE the set-floors below;
       // they carry independent precision signal (sigRows/fileRows rationale) and are
       // restored after the floors so a low top-score can't drop a named-identifier hit.
-      const bypassRows = (IDENTIFIER_BYPASS && promptIdentifiers.length > 0)
-        ? ftsRows.filter(r => rowMatchesIdentifier(r, promptIdentifiers))
-        : [];
+      // STRICTLY ADDITIVE to the pre-ALGO-2 behaviour: `head` is what this expression
+      // used to return (the post-floor rows of the old LIMIT window that match an
+      // identifier), and `deep` adds at most IDENTIFIER_BYPASS_DEEP_MAX rows from
+      // beyond that window. The audit prescribed a standalone LIMIT-2 SELECT; a capped
+      // tail of the SAME query is the same reach with one fewer FTS scan, and it cannot
+      // regress the head — a flat cap of 2 over the merged set could have, by evicting
+      // a third head row that ships today.
+      const bypassFloorOk = (r) => typeof r.relevance === 'number' && Math.abs(r.relevance) >= bm25Floor;
+      let bypassRows = [];
+      if (IDENTIFIER_BYPASS && promptIdentifiers.length > 0) {
+        const head = ftsPool.slice(0, mainLimit)
+          .filter(bypassFloorOk)
+          .filter(r => rowMatchesIdentifier(r, promptIdentifiers));
+        const headIds = new Set(head.map(r => r.id));
+        const deep = ftsPool.slice(mainLimit)
+          .filter(bypassFloorOk)
+          .filter(r => !headIds.has(r.id) && rowMatchesIdentifier(r, promptIdentifiers))
+          .slice(0, IDENTIFIER_BYPASS_DEEP_MAX);
+        bypassRows = [...head, ...deep];
+      }
 
       // v2.43.x: OR-mode raw-BM25 floor. In OR-fallback mode the composite
       // TOP_REL_FLOOR below is inflated by importance × type_quality × decay