claude-mem-lite 3.78.0 → 3.79.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.78.0",
+      "version": "3.79.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.78.0",
+  "version": "3.79.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

@@ -816,6 +816,8 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `CLAUDE_MEM_UPS_TOP_MIN` | Minimum score for the top hit; `0` disables (useful on tiny test corpora). | `50` |
 | `CLAUDE_MEM_UPS_FLOOR_REF_CORPUS` | Reference corpus size the score floors are normalized against, so a fresh install with few rows is not silently gated to zero injections. Shared by every floor-bearing surface, including error-recall below. | `584` |
 | `CLAUDE_MEM_ERROR_RECALL_BM25_MIN` | Relevance floor for the error-recall surface (memories injected after a failed Bash command). **Off by default.** Setting it to `10.5` (the calibrated value) makes the surface stay silent when its best-matching memory is not actually about the failure — the whole set is dropped, never trimmed row-by-row. **It is a real trade, not a free win:** measured on a live database at that threshold, injections fall ~37% and ~39% of firings go silent, concentrated in projects with few memories. Off by default because nothing shows the dropped rows were noise. Explore with `node benchmark/error-recall-suite.mjs --sweep`. | `0` (off) |
+| `CLAUDE_MEM_ERROR_RECALL_RERANK` | `off` restores the flat keyword ordering of the error-recall surface. **On by default**, and unlike the floor above it removes nothing: memories that share only the failed command's vocabulary are demoted below memories that mention the failure itself, and when a project has none of the latter the result is unchanged. Measured on a live database over 52 real failing commands × 15 projects: the lead memory matched no error term in 42.3% of firings before, 21.5% after, with the injected row count identical. | _(on)_ |
+| `CLAUDE_MEM_ERROR_RECALL_ON_FAILURE` | `off` stops the plugin from recalling memories when a Bash command **fails at the host level**. On by default. Claude Code delivers failed tool calls to a separate `PostToolUseFailure` hook event, so before this the surface only ever saw commands that exited `0` while printing error-ish text — a genuinely failing build recalled nothing. Denials from your own guardrails (sandbox, policy hooks, declined permission prompts) and commands you interrupted are never recalled for. | _(on)_ |
 | `CLAUDE_MEM_UPS_IDENTIFIER_BYPASS` | `0` disables the bypass that lets an exact identifier match skip the score floors. | _(on)_ |
 | `CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT` | How many past-prompt rows the fallback arm may return. | `1` |
 | `MEM_COVERAGE_THRESHOLD` | Fraction of query terms a memory must cover to qualify (∈ [0,1]). | `0.4` |

package/bash-utils.mjs

@@ -120,6 +120,58 @@ const ERROR_STOP_WORDS = new Set([
 const ERROR_LINE_RE = /error|fail|exception|cannot|not found|undefined|null/i;
 const ERROR_RECALL_MAX_TERMS = 6;
 
+/**
+ * The token that NAMES the failure: an exception class (`ModuleNotFoundError`,
+ * `JSONDecodeError`), an errno-style code (`ENOENT`, `EACCES`), a signal (`SIGSEGV`),
+ * or Rust's `panicked`.
+ *
+ * WHY THIS EXISTS (D#167). The line scan below takes the FIRST 3 matching lines and the
+ * first 5 tokens of each, and a real failure puts its banner first and its name last:
+ *
+ *     Traceback (most recent call last):        <- matches, contributes `traceback most recent`
+ *       File "<string>", line 3, in <module>
+ *     ModuleNotFoundError: No module named 'x'  <- the only line that says WHAT broke
+ *
+ * Measured over 52 real failing commands pulled from 1110 transcripts: 28 of them name
+ * their failure this way, and in 25 of those 28 (89.3%) THE NAME NEVER REACHED THE
+ * QUERY. The six-term budget went to the banner (`traceback,most,recent`) and to path
+ * fragments from the command (`mnt,data_ssd,dev`). Downstream, 39.2% of injected rows
+ * (764/1947 over 8 projects x 52 shapes on the live DB) matched no error term at all —
+ * they were admitted on command vocabulary alone — and for 42.3% of firing cases that
+ * was true of the TOP-1 row, whose lesson_learned is inlined into the model's context.
+ *
+ * This is deliberately a POSITIVE pattern for the signal, not a stop-list for the noise:
+ * a stop-list of boilerplate ("traceback", "most", "recent", "call", "last", …) grows
+ * once per runtime forever, which is the enumeration the D#136 docblock below warns
+ * against. Matching the shape of an exception name instead covers runtimes nobody has
+ * seen yet, and when nothing matches, extraction is byte-identical to before.
+ *
+ * Note `E[A-Z]{3,}` also matches the literal `ERROR`; it is dropped by ERROR_STOP_WORDS
+ * on the next line, and that interaction is load-bearing rather than incidental.
+ */
+const ERROR_NAMER_RE = /\b(?:[A-Z][A-Za-z]*(?:Error|Exception)|E[A-Z]{3,}|SIG[A-Z]{2,}|panicked)\b/g;
+
+/**
+ * How many names may jump the queue. Each one displaces a scanned term (the 6-term cap
+ * is unchanged), so this trades tail tokens for the identifier.
+ *
+ * ONE, and that is measured rather than argued. Swept on the live DB over the same 52
+ * shapes x 15 projects, reading the share of injected rows that match no error term and
+ * the share of cases whose top row does:
+ *
+ *   MAX=1   434 rows (22.4%)   154 cases (21.5%)
+ *   MAX=2   442 rows (22.8%)   157 cases (22.0%)
+ *   MAX=3   445 rows (22.9%)   157 cases (22.0%)
+ *
+ * The second name never pays: 96.4% of shapes already have their failure named by the
+ * first, so slots 2 and 3 buy a duplicate or a second-order name while still evicting a
+ * scanned term — and the evicted tail is often the most specific token in the list (see
+ * the golden case in tests/error-recall-gate.test.mjs, where a filename is lost). This
+ * shipped at 2 on the reasoning that a chained Python traceback has two real names; the
+ * sweep says that reasoning does not survive contact with the sample.
+ */
+const ERROR_NAMER_MAX = 1;
+
 /**
  * Split a failed command + its output into command-derived and error-derived terms.
  * Shared by extractErrorKeywords (merged view, unchanged contract) and
@@ -137,6 +189,19 @@ function collectErrorTerms(cmd, response) {
     if (!ERROR_STOP_WORDS.has(lw) && !seen.has(lw)) { seen.add(lw); cmdWords.push(lw); }
   }
   const errWords = [];
+  // The failure's NAME goes in first — see ERROR_NAMER_RE for the measurement that put
+  // it here. Prepending rather than re-ordering the LINE scan is deliberate: sorting
+  // namer-bearing lines to the front also promotes their verbose neighbours, which costs
+  // real terms (on npm's ENOENT output it evicts `syscall` in favour of `such`/`file`
+  // from the long "no such file or directory" line). Prepending only ever displaces the
+  // TAIL of what the scan would have produced.
+  for (const m of String(response || '').match(ERROR_NAMER_RE) || []) {
+    if (errWords.length >= ERROR_NAMER_MAX) break;
+    const lt = m.toLowerCase();
+    if (ERROR_STOP_WORDS.has(lt) || seen.has(lt)) continue;
+    seen.add(lt);
+    errWords.push(lt);
+  }
   // The line filter is the TRIGGER's pattern list OR'd with the prose one. Anything
   // that made detectBashSignificance call this a hard error is, by construction, also
   // something we will extract terms from — which closes the "trigger fired, extractor
@@ -163,6 +228,40 @@ function collectErrorTerms(cmd, response) {
   return { cmdWords, errWords };
 }
 
+/**
+ * THE CAP TRUNCATES BY POSITION, AND THAT WAS TESTED AGAINST THE ALTERNATIVE (D#169).
+ *
+ * The alternative looked obviously right. Tokens are scanned line by line, prose comes
+ * before identifiers within a line, so `AssertionError: expected observation-write.mjs
+ * to be defined` yields `assertionerror, expected, observation-write.mjs` — and whatever
+ * the cap removes comes off that end. On a real shape, `npx vitest run
+ * tests/scope-label.test.mjs` failing with an AssertionError kept `fail, tests` and
+ * dropped `scope-label.test.mjs`: a filename traded for a word in thousands of memories.
+ * Keeping identifier-shaped tokens (`[._-]`) first should fix that.
+ *
+ * Measured on the live DB, same 58 real shapes x 15 projects either way:
+ *
+ *                              cmd-only rows     cmd-only at TOP-1
+ *   positional cap (shipped)   493/2184  22.6%   171/801  21.3%
+ *   identifier-first cap        749/2093  35.8%   259/775  33.4%
+ *
+ * Thirteen points WORSE on both, and the mechanism is worth keeping written down:
+ * `[._-]` conflates "discriminative" with "unique to this invocation". The tokens it
+ * promotes are this run's own paths and filenames — `d167-measure.mjs`,
+ * `s-default.json` — whose IDF is so high they match NOTHING in the corpus, and the
+ * tokens it evicts to make room are `enoent`, `syscall`: low-IDF, but present in the
+ * memories that actually explain the failure. A row then survives on command vocabulary
+ * alone, which is the D#167 defect re-created from the other side.
+ *
+ * (A variant that promoted identifiers only among ERROR words, sparing command words,
+ * measured byte-identical: command words sit at low indices, so a positional tiebreak
+ * already keeps them and promotion never decides their fate.)
+ *
+ * The premise "the evicted tail is systematically the good part" is therefore FALSE.
+ * The tail is often hapax. Any future attempt here needs real document frequencies, not
+ * a shape heuristic — and planErrorRecall is pure, with no corpus to count against.
+ */
+
 /**
  * Extract discriminative keywords from a failed command and its error output.
  * Filters out common stop words to produce useful FTS5 search terms.
@@ -172,6 +271,8 @@ function collectErrorTerms(cmd, response) {
  */
 export function extractErrorKeywords(cmd, response) {
   const { cmdWords, errWords } = collectErrorTerms(cmd, response);
+  // Same cap rule as planErrorRecall — the two must not drift into dialects, which is
+  // pinned by a test asserting they emit identical lists.
   const result = [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS);
   return result.length >= 1 ? result : null;
 }
@@ -231,12 +332,26 @@ export function extractErrorKeywords(cmd, response) {
  *
  * @param {string} cmd The command that was executed
  * @param {string} response The error output text
- * @returns {{terms: string[]}|null} null ⇒ do not inject
+ * @returns {{terms: string[], cmdWords: string[], errWords: string[]}|null}
+ *   null ⇒ do not inject. The two classes are returned ALONGSIDE the merged list, and
+ *   post-cap, so the retrieval surface can rank on "did this row match the failure or
+ *   only the command" without re-deriving the split from the command string — a
+ *   re-derivation is the "second program that merely looks like the first" trap this
+ *   file's consumer (lib/error-recall-core.mjs) is structured to avoid.
  */
 export function planErrorRecall(cmd, response) {
   const { cmdWords, errWords } = collectErrorTerms(cmd, response);
   if (errWords.length === 0) return null;
-  return { terms: [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS) };
+  const terms = [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS);
+  // Intersect with the CAPPED list: a term the cap dropped is not in the query, so
+  // reporting it as an error term would have the surface rank on a word it never
+  // matched on.
+  const kept = new Set(terms);
+  return {
+    terms,
+    cmdWords: cmdWords.filter((t) => kept.has(t)),
+    errWords: errWords.filter((t) => kept.has(t)),
+  };
 }
 
 // ─── File Paths ──────────────────────────────────────────────────────────────

package/hook.mjs

@@ -49,6 +49,7 @@ import { readFastSummarySource, insertFastSummary, FAST_SUMMARY_LIMITS } from '.
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { recordHookError } from './lib/hook-telemetry.mjs';
 import { queueHookContext, queueHookSystemMessage, flushHookStdout } from './lib/hook-stdout.mjs';
+import { shouldRecallOnFailure } from './lib/tool-refusal.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, resolveDefaultMaintainOps, markAutoCompressible, selectFuzzyDedupeIds, stampDedupSuperseded, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
@@ -483,7 +484,18 @@ async function handlePostToolUse() {
 
 // ─── Error-Triggered Recall (Tier 2 G) ─────────────────────────────────────
 
-function triggerErrorRecall(db, toolInput, response) {
+/**
+ * @param {object} db Open handle.
+ * @param {object} toolInput The failed tool's input (needs `.command`).
+ * @param {string} response The failure text.
+ * @param {{eventName?: string, metricEvent?: string}} [opts] Which hook event this is
+ *   answering. The envelope carries exactly one hookEventName and the host rejects a
+ *   mismatch, so the PostToolUseFailure path MUST pass its own — defaulting silently
+ *   would emit a PostToolUse envelope from a PostToolUseFailure hook.
+ */
+function triggerErrorRecall(db, toolInput, response, opts = {}) {
+  const eventName = opts.eventName || 'PostToolUse';
+  const metricEvent = opts.metricEvent || 'error_recall';
   try {
     const project = inferProject();
 
@@ -510,7 +522,7 @@ function triggerErrorRecall(db, toolInput, response) {
       // G13: this surface feeds the citation denominator but had zero metering —
       // the G8 gate change (isError→isHardError) could not be volume-verified
       // from metrics. Counter only; no latency (query is bundled in the hook).
-      recordMetric(join(RUNTIME_DIR, '..'), { event: 'error_recall', returned: rows.length });
+      recordMetric(join(RUNTIME_DIR, '..'), { event: metricEvent, returned: rows.length });
       // MED-3 (full audit 2026-07-16): go through the envelope, NOT raw stdout —
       // a raw multi-line write corrupts a co-emitted episode-flush receipt.
       // The follow-up correction (2026-08-17): "two separate JSON lines each parse
@@ -518,11 +530,118 @@ function triggerErrorRecall(db, toolInput, response) {
       // flushEpisode in one handlePostToolUse, and two documents make the parser
       // fall back to plain text — which the renderer drops entirely for
       // PostToolUse. Both receipts vanished. Queue; one envelope is written at exit.
-      queueHookContext('PostToolUse', out);
+      queueHookContext(eventName, out);
     }
   } catch (e) { debugCatch(e, 'triggerErrorRecall'); }
 }
 
+/**
+ * PostToolUseFailure — the event that carries tool calls the HOST judged failed (D#170).
+ *
+ * WHY A SECOND ENTRY POINT AT ALL. `PostToolUse` does not fire for a failed tool call;
+ * Claude Code routes those here. Registering only `PostToolUse` therefore made this
+ * plugin blind to every host-flagged failure, and the only "failures" error-recall ever
+ * saw were commands that exited 0 while printing error-ish text — the classic shape
+ * being `cmd 2>&1 | tail`, where the pipe launders a failure into a success. Verified on
+ * the 2.1.241 bundle (the event and its schema) and by live probe (two genuinely failing
+ * Bash calls, one with a full stack frame, left zero trace in the episode buffer and the
+ * events table while the successful calls either side were recorded).
+ *
+ * THE PAYLOAD IS NOT PostToolUse'S. There is no `tool_response`; the failure text is in
+ * `error`, and `is_interrupt` marks a user cancellation. Reading `tool_response` here
+ * would find undefined and silently do nothing — which is exactly how this class of
+ * wiring bug stays invisible, so the field names are asserted in the tests.
+ *
+ * DELIBERATELY NARROWER THAN THE EVENT. Only `Bash` (this surface queries on a command
+ * plus its output; no other tool has that shape), only when the failure came from a
+ * PROGRAM rather than from the agent's own tool chain (lib/tool-refusal.mjs — 68.9% of
+ * host-flagged failures on the maintainer's machine were guardrails working), and NOT
+ * feeding the episode buffer. That last exclusion is scope, not oversight: episode
+ * entries flow into LLM summarisation and the bugfix save-nudge, whose behaviour under a
+ * sudden influx of failures has not been measured, and this change is already worth a
+ * 3.5x increase in this surface's firing volume.
+ *
+ * NO `isHardError` GATE HERE, AND THAT IS THE POINT — stated because review found it
+ * unwritten and it is a real semantic difference between the two entry points. On the
+ * PostToolUse path the host says nothing about success, so `isHardError` has to GUESS
+ * from vocabulary whether a command failed; here the host has already ruled, and
+ * re-deriving its verdict from the text would only discard cases. The measurable
+ * consequence: `Segmentation fault (core dumped)` and a Rust `panicked at` both score
+ * `isHardError === false` (the first has no error word, the second loses on `\bpanic\b`'s
+ * word boundary), so until this event they could not reach term extraction at all. They
+ * can now. That is the coverage this event was wired for, not an oversight — but it does
+ * mean ERROR_NAMER_RE's `SIG…`/`panicked` alternatives went live here first.
+ *
+ * Off switch: CLAUDE_MEM_ERROR_RECALL_ON_FAILURE=off.
+ */
+async function handlePostToolFailure() {
+  if (String(process.env.CLAUDE_MEM_ERROR_RECALL_ON_FAILURE || '').toLowerCase() === 'off') return;
+
+  let raw;
+  try { raw = await readStdin(); } catch { return; }
+  let hookData;
+  try { hookData = JSON.parse(raw.text); } catch { return; }
+
+  const { tool_name, tool_input, error, is_interrupt } = hookData || {};
+  // The manifest matcher already scopes this to Bash. Re-checking is not redundancy for
+  // its own sake: install.mjs writes a SECOND registration into the user's settings.json,
+  // and a hand-edited matcher there would otherwise hand this path an Edit or a Read.
+  //
+  // A payload whose SHAPE is wrong is recorded, not just dropped. Tests pin the field
+  // names against a payload we construct; they cannot see the host renaming `error` or
+  // changing `tool_name`'s type, and this whole path fails silently by design — the
+  // v3.60 binding outage ran four days on exactly that combination, and hook-errors/ was
+  // the only window that would have shown it. Volume is bounded by the recorder's
+  // 14-day retention and one short line per fire.
+  if (tool_name !== undefined && typeof tool_name !== 'string') {
+    recordHookError(
+      'post-tool-failure:tool_name-type',
+      new TypeError(`tool_name is ${Array.isArray(tool_name) ? 'array' : typeof tool_name}, expected string`),
+      RUNTIME_DIR,
+    );
+    return;
+  }
+  if (tool_name !== 'Bash') return;
+  if (error !== undefined && typeof error !== 'string') {
+    recordHookError(
+      'post-tool-failure:error-type',
+      new TypeError(`error is ${typeof error}, expected string — host payload shape may have changed`),
+      RUNTIME_DIR,
+    );
+    return;
+  }
+
+  const verdict = shouldRecallOnFailure({ error, is_interrupt });
+  if (!verdict.ok) return;
+
+  const toolInput = typeof tool_input === 'string' ? tryParseJson(tool_input) : (tool_input || {});
+  if (typeof toolInput?.command !== 'string' || !toolInput.command) return;
+
+  let db = null;
+  try {
+    db = openDb();
+    if (!db) return;
+    // Same selection, same rendering, same core as the PostToolUse path — only the event
+    // name on the envelope differs. A second copy of the query here is the twin-drift
+    // defect this project keeps paying for.
+    triggerErrorRecall(db, toolInput, error, {
+      eventName: 'PostToolUseFailure',
+      // A separate counter, so the volume this event adds is readable on its own rather
+      // than merged into the existing surface's total. The citation funnel deliberately
+      // keeps ONE `error_recall` surface: these are the same injections to the model, and
+      // splitting the cite-rate denominator would make both halves too small to read.
+      metricEvent: 'error_recall_failure',
+    });
+  } catch (e) {
+    debugCatch(e, 'handlePostToolFailure');
+  } finally {
+    // No flushHookStdout() here: the single flush after the event switch owns writing
+    // the envelope, and two flush points is how a process ends up emitting two JSON
+    // documents — the degradation that made BOTH receipts vanish in v3.68.
+    if (db) try { db.close(); } catch {}
+  }
+}
+
 // ─── Stop Handler ───────────────────────────────────────────────────────────
 
 async function handleStop() {
@@ -1983,6 +2102,8 @@ function normalizeToolResponse(toolResponse) {
 try {
   switch (event) {
     case 'post-tool-use':    await handlePostToolUse(); break;
+    // Host-flagged tool failures arrive on their own event; PostToolUse never sees them.
+    case 'post-tool-failure': await handlePostToolFailure(); break;
     case 'session-start':    await handleSessionStart(); break;
     case 'pre-compact':      await handlePreCompactDispatch(); break;
     case 'stop':             await handleStop(); break;

package/hooks/hooks.json

@@ -84,6 +84,18 @@
         ]
       }
     ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" hook.mjs post-tool-failure",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "*",

package/install.mjs

@@ -718,6 +718,19 @@ const memPostToolRecall = {
   }]
 };
 
+// D#170. A SEPARATE event from PostToolUse, not a variant of it: Claude Code does not
+// fire PostToolUse for a tool call it judged failed, so without this registration the
+// plugin never sees a single host-flagged failure. Matched on Bash alone — the surface
+// it feeds queries on a command plus its output, and no other tool has that shape.
+const memPostToolFailure = {
+  matcher: 'Bash',
+  hooks: [{
+    type: 'command',
+    command: nodeHook('hook.mjs', 'post-tool-failure'),
+    timeout: 5
+  }]
+};
+
 const memSessionStart = {
   matcher: 'startup|clear|compact',
   hooks: [{
@@ -819,6 +832,7 @@ const memPreAgentInject = {
 const hookConfigs = {
   PreToolUse: [memPreToolRecall, memPreSkillBridge, memPreAgentInject],
   PostToolUse: [memPostToolUse, memPostToolRecall],
+  PostToolUseFailure: [memPostToolFailure],
   PreCompact: [memPreCompact],
   SessionStart: [memSessionStart],
   Stop: [memStop],

package/lib/error-recall-core.mjs

@@ -127,15 +127,26 @@ const ERROR_RECALL_HALF_LIFE_MS = '1209600000.0';
  *   (decay reference) and @floor (|bm25| minimum). Named rather than positional
  *   so the binding cannot silently renumber when the statement is rearranged.
  */
-export function errorRecallSql(limit = ERROR_RECALL_LIMIT) {
-  // Number.isFinite before trunc: `Number('Infinity')` is a number and truncates to
-  // Infinity, which interpolates as `LIMIT Infinity` and throws at prepare(). Not an
-  // injection (every string form coerces to the default) but a crash where a fallback
-  // belongs.
+/**
+ * The row cap, coerced. ONE body, because the SQL builder and the rerank's control flow
+ * both need it and a second copy let them disagree: at `limit: 0` the rerank compared
+ * against the raw value, short-circuited its fallback and became a filter, while the SQL
+ * had already fallen back to 3.
+ *
+ * Number.isFinite before trunc: `Number('Infinity')` is a number and truncates to
+ * Infinity, which interpolates as `LIMIT Infinity` and throws at prepare(). Not an
+ * injection (every string form coerces to the default) but a crash where a fallback
+ * belongs.
+ */
+function sanitizeErrorRecallLimit(limit) {
   const asNum = Number(limit);
-  const n = Number.isFinite(asNum) && asNum >= 1
+  return Number.isFinite(asNum) && asNum >= 1
     ? Math.max(1, Math.trunc(asNum))
     : ERROR_RECALL_LIMIT;
+}
+
+export function errorRecallSql(limit = ERROR_RECALL_LIMIT) {
+  const n = sanitizeErrorRecallLimit(limit);
   // No floor in the SQL: the gate is SET-LEVEL and lives in selectErrorRecall. See
   // its docblock for why. This statement is the pre-floor one plus a bm25_raw column.
   return `
@@ -183,6 +194,40 @@ export function errorRecallFtsQuery(terms) {
   return (terms || []).map((t) => `"${String(t).replace(/"/g, '""')}"`).join(' OR ');
 }
 
+/**
+ * The ERROR-FIRST form of the same expression: a row must carry at least one term that
+ * came from the FAILURE, while every term — command words included — stays in the
+ * expression so bm25 still sums their contribution.
+ *
+ * The redundant-looking second clause is the point. Dropping command words from the
+ * QUERY was measured against the live DB in D#136 and regressed two of five replays:
+ * `database` and `vitest` were carrying domain anchoring, not noise. This keeps them
+ * scoring while denying them the power to admit a row on their own.
+ *
+ * Module-private on purpose: selectErrorRecall is the only caller, and the tests assert
+ * on the expression it REPORTS (`errorFirstQuery`) rather than importing the builder —
+ * a guard through the real path beats one through a side door. Exporting it would add a
+ * name to the knip baseline for no consumer (the #9675 precedent).
+ *
+ * @returns {string|null} null when there is no error term to require.
+ */
+function errorRecallErrorFirstQuery(terms, errWords) {
+  if (!errWords || !errWords.length) return null;
+  const or = (list) => list.map((t) => `"${String(t).replace(/"/g, '""')}"`).join(' OR ');
+  return `(${or(errWords)}) AND (${or(terms)})`;
+}
+
+/**
+ * Rerank kill-switch. Default ON — see selectErrorRecall for the measurement.
+ * `CLAUDE_MEM_ERROR_RECALL_RERANK=off` restores the flat-OR ordering exactly.
+ *
+ * Module-private for the same reason as the builder above; the switch is exercised
+ * end-to-end through selectErrorRecall in the test suite, which is where it has to work.
+ */
+function errorRecallRerankEnabled() {
+  return String(process.env.CLAUDE_MEM_ERROR_RECALL_RERANK || '').toLowerCase() !== 'off';
+}
+
 /**
  * Decide whether error-recall fires, and select its rows.
  *
@@ -219,7 +264,69 @@ export function selectErrorRecall(db, {
   // one. v3.61.0 shipped an unscaled floor and injected 0/8 on fresh installs.
   const effective = base > 0 ? base * corpusFloorScale(db) : 0;
 
-  const rows = db.prepare(errorRecallSql(limit)).all({ q: ftsQuery, project, now });
+  const stmt = db.prepare(errorRecallSql(limit));
+
+  // ── ERROR-FIRST RERANK (D#167) ──────────────────────────────────────────────
+  // The flat OR admits a row on ANY term, so a memory that merely shares the command's
+  // vocabulary competes for the three slots on equal footing with one that names the
+  // failure. Measured on the live DB over 52 real failing commands (with their real
+  // stderr, extracted from 1110 transcripts) x 15 projects, ~715 firing cases. Rows that
+  // match NO error term at all, and cases whose TOP-1 row is one of those — the top row
+  // being the one whose lesson_learned is inlined verbatim into the model's context:
+  //
+  //                                          cmd-only rows      cmd-only at TOP-1
+  //   v3.78.0 (flat OR, banner terms)        764/1947  39.2%    302/714   42.3%
+  //   flat OR + ERROR_NAMER_RE               780/1941  40.2%    301/715   42.1%
+  //   + error-first rerank  (shipped)        434/1941  22.4%    154/715   21.5%
+  //
+  // Read the middle row before reaching for the term fix alone: naming the failure did
+  // NOT reduce command-vocabulary injection, it nudged it up. Better terms are more
+  // specific, so they match fewer rows, so the flat OR has MORE room to fill the three
+  // slots with whatever shares the command's words. Terms and ranking are two
+  // independent defects and only the pair moves this number.
+  //
+  // The obvious alternative — make the error term MANDATORY and stop there — was
+  // measured too: 1499 rows (−22.8%) and 157 of 715 cases (22.0%) injecting nothing,
+  // with the loss concentrated in small projects. That is the magnitude floor's failure
+  // mode wearing a different hat (see errorRecallBm25Floor above), so it is not what
+  // ships. This REORDERS and never removes: rows that only match the command fall to
+  // slots 2-3 instead of being deleted, and when NOTHING in the project matches an
+  // error term the result is byte-identical to the flat OR. The residual ~21.5% is
+  // essentially that set — verified, not assumed: of the cases the mandatory form
+  // silences, 0 had a base set containing an error-matching row.
+  //
+  // Cost is one extra query only when the primary comes up short of the cap. D#136
+  // rejected this shape on the grounds that "the primary always filled its LIMIT 3" —
+  // true of the five cases it replayed, false at 715, where the primary leaves hundreds
+  // of slots for the fallback to fill.
+  let rows;
+  const errorFirst = errorRecallRerankEnabled()
+    ? errorRecallErrorFirstQuery(plan.terms, plan.errWords)
+    : null;
+  const primary = errorFirst ? stmt.all({ q: errorFirst, project, now }) : [];
+  // Compare against the SANITIZED cap, not the raw argument. errorRecallSql coerces
+  // (finite, >= 1, else the default) before interpolating, so the raw value and the one
+  // the SQL used can disagree — and at `limit: 0` the raw comparison short-circuits the
+  // fallback, turning the rerank into the filter this face deliberately rejected.
+  // Unreachable from the hook (it passes no limit), found by fuzzing in review.
+  const cap = sanitizeErrorRecallLimit(limit);
+  if (primary.length >= cap) {
+    rows = primary;
+  } else {
+    // Fallback fills the remaining slots from the unchanged flat-OR result, skipping
+    // what the primary already returned. `rows` therefore has the same LENGTH as the
+    // pre-rerank behaviour in every case, including the case where primary is empty.
+    const flat = stmt.all({ q: ftsQuery, project, now });
+    rows = [...primary];
+    for (const r of flat) {
+      if (rows.length >= cap) break;
+      // The id check is load-bearing, not defensive: the error-first match set is a
+      // SUBSET of the flat one, so every primary row appears again in `flat`. Without
+      // this, the top row is injected twice and one of three slots is wasted. Review
+      // measured the mutant: ids 1,2,3 -> 1,1,2.
+      if (!rows.some((x) => x.id === r.id)) rows.push(r);
+    }
+  }
 
   // SET-LEVEL gate, the shape UPS already uses (read the top row; on failure drop the
   // WHOLE set) rather than filtering row by row.
@@ -247,10 +354,49 @@ export function selectErrorRecall(db, {
   // switched to max(): UPS gates on `ftsRows[0]` the same way, and one face quietly
   // disagreeing with the other about what "the top hit" means is worse than the
   // occasional veto. Stated here because the comment above used to claim otherwise.
+  //
+  // With the rerank above, `rows[0]` is the top row of the ERROR-FIRST result whenever
+  // one exists. The gate is therefore applied to the row it is actually about — the
+  // best row that mentions the failure — instead of to whatever the flat OR floated up.
+  //
+  // AND IT ALSO CHANGES THE SCALE, which the first version of this comment missed and
+  // pre-release review caught. `(errWords) AND (allTerms)` repeats every error term, and
+  // FTS5's bm25() sums over phrase instances, so a PRIMARY row's |bm25_raw| is
+  // systematically larger than the same row's flat-OR score — measured on one row in an
+  // in-memory index, 1.334 -> 1.779. Rows in the same result set can therefore carry two
+  // different scales (primary rows error-first, fallback rows flat).
+  //
+  // What that costs: CALIBRATED_ERROR_RECALL_BM25_FLOOR = 10.5 was derived from the
+  // PRE-RERANK distribution — the gap between filler p75 10.99 and relevant min 10.93 in
+  // the table above. Re-running `benchmark/error-recall-suite.mjs --scores` with the
+  // rerank ON moves filler p75 to 20.27 and relevant min to 21.87, so 10.5 no longer
+  // sits in any gap. The drift is toward a LOOSER gate on sets that have a primary and
+  // an unchanged one on sets that do not (empty primary keeps the flat scale), which may
+  // be an improvement; nothing has measured it.
+  //
+  // This is documented rather than fixed because the floor's default is 0 — nothing
+  // ships gated. Anyone switching it on must re-derive the constant with the rerank in
+  // whatever state they intend to run, NOT reuse the table above.
   if (effective > 0 && rows.length && Math.abs(rows[0].bm25_raw) < effective) {
     return {
-      rows: [], terms: plan.terms, ftsQuery, floor: effective, suppressed: rows.length,
+      rows: [],
+      terms: plan.terms,
+      ftsQuery,
+      // Reported here too: this is the path where knowing which expression ranked the
+      // row the gate just rejected matters MOST, and the first version omitted it.
+      errorFirstQuery: errorFirst,
+      floor: effective,
+      suppressed: rows.length,
     };
   }
-  return { rows, terms: plan.terms, ftsQuery, floor: effective, suppressed: 0 };
+  return {
+    rows,
+    terms: plan.terms,
+    ftsQuery,
+    // The expression that actually ranked the set, so the calibration suite and any
+    // future debugging read the query that ran rather than the one that would have.
+    errorFirstQuery: errorFirst,
+    floor: effective,
+    suppressed: 0,
+  };
 }

package/lib/tool-refusal.mjs

@@ -0,0 +1,117 @@
+// Did this tool call fail because a PROGRAM failed, or because the agent's own
+// tool chain said no?
+//
+// WHY THIS EXISTS. Claude Code delivers host-flagged tool failures to the
+// `PostToolUseFailure` event (D#170), which is where error-recall gets its coverage of
+// real failures. But that event fires for EVERY failed call, and a large share of them
+// are not failures at all in the sense that matters here — they are guardrails working:
+// a §8 SAFETY hook denying an `rm -rf $VAR`, a sandbox refusing a syscall, a policy hook
+// steering a `grep` to the AST tool. Measured over 1110 transcripts, 558 of 810
+// host-flagged Bash failures (68.9%) were of that kind — one number, re-measured with the
+// shipped predicate after review found two irreconcilable figures in this file and the
+// CHANGELOG. Reproduce with `node benchmark/error-recall-live-replay.mjs --host-failures`,
+// which now buckets by the gate's own reason instead of lumping refusals with empties.
+//
+// Recalling a past lesson because a permission prompt was declined is noise by
+// construction, and on the lowest-cited injection surface in the system it is the kind of
+// noise that discredits the rest.
+//
+// THE ERROR DIRECTIONS ARE NOT SYMMETRIC, and the list below is tuned accordingly:
+//
+//   false "refusal"  → we stay silent on a real failure. Costs nothing beyond the
+//                      status quo, which is silence for every host-flagged failure.
+//   missed refusal   → we inject three memories about a denied permission prompt.
+//
+// So every entry is anchored on a tool-chain marker — a bracketed plugin tag, a spec
+// section marker, a sandbox syscall name — rather than a generic word like "denied" or
+// "permission", which real programs print constantly (`chmod`, `docker`, `sudo`, HTTP
+// 403 handlers).
+//
+// "NO ORDINARY PROGRAM EMITS THESE" IS TOO STRONG, AND REVIEW MEASURED IT. Over the same
+// 1110-transcript corpus, three sentinels appear in the stdout of SUCCESSFUL commands:
+// `[claudemd]` (21), `No such tool available` (10), `requested permission(s) to use` (7)
+// — mostly this repo's own test runners printing hook output. When such a runner FAILS,
+// the gate swallows a real failure. That is the cheap direction (see above), but the
+// claim is "anchored on a marker real programs rarely emit", not "never".
+//
+// Two of those three (`[claudemd]`, `requested permissions? to use`) had ZERO matches
+// among the 558 actual refusals in that corpus — they are speculative, covering hook
+// stacks other than this one, and today they pay only their false-positive cost. Kept
+// deliberately: a user running those hooks gets the protection, and the cost is silence
+// on a failure that was already silent before this event existed. Delete them if a
+// measurement ever shows them costing more than that.
+//
+// THIS RATIO IS ONE MACHINE'S PROFILE. 68.9% is what the maintainer's own hook stack
+// produces; a user with no policy hooks will see close to 0%. The filter is correctness
+// for whoever has those hooks, not a tuning constant — do not treat the percentage as a
+// property of the product.
+
+/**
+ * Sentinels that identify a refusal emitted by the agent's own tool chain.
+ * Ordered roughly by observed frequency; the array is small enough that order is
+ * cosmetic.
+ */
+export const REFUSAL_SENTINELS = [
+  // Sandbox / seccomp layers refusing to run the command at all.
+  /apply-seccomp: unshare\(/,
+  /sandbox\.excludedCommands/,
+  // Spec / policy hooks (claudemd and friends) denying a command by rule. Anchored on
+  // the SECTION MARKER at the start of the text, not on the one section that was found
+  // first: pre-release review scanned the same corpus and found the family is wider than
+  // `§8` — `§7 Ship-baseline` (a policy hook blocking `git push`), `§11 MEMORY.md`,
+  // `§10-V Specificity`, `§10-V prose scan`. The `§7` shape alone was 13 of 135 firing
+  // cases (9.6%), and it does not merely waste a slot: its own boilerplate becomes the
+  // query, so `git push` blocked by a red-CI rule injected three memories about
+  // statusline adoption. The other three shapes were silent only because
+  // planErrorRecall found no term in them — luck, not this gate.
+  //
+  // `§` followed by a digit at the very start of the failure text is a spec citation. No
+  // compiler, runtime or CLI opens its stderr that way.
+  /^\s*§\s*\d/,
+  /§\d[\w.-]*\s+[A-Z][\w-]*[^\n]{0,60}:\s/,
+  /\[claudemd\]/,
+  // Plugin hooks that deny-and-redirect rather than let the command run.
+  /\[code-graph\][^\n]{0,80}denied/i,
+  // Host-level refusals: the tool was not available in this context.
+  /No such tool available/i,
+  /\bis not available to you as the coordinator\b/i,
+  // The human said no. Not a program failure, and re-asking with a recalled memory
+  // attached is the wrong response to it.
+  /user doesn'?t want to (?:take this action|proceed)/i,
+  /requested permissions? to use/i,
+];
+
+/**
+ * @param {string} text The failure text (`error` on a PostToolUseFailure payload).
+ * @returns {boolean} true when the failure came from the tool chain, not the program.
+ */
+export function isToolChainRefusal(text) {
+  if (typeof text !== 'string' || !text) return false;
+  return REFUSAL_SENTINELS.some((re) => re.test(text));
+}
+
+/**
+ * Should error-recall run for this failed tool call?
+ *
+ * Three reasons to stay silent, each for a different kind of "this is not a program
+ * failure I can recall anything useful about":
+ *
+ *  - `is_interrupt` — the HOST's own flag for "the user stopped it". A cancelled
+ *    command has no failure to explain, and this is the one discriminator that comes
+ *    from the host rather than from pattern-matching its text.
+ *  - a tool-chain refusal (above).
+ *  - nothing to read: an empty or near-empty error string cannot produce query terms,
+ *    and the 10-character floor matches the one PostToolUse already applies to
+ *    `tool_response` so the two entry points do not disagree about what "no output"
+ *    means.
+ *
+ * @param {{error?: string, is_interrupt?: boolean}} payload
+ * @returns {{ok: boolean, reason?: string}}
+ */
+export function shouldRecallOnFailure(payload) {
+  if (payload?.is_interrupt === true) return { ok: false, reason: 'interrupt' };
+  const text = typeof payload?.error === 'string' ? payload.error : '';
+  if (text.length < 10) return { ok: false, reason: 'empty' };
+  if (isToolChainRefusal(text)) return { ok: false, reason: 'refusal' };
+  return { ok: true };
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.78.0",
+  "version": "3.79.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.78.0",
+      "version": "3.79.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.78.0",
+  "version": "3.79.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",
@@ -92,6 +92,7 @@
     "lib/keyctx-marker.mjs",
     "lib/inject-search-core.mjs",
     "lib/error-recall-core.mjs",
+    "lib/tool-refusal.mjs",
     "lib/relevance-floor.mjs",
     "lib/get-core.mjs",
     "lib/browse-core.mjs",

package/source-files.mjs

@@ -153,6 +153,10 @@ export const SOURCE_FILES = [
   // injection) and by benchmark/error-recall-suite.mjs (offline calibration) — the
   // hook is the one that breaks on a missing manifest entry.
   'lib/error-recall-core.mjs',
+  // D#170: the PostToolUseFailure gate. hook.mjs imports it on the failure path and
+  // benchmark/error-recall-live-replay.mjs scores the SAME predicate, so a missing
+  // registration would ship a hook that cannot load its own filter.
+  'lib/tool-refusal.mjs',
   // Corpus-size ramp for absolute relevance floors. Imported by BOTH floor-bearing
   // injection faces: scripts/user-prompt-search.js (standalone hook) and
   // lib/error-recall-core.mjs. Missing here = UserPromptSubmit dies on auto-update.