claude-mem-lite 3.74.1 → 3.75.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -4,7 +4,8 @@
 
 `claude-mem-lite` is a **persistent memory** (also called *long-term memory* or *cross-session context*) system for **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — Anthropic's CLI coding agent. It runs as an **[MCP](https://modelcontextprotocol.io/) server** plus a set of Claude Code hooks, automatically capturing coding observations, decisions, and bug fixes during sessions, then providing hybrid full-text + semantic search to recall them later.
 
-Compared to general-purpose LLM memory frameworks like [`mem0`](https://github.com/mem0ai/mem0) or the MCP reference [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) server, claude-mem-lite is purpose-built for Claude Code's hook lifecycle: episode batching cuts LLM calls 7–10× vs the original [claude-mem](https://github.com/thedotmack/claude-mem) (an estimated ~600× lower total cost — see the cost model below; this is an architecture estimate, not a measured benchmark), while the hybrid FTS5 + TF-IDF retriever benchmarks at 0.88 Recall@10 / 0.96 Precision@10.
+Compared to general-purpose LLM memory frameworks like [`mem0`](https://github.com/mem0ai/mem0) or the MCP reference [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) server, claude-mem-lite is purpose-built for Claude Code's hook lifecycle: episode batching cuts LLM calls 7–10× vs the original [claude-mem](https://github.com/thedotmack/claude-mem) (an estimated ~600× lower total cost — see the cost model below; this is an architecture estimate, not a measured benchmark), while the hybrid FTS5 + TF-IDF retriever benchmarks at 0.90 Recall@10 / 0.85 Precision@10
+(see [Search Quality](#search-quality) for the reproduction command).
 
 > 中文简介：claude-mem-lite 是 Claude Code 的轻量级**持久化记忆 / 长期记忆 / 跨会话上下文**插件，基于 MCP 协议 + 钩子机制，自动捕获编码会话中的决策、修复和上下文，并通过 FTS5 + TF-IDF 混合检索召回。详见 [中文 README](README.zh-CN.md)。
 
@@ -681,10 +682,16 @@ path and fails on regression.
 | Metric | Score (production-hybrid) |
 |--------|---------------------------|
 | Recall@10 | 0.90 |
-| Precision@10 | 0.79 |
+| Precision@10 | 0.85 |
 | nDCG@10 | 0.97 |
-| MRR@10 | 0.97 |
-| P95 search latency | ~3ms |
+| MRR@10 | 0.96 |
+| P95 search latency | ~1.8ms |
+
+> **Where these numbers come from.** Reproduce with
+> `node benchmark/benchmark.mjs --production-hybrid` (deterministic — same fixture corpus,
+> same query set, no sampling). The CI reference capture is `benchmark/baseline.json`, and
+> `npm run benchmark:gate` fails the build when a run drifts more than 5% from it. This is
+> the single source for every retrieval figure quoted in this README.
 
 > **Note on the path measured.** Earlier versions of this table reported the *lexical*
 > FTS-only path (Precision@10 0.96, P95 0.15ms). The hybrid vector arm trades raw
@@ -761,6 +768,12 @@ npm run benchmark:gate    # CI gate: fails if metrics regress beyond 5% toleranc
 
 ## Environment Variables
 
+Every environment variable the shipped code reads is listed below, grouped by what it
+controls. Booleans accept `1` unless noted. Anything not listed here is not read by
+claude-mem-lite.
+
+### Core
+
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CLAUDE_MEM_DIR` | Custom data directory. All databases, runtime files, and managed resources are stored here. | `~/.claude-mem-lite/` |
@@ -773,6 +786,111 @@ npm run benchmark:gate    # CI gate: fails if metrics regress beyond 5% toleranc
 | `MEM_NO_AUTO_ADOPT` | Global opt-out for auto-adopt (v2.82.0+). `1` prevents the first-SessionStart auto-write of the invited-memory sentinel across **all** projects. For per-project opt-out use `claude-mem-lite adopt --disable` instead (writes a durable `<memdir>/.mem-no-auto-adopt` sentinel that survives marker deletion). | _(disabled)_ |
 | `MEM_NO_ADOPT_HINT` | Silences the one-line "Invited-memory 未启用：`claude-mem-lite adopt`…" hint that SessionStart appends when the current project hasn't been adopted. Since v2.82.1 auto-adopt fires on first SessionStart for any install path, so this hint typically surfaces only when you've explicitly opted out (`MEM_NO_AUTO_ADOPT=1` or `claude-mem-lite adopt --disable`). | _(disabled)_ |
 
+### What gets injected into your context
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_MEM_ALL_TOOLS` | `1` exposes all 20 MCP tools in `tools/list` instead of the 9 core ones (pre-v2.34.0 behavior). The 11 hidden tools stay callable by exact name either way. | _(9 core)_ |
+| `CLAUDE_MEM_FILE_INTEL` | `0` disables the file-intel block injected before `Read` (past observations about the file you are about to open). | _(on)_ |
+| `CLAUDE_MEM_FILE_INTEL_MIN_TOKENS` | Files smaller than this stay silent — file-intel only pays for itself on large files. | `800` |
+| `CLAUDE_MEM_REREAD_GUARD` | `0` disables the warning when the same file is read twice in a session. Never fires on `offset`/`limit` paging. | _(on)_ |
+| `CLAUDE_MEM_REREAD_MIN_TOKENS` | Token floor below which the re-read guard stays silent. | `600` |
+| `CLAUDE_MEM_PRETOOL_NUDGE` | `1` extends the pre-tool recall nudge from `Read` to other tools. | _(Read only)_ |
+| `CLAUDE_MEM_KEEP_LOW_SIGNAL` | `1` keeps low-signal observations that the deterministic filter would otherwise drop before dedup/vector work. | _(filtered)_ |
+| `CLAUDE_MEM_NO_TEMPLATE_REFRESH` | `1` stops SessionStart from refreshing the adopted `CLAUDE.md` managed block when the shipped template changes. | _(refreshes)_ |
+| `MEM_QUIET_HOOKS` | See Core above — the broadest injection-volume switch. | _(disabled)_ |
+
+### Retrieval tuning
+
+Prompt-time search (`UPS_*` = the UserPromptSubmit surface). Defaults are the values the
+benchmark and A/B harness are calibrated against — changing them invalidates the numbers in
+[Search Quality](#search-quality).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_MEM_UPS_MAX_RESULTS` | Max memories injected per prompt. | `3` |
+| `CLAUDE_MEM_UPS_REQUIRE_SIGNAL` | `0` restores always-search; by default the prompt must carry an explicit retrieval signal. | _(signal required)_ |
+| `CLAUDE_MEM_UPS_BM25_MIN` | BM25 relevance floor for a result to be injected. | `1e-5` |
+| `CLAUDE_MEM_UPS_BM25_MIN_FOLLOWUP` | Looser floor for follow-up prompts inside an already-injected session. | `5e-6` |
+| `CLAUDE_MEM_UPS_OR_BM25_MIN` | Floor applied to the OR-fallback arm (looser query, needs a stricter floor). | `30` |
+| `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. | `584` |
+| `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` |
+| `MEM_CROSS_PROJECT_BOOST` | Multiplier for matches from other projects (∈ [0,1]); raise it for installs that want more cross-project sharing. | `0.4` |
+| `MEM_OR_FALLBACK_MAX_TOKENS` | Max query tokens allowed into the OR fallback (∈ [0,50]). | `8` |
+| `CLAUDE_MEM_CJK_PREC_MIN` | Precision floor for CJK segmentation candidates. | `0.2` |
+| `CLAUDE_MEM_AUTO_DEEP` | `0` disables automatic deep-search escalation (one Haiku call rewriting a weak query into keyword/concept/HyDE variants). Explicit `deep: true` still works. | _(auto)_ |
+| `CLAUDE_MEM_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. | _(off)_ |
+
+### Citation tracking and feedback
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_MEM_NO_CITATION_TRACK` | `1` disables both the access-count bump and the decay loop — no citation bookkeeping at all. | _(enabled)_ |
+| `MEM_DISABLE_CITATION_DECAY` | `1` disables only the decay writes, keeping access-count bumps. | _(enabled)_ |
+| `CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD` | Session cite-rate below which demotion is suppressed (promotion always proceeds). | `0.02` |
+| `CLAUDE_MEM_NO_CITE_NUDGE` | `1` fully silences the cite-back nudge. | _(enabled)_ |
+| `CLAUDE_MEM_CITE_NUDGE_THRESHOLD` | Cite-rate below which the nudge fires. | `0.6` |
+| `CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED` | Minimum injection volume before the ratio gate is judged at all. | `5` |
+| `CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER` | Consecutive low-cite sessions before the nudge goes quiet; `0` = never silence. | `3` |
+| `CLAUDE_MEM_METRICS` | `1` records feature-injection counters surfaced by `claude-mem-lite stats`. | _(off)_ |
+
+### Background work
+
+All of these turn *off* work that normally happens in the background. Nothing here changes
+what is already stored — only whether new work runs.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_MEM_SKIP_SUMMARY` | Skip the LLM session summary at Stop. | _(runs)_ |
+| `CLAUDE_MEM_SKIP_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)_ |
+| `CLAUDE_MEM_SKIP_MAINTAIN` | Skip the 24h auto-maintain pass (decay, purge, backup). | _(runs)_ |
+| `CLAUDE_MEM_SKIP_OPTIMIZE` | Skip the LLM optimization pass (re-enrich, normalize, cluster-merge). | _(runs)_ |
+| `CLAUDE_MEM_SKIP_AUTO_DEDUP_FUZZY` | Skip the MinHash near-duplicate pass, keeping exact dedup. | _(runs)_ |
+| `CLAUDE_MEM_SKIP_MARKER_GC` | Skip the runtime-marker sweep. | _(runs)_ |
+| `CLAUDE_MEM_SKIP_UPDATE` | Skip the 24h auto-update check against GitHub Releases. | _(runs)_ |
+| `CLAUDE_MEM_SKIP_SIG_VERIFY` | Skip Ed25519 signature verification of a downloaded update. **Escape hatch — leaves updates unauthenticated.** | _(verifies)_ |
+| `CLAUDE_MEM_SKIP_REPOS` | Skip skill/agent registry seeding during install. | _(seeds)_ |
+| `CLAUDE_MEM_NO_LESSON_RETRY` | `1` disables the one-shot retry that re-asks for a missing `lesson_learned`. | _(retries)_ |
+| `CLAUDE_MEM_FLUSH_TIMEOUT` | Seconds the Stop hook waits for pending episode flushes. | `15` |
+| `CLAUDE_MEM_BACKUP_BUDGET_MB` | Disk budget for backup snapshots; the next maintain/save evicts oldest snapshots past the 7-day undo grace. | `256` |
+
+### Experimental
+
+Off or shadow-mode by default. These are measurement arms, not finished features — behavior
+and names can change between releases.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_MEM_RECOMMEND_MODE` | Skill-recommendation engine: `shadow` (log would-be recommendations, inject nothing) or `off`. **`live` is parsed but not implemented** — live injection is Phase 2. Setting it runs shadow and prints one warning to stderr per process; `claude-mem-lite doctor` also reports it as an inert flag. | `shadow` |
+| `CLAUDE_MEM_TASK_IMPERATIVE` | `on`/`1` injects the single most relevant lesson at prompt position under an imperative template. | _(off)_ |
+| `CLAUDE_MEM_SUBAGENT_INJECT` | Dispatch-time memory injection for subagents. | _(off)_ |
+| `CLAUDE_MEM_SALIENCE` | Selects a comprehension-bridge arm (`bridge`, `bind`); unset = current default behavior. | _(unset)_ |
+| `CLAUDE_MEM_EDGE_DECAY` | Enables decay of file↔observation edges. | _(off)_ |
+| `CLAUDE_MEM_EDGE_DECAY_K` | Edge-decay threshold when the flag above is on (clamped to ≥1). | `3` |
+
+### Internal and test-only
+
+Set by the tool or by the test harness. Setting these by hand is not supported:
+`CLAUDE_MEM_HOOK_RUNNING`, `CLAUDE_MEM_BINDING_HEALED`, `CLAUDE_MEM_BRIDGE_FAKE`,
+`CLAUDE_MEM_NO_DELAY`, `CLAUDE_MEM_CATCH_SAMPLE`, `CLAUDE_MEM_QUIET_TRACE`,
+`CLAUDE_MEM_DB_PATH`, `CLAUDE_MEM_RUNTIME_DIR`, `MEM_DISABLE_SPAWN_LOG`.
+`CLAUDE_PLUGIN_ROOT` is set by Claude Code itself.
+
+Three more are set by `vitest.config.mjs` / `tests/global-setup.mjs` and exist only to
+keep a test run off the live database: `CLAUDE_MEM_TEST_GUARD` (`1` arms the guard, `off`
+opts a test out), `CLAUDE_MEM_TEST_REALDIR` (the live data dir, captured before the suite
+relocates anything) and `CLAUDE_MEM_TEST_SANDBOX` (this run's throwaway dir). With the
+guard armed, any resolution that lands on the live data dir is redirected to the sandbox
+instead — including from a subprocess that inherited the ambient environment. Unset in
+normal use, and inert when unset.
+
 ## FAQ
 
 ### What is a memory system for Claude Code?

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 `claude-mem-lite` 是 **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)**（Anthropic 官方 CLI 编程代理）的 **持久化记忆系统**（也称 **长期记忆 / 跨会话上下文 / Claude Code 记忆插件**）。它以 **[MCP](https://modelcontextprotocol.io/) 服务器** + Claude Code 钩子（hooks）的形式运行，在编码会话中自动捕获观察记录、决策、bug 修复，并通过 FTS5 全文检索 + TF-IDF 向量的混合检索召回历史上下文。
 
-与 [`mem0`](https://github.com/mem0ai/mem0)、MCP 官方参考实现的 [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 服务器等通用 LLM 记忆框架相比，claude-mem-lite 专为 Claude Code 的钩子生命周期定制：episode 批处理把 LLM 调用量相比原版 [claude-mem](https://github.com/thedotmack/claude-mem) 减少 7-10 倍（综合成本估算下降约 600 倍 —— 见下方成本模型，属架构估算而非实测基准）；FTS5 + TF-IDF 混合检索在 30 个查询的基准上达到 **Recall@10 = 0.88 / Precision@10 = 0.96**。
+与 [`mem0`](https://github.com/mem0ai/mem0)、MCP 官方参考实现的 [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 服务器等通用 LLM 记忆框架相比，claude-mem-lite 专为 Claude Code 的钩子生命周期定制：episode 批处理把 LLM 调用量相比原版 [claude-mem](https://github.com/thedotmack/claude-mem) 减少 7-10 倍（综合成本估算下降约 600 倍 —— 见下方成本模型，属架构估算而非实测基准）；FTS5 + TF-IDF 混合检索在 30 个查询的基准上达到 **Recall@10 = 0.90 / Precision@10 = 0.85**（复现命令见[搜索质量](#搜索质量)一节）。
 
 无需外部服务。单一 SQLite 数据库。开销极低。
 
@@ -572,17 +572,25 @@ claude-mem-lite/
 
 ## 搜索质量
 
-基于 200 条观察和 30 个查询（标准 + 困难负样本类别）的基准测试结果：
+基于 200 条观察和 30 个查询（标准 + 困难负样本类别）的基准测试结果，测量的是
+**production-hybrid** 检索路径（FTS5 BM25 + TF-IDF 向量 + RRF）——也就是 `mem_search` /
+`recall` 实际走的那条路径：
 
-| 指标 | 得分 |
+| 指标 | 得分（production-hybrid） |
 |------|------|
-| Recall@10 | 0.88 |
-| Precision@10 | 0.96 |
-| nDCG@10 | 0.95 |
-| MRR@10 | 0.95 |
-| P95 搜索延迟 | 0.15ms |
-
-基准测试作为 CI 门控运行（`npm run benchmark:gate`），防止搜索质量回退。
+| Recall@10 | 0.90 |
+| Precision@10 | 0.85 |
+| nDCG@10 | 0.97 |
+| MRR@10 | 0.96 |
+| P95 搜索延迟 | ~1.8ms |
+
+> **数据来源。** 复现命令：`node benchmark/benchmark.mjs --production-hybrid`（确定性输出——
+> 固定语料、固定查询集、无采样）。CI 参考快照是 `benchmark/baseline.json`，
+> `npm run benchmark:gate` 在偏离超过 5% 时让构建失败。本 README 中所有检索指标都以此为唯一来源。
+
+> **关于测量路径。** 本表早期版本报告的是 *lexical* 纯 FTS 路径（Precision@10 0.96、
+> P95 0.15ms）。混合向量臂用 precision@10 换取更高的 recall / nDCG / MRR——它会召回超出字面
+> 匹配的语义相关候选；门控现在测量混合路径，所以这些数字反映的是 `mem_search` 的真实行为。
 
 ## 开发
 

package/haiku-client.mjs

@@ -190,8 +190,14 @@ export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500, temp
   // out-of-credit key must not silently drop background summaries.
   let primary = null;
   try {
+    // callModelAPI, not a second copy of it: the two were byte-identical apart from
+    // where the model id came from (MODEL_MAP[model] vs resolveModel().api — the same
+    // value, since resolveModel().cli is a MODEL_MAP key) and a hardcoded 'haiku-api'
+    // log label that lied under CLAUDE_MEM_MODEL=sonnet. Two copies of an HTTP client
+    // means every proxy fix has to land twice, on the path where missing the proxy is
+    // the difference between 1.4s and 13.5s.
     primary = mode === 'api'
-      ? await callHaikuAPI(prompt, { timeout, maxTokens, temperature })
+      ? await callModelAPI(prompt, resolveModel().cli, { timeout, maxTokens, temperature })
       : await callOpenRouterAPI(prompt, resolveModel().cli, { timeout, maxTokens, temperature });
   } catch (e) {
     debugCatch(e, `callHaiku:${mode}`);
@@ -683,63 +689,6 @@ export async function callModelCLIAsync(prompt, model, { timeout }) {
   return second.result;
 }
 
-// ─── API Mode ────────────────────────────────────────────────────────────────
-
-async function callHaikuAPI(prompt, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) return null;
-
-  const { api: modelId } = resolveModel();
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeout);
-
-  try {
-    const { system, user } = splitPrompt(prompt);
-    const body = {
-      model: modelId,
-      max_tokens: maxTokens,
-      temperature,
-      messages: [{ role: 'user', content: user }],
-    };
-    // See callModelAPI: cache_control on the constant system slot.
-    if (system) {
-      body.system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
-    }
-
-    // Proxy-aware, same as the OpenRouter site below. Missing it here meant the
-    // ANTHROPIC_API_KEY paths were the one keyed provider still doing a bare
-    // fetch — a silent outage behind a proxy, and one the new doctor check would
-    // have certified as healthy because it probes the hop this code was ASSUMED
-    // to use. (pre-tag review SHOULD-FIX 3)
-    const apiUrl = 'https://api.anthropic.com/v1/messages';
-    const apiHeaders = {
-      'Content-Type': 'application/json',
-      'x-api-key': apiKey,
-      'anthropic-version': '2023-06-01',
-    };
-    const apiProxy = httpConnectProxyFor(apiUrl);
-    const res = apiProxy
-      ? await postViaConnectProxy(apiProxy, apiUrl, { headers: apiHeaders, body: JSON.stringify(body), timeout })
-      : await fetch(apiUrl, {
-        method: 'POST',
-        headers: apiHeaders,
-        body: JSON.stringify(body),
-        signal: controller.signal,
-      });
-
-    if (!res.ok) {
-      debugLog('WARN', 'haiku-api', `HTTP ${res.status}`);
-      return null;
-    }
-
-    const data = await res.json();
-    const text = data.content?.[0]?.text;
-    return text ? { text } : null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 // ─── OpenRouter Mode ─────────────────────────────────────────────────────────
 
 // OpenRouter exposes an OpenAI-compatible chat-completions API (NOT the

package/hook-context.mjs

@@ -16,6 +16,9 @@ import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS, RUNTIME_DIR, effectiveQuiet,
 import { extractUnfinishedSummary } from './hook-handoff.mjs';
 import { recentInjectableEvents, renderInjectableEvent } from './lib/events-injection.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
+// Single source for the type-quality weights (audit 2026-08-22 P2-10) — this table used
+// to be hand-copied here and in hook-memory.mjs, kept equal only by comment convention.
+import { TYPE_QUALITY, TYPE_QUALITY_DEFAULT } from './scoring-sql.mjs';
 
 import { DAY_MS } from './lib/time-constants.mjs';
 /**
@@ -108,18 +111,12 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
   const selectedSess = [];
   let totalTokens = 0;
 
-  // Type quality multipliers — aligned with scoring-sql.mjs TYPE_QUALITY_CASE (R2).
-  // Weights calibrated from empirical avg access_count per type:
-  //   decision 6.05, discovery 3.32, bugfix 2.24, feature 2.04, change 0.93, refactor 0.54.
-  // Pre-R2 had bugfix=0.35 (inverted vs reality — bugfixes are 2.4× more used than changes).
-  const TYPE_QUALITY = { decision: 1.5, discovery: 1.3, bugfix: 1.1, feature: 1.0, refactor: 0.6, change: 0.5 };
-
   // Score each candidate: value = recency * type_quality * importance, cost = tokens
   // Recency uses exponential half-life (consistent with server.mjs BM25 scoring)
   const scoredObs = obsPool.map(o => {
     const halfLifeMs = DECAY_HALF_LIFE_BY_TYPE[o.type] || DEFAULT_DECAY_HALF_LIFE_MS;
     const recency = 1.0 + Math.exp(-0.693 * (now_ms - o.created_at_epoch) / halfLifeMs);
-    const typeQuality = TYPE_QUALITY[o.type] || 1.0;
+    const typeQuality = TYPE_QUALITY[o.type] || TYPE_QUALITY_DEFAULT;
     const impBoost = 0.5 + 0.5 * (o.importance || 1);
     const lessonBoost = o.lesson_learned ? 1.3 : 1.0;
     const value = recency * typeQuality * impBoost * lessonBoost;

package/hook-episode.mjs

@@ -246,37 +246,61 @@ export function mergePendingEntries(episode) {
   }
 }
 
+/** Rule 4's threshold — 8+ Read/Grep entries read as investigation. */
+const RESEARCH_ENTRY_THRESHOLD = 8;
+
 /**
- * Check if an episode has significant content worth processing with LLM.
- * Significant = contains file edits, Bash errors, or a review/research pattern
- * (8+ Read/Grep entries indicate investigation worth recording).
- * @param {object} episode The episode to check
- * @returns {boolean} true if the episode has significant content
+ * The significance decision WITH its reasoning, for instrumentation.
+ * `episodeHasSignificantContent` is the boolean face of this same body, so the meter
+ * and the decision cannot drift (audit 2026-08-22 P2-14).
+ *
+ * `grepDecisive` answers the one question the "move Grep into the bash skip list"
+ * decision is blocked on: would this episode still have been kept without its Grep
+ * entries? It is true ONLY when rule 4 decided AND the non-Grep entries alone fall
+ * short — an edit-driven episode that happens to contain Greps is not evidence that
+ * Grep carries research episodes.
+ *
+ * @param {object} episode
+ * @returns {{significant: boolean, rule: 1|2|3|4|null, readCount: number,
+ *   grepCount: number, grepDecisive: boolean}}
  */
-export function episodeHasSignificantContent(episode) {
+export function explainSignificance(episode) {
+  const entries = episode?.entries || [];
+  const grepCount = entries.filter(e => e.tool === 'Grep').length;
+  const readCount = entries.filter(e => e.tool === 'Read' || e.tool === 'Grep').length;
+  const base = { readCount, grepCount, grepDecisive: false };
+
   // 1. File edits → always significant (code changes matter)
-  const hasEdits = episode.entries.some(e => EDIT_TOOLS.has(e.tool));
-  if (hasEdits) return true;
+  if (entries.some(e => EDIT_TOOLS.has(e.tool))) return { ...base, significant: true, rule: 1 };
 
   // 2. Test/build errors → significant (actionable failures)
   // Plain bash errors without edits are noise (e.g. typos, exploration errors)
-  const hasTestOrBuildError = episode.entries.some(e =>
-    e.tool === 'Bash' && e.isError && (e.bashSig?.isTest || e.bashSig?.isBuild)
-  );
-  if (hasTestOrBuildError) return true;
+  if (entries.some(e => e.tool === 'Bash' && e.isError && (e.bashSig?.isTest || e.bashSig?.isBuild))) {
+    return { ...base, significant: true, rule: 2 };
+  }
 
   // 3. Important files touched (config, schema, security, migration)
   // Checks episode.files (all touched files, including reads) — catches important-file investigation
-  const allFiles = episode.files || [];
-  const hasImportantFile = allFiles.some(f =>
+  const allFiles = episode?.files || [];
+  if (allFiles.some(f =>
     /\.(env|yml|yaml|toml|lock|sql|prisma|proto)$/.test(f) ||
     /(config|schema|migration|auth|security)/i.test(f)
-  );
-  if (hasImportantFile) return true;
+  )) return { ...base, significant: true, rule: 3 };
 
   // 4. Research pattern: reading many files indicates investigation
-  const readCount = episode.entries.filter(e =>
-    e.tool === 'Read' || e.tool === 'Grep'
-  ).length;
-  return readCount >= 8;
+  if (readCount >= RESEARCH_ENTRY_THRESHOLD) {
+    return { ...base, significant: true, rule: 4, grepDecisive: readCount - grepCount < RESEARCH_ENTRY_THRESHOLD };
+  }
+  return { ...base, significant: false, rule: null };
+}
+
+/**
+ * Check if an episode has significant content worth processing with LLM.
+ * Significant = contains file edits, Bash errors, or a review/research pattern
+ * (8+ Read/Grep entries indicate investigation worth recording).
+ * @param {object} episode The episode to check
+ * @returns {boolean} true if the episode has significant content
+ */
+export function episodeHasSignificantContent(episode) {
+  return explainSignificance(episode).significant;
 }

package/hook-llm.mjs

@@ -511,14 +511,19 @@ export function buildDegradedTitle(episode) {
 // processed), so without this the in-flight episode is silently lost on abnormal
 // termination — and spawning a detached child from a dying process is unreliable, so
 // the save must be synchronous (audit #6). Never throws; returns the obs id or null.
-export function saveEpisodeImmediate(episode, externalDb) {
+// `scope` names the CALLER in hook-error telemetry. Audit 2026-08-22 P2-9 folded
+// flushEpisodeGroup's hand-copied version of this block into this function; without the
+// parameter all three paths would report failures under one label, and "the immediate
+// save threw" means different things on the normal flush, the lock-contended Stop
+// fallback, and the shutdown salvage.
+export function saveEpisodeImmediate(episode, externalDb, scope = 'saveEpisodeImmediate') {
   try {
     if (!episode || !Array.isArray(episode.entries) || episode.entries.length === 0) return null;
     if (!episodeHasSignificantContent(episode)) return null;
     const obs = buildImmediateObservation(episode);
     return saveObservation(obs, episode.project, episode.sessionId, externalDb) || null;
   } catch (e) {
-    debugCatch(e, 'saveEpisodeImmediate');
+    debugCatch(e, scope);
     return null;
   }
 }

package/hook-memory.mjs

@@ -1,8 +1,9 @@
 // claude-mem-lite — Semantic Memory Injection
 // Search past observations for relevant memories to inject as context at user-prompt time.
 
-import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters, basenameAnySep } from './utils.mjs';
-import { citeFactorJs } from './scoring-sql.mjs';
+import { relaxFtsQueryToOr, debugCatch, truncate, OBS_BM25, notLowSignalTitleClause, noisePenaltyClause, tokenizeHandoff, HANDOFF_STOP_WORDS, extractCjkKeywords, neutralizeContextDelimiters, basenameAnySep } from './utils.mjs';
+import { upsFtsQuery } from './lib/ups-query.mjs';
+import { citeFactorJs, TYPE_QUALITY, TYPE_QUALITY_DEFAULT } from './scoring-sql.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { recordMetric } from './lib/metrics.mjs';
 import { DB_DIR } from './schema.mjs';
@@ -12,11 +13,9 @@ 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
-// Aligned with TYPE_QUALITY_CASE in scoring-sql.mjs (R2 rebalance).
-// Weights calibrated to empirical avg access_count:
-//   decision 6.05, discovery 3.32, bugfix 2.24, feature 2.04, change 0.93, refactor 0.54.
+// 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.
-const MEMORY_TYPE_BOOST = { decision: 1.5, discovery: 1.3, bugfix: 1.1, feature: 1.0, refactor: 0.6, change: 0.5 };
 // Adaptive BM25 thresholds — scale with corpus size to filter noise.
 // Larger corpora produce more weak matches from common words.
 const BM25_THRESHOLD = { TINY: 0, SMALL: 1.5, MEDIUM: 2.5, LARGE: 3.5 };
@@ -194,7 +193,12 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
   };
 
   try {
-    const ftsQuery = sanitizeFtsQuery(userPrompt);
+    // upsFtsQuery, not bare sanitizeFtsQuery: this is the SECOND hook UserPromptSubmit
+    // fires, and v3.75.0 capped only the first. This one is the worse half — its stdin
+    // ceiling is MAX_HOOK_STDIN_BYTES (256KB) against path A's 64KB, and nothing
+    // truncates between stdin and here. The caps are shared, not copied, so the two
+    // faces of one event cannot drift apart again.
+    const ftsQuery = upsFtsQuery(userPrompt);
     if (!ftsQuery) return [];
 
     const cutoff = Date.now() - MEMORY_LOOKBACK_MS;
@@ -245,7 +249,15 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     if (rows.length === 0) {
       const orQuery = relaxFtsQueryToOr(ftsQuery);
       if (orQuery && (queryIsCjkDominant || queryTokenCount <= orFallbackMaxTokens)) {
-        try { rows = selectStmt.all(orQuery, project, cutoff); usedOrFallback = true; } catch {}
+        // debugCatch, not a bare swallow: this is the injection chain's LAST query, and
+        // an FTS5 fault here (corrupt index, malformed relaxed query) degrades to an
+        // EMPTY injection that reads exactly like "nothing matched" — invisible to
+        // stats and doctor alike. Still non-fatal; the prompt must go through.
+        // (The two bare catches further down, around the per-row access bumps, are
+        // deliberately left bare: they are write-path and per-row, so logging them would
+        // flood the debug stream on the same corruption this one reports once.)
+        try { rows = selectStmt.all(orQuery, project, cutoff); usedOrFallback = true; }
+        catch (e) { debugCatch(e, 'injectMemory:orFallback'); }
       }
     }
 
@@ -276,7 +288,10 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       if (crossRows.length === 0) {
         const orQuery = relaxFtsQueryToOr(ftsQuery);
         if (orQuery && (queryIsCjkDominant || queryTokenCount <= orFallbackMaxTokens)) {
-          try { crossRows = crossStmt.all(orQuery, project, cutoff); crossUsedOr = true; } catch {}
+          // Same reasoning as the same-project OR fallback above: a fault here silently
+          // drops the cross-project half of the injection.
+          try { crossRows = crossStmt.all(orQuery, project, cutoff); crossUsedOr = true; }
+          catch (e) { debugCatch(e, 'injectMemory:crossOrFallback'); }
         }
       }
     } catch (e) { debugCatch(e, 'crossProjectSearch'); }
@@ -302,7 +317,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
         return {
           ...r,
           score: Math.abs(r.relevance)
-            * (MEMORY_TYPE_BOOST[r.type] || 1.0)
+            * (TYPE_QUALITY[r.type] || TYPE_QUALITY_DEFAULT)
             * (r.lesson_learned ? 1.5 : 1.0)
             * (r.importance >= 2 ? 1.0 : 0.6)
             * crossProjectPenalty