claude-mem-lite 3.74.0 → 3.75.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.74.0",
+      "version": "3.75.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.74.0",
+  "version": "3.75.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

@@ -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/bash-utils.mjs

@@ -137,7 +137,21 @@ function collectErrorTerms(cmd, response) {
     if (!ERROR_STOP_WORDS.has(lw) && !seen.has(lw)) { seen.add(lw); cmdWords.push(lw); }
   }
   const errWords = [];
-  const errLines = String(response || '').split('\n').filter(l => ERROR_LINE_RE.test(l)).slice(0, 3);
+  // 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
+  // found nothing, so we queried the command's own words" class without enumerating
+  // failure shapes. ERROR_LINE_RE alone missed `npm ERR! code ENOENT` (no `error`, no
+  // `fail`, no `not found` — npm says "no such file") and `panic: assignment to entry
+  // in nil map`, while letting `panic: runtime error: …` through purely because that
+  // message happens to contain the substring `error`.
+  // Note HARD_ERROR_RE's `\n\s+at\s+\S` alternative cannot match a single line (it
+  // needs the preceding newline); that is fine — it is a stack-frame anchor, and the
+  // frames it guards are accompanied by a line the other alternatives do catch.
+  const errLines = String(response || '')
+    .split('\n')
+    .filter((l) => ERROR_LINE_RE.test(l) || HARD_ERROR_RE.test(l))
+    .slice(0, 3);
   for (const line of errLines) {
     const tokens = line.replace(/[^a-zA-Z0-9_.-]/g, ' ').split(/\s+/)
       .filter(w => w.length > 3 && !/^\d+$/.test(w));
@@ -168,22 +182,25 @@ export function extractErrorKeywords(cmd, response) {
  * Two defects this closes, both measured against the live DB on 2026-08-22 (obs
  * #10730 carries the readings):
  *
- * 1. NO ERROR SIGNAL ⇒ NO INJECTION. This surface fires on detectBashSignificance's
- *    isHardError, and that gate's HARD_ERROR_RE is NOT in sync with ERROR_LINE_RE
- *    here: HARD_ERROR_RE accepts `ERR!`, `enoent` and `traceback`, while ERROR_LINE_RE
- *    only matches the whole word `error`. So npm's own failure output clears the
- *    trigger and then yields ZERO error lines — `npm ERR! code ENOENT / npm ERR!
- *    enoent ENOENT: no such file or directory` contains no `error`, no `fail`, and no
- *    `not found` (it says "no such file"). The keyword set then degraded to pure
- *    command words — literally ['npm','run','build'] — and the surface searched the
- *    COMMAND'S TOPIC instead of the failure. Same for a Python traceback whose head
- *    lines carry `Traceback (most recent call last):` and a bare `File "x.py"`.
- *    Both are among the most common failures a session produces.
- *    With no error term there is nothing to recall ON, so the honest answer is
- *    silence rather than a topic match. Widening ERROR_LINE_RE is NOT the fix —
- *    enumeration always misses one more shape, and this gate is correct for every
- *    shape it misses. (Verified: a `grep` killed by seccomp does NOT reach here at
- *    all — isHardError is false for it — so that shape is not evidence for this gate.)
+ * 1. THE SELECTION FILTER IS A SUPERSET OF THE TRIGGER. This surface fires on
+ *    detectBashSignificance's isHardError (HARD_ERROR_RE), but term extraction used to
+ *    keep only lines matching ERROR_LINE_RE — a DIFFERENT list. The two diverge:
+ *    HARD_ERROR_RE accepts `ERR!`, `enoent`, `panic`, `traceback`; ERROR_LINE_RE takes
+ *    `error|fail|exception|cannot|not found|undefined|null` as SUBSTRINGS (no word
+ *    boundaries — `AssertionError` matches on `error`). npm's own output sits in the
+ *    gap: `npm ERR! code ENOENT / npm ERR! enoent ENOENT: no such file or directory`
+ *    has no `error`, no `fail`, no `not found` (npm says "no such file"), so it cleared
+ *    the trigger and then yielded ZERO lines to extract from. The keyword set degraded
+ *    to pure command words — literally ['npm','run','build'] — and the surface searched
+ *    the COMMAND'S TOPIC instead of the failure.
+ *    The sharpest symptom was Go: `panic: assignment to entry in nil map` was silenced
+ *    while `panic: runtime error: index out of range` was not, purely because the
+ *    second message happens to contain the substring `error`. Recall depending on the
+ *    wording of a panic is the same divergence, relocated.
+ *    OR-ing HARD_ERROR_RE into the line filter closes the class BY CONSTRUCTION rather
+ *    than by enumerating shapes: whatever convinced the trigger this was a hard error
+ *    is, by definition, also something we will read terms from. (Widening ERROR_LINE_RE
+ *    ad hoc WOULD be enumeration; making it a superset of the trigger is not.)
  *
  * 2. COMMAND WORDS STAY IN THE QUERY — a demotion was TRIED AND REJECTED on data.
  *    The obvious follow-up is to drop `npm` / `run` / `grep` from the query, since
@@ -196,7 +213,21 @@ export function extractErrorKeywords(cmd, response) {
  *    fails locally) for a test failure. Command words are carrying domain anchoring,
  *    not just noise. A demote-to-fallback variant measured byte-identical to
  *    error-terms-only (12 rows either way): the primary query always filled its
- *    LIMIT 3, so the fallback never ran. Net: gate only, selection unchanged.
+ *    LIMIT 3, so the fallback never ran.
+ *
+ * 3. THE RESIDUAL GATE. With (1) in place this fires rarely, but it is not dead: a
+ *    failure can still yield no usable term — empty output, or a line whose tokens are
+ *    all stop words (`Error: it failed`). There is then nothing to recall ON, and
+ *    silence beats querying the command's topic.
+ *    Read the predicate precisely: `errWords` excludes anything ALREADY taken as a
+ *    command word, because collectErrorTerms dedups across both classes with the
+ *    command filled first. So this is "no error term that is not also in the command",
+ *    not "no error term". `docker compose up -d` and `docker stack deploy` on the SAME
+ *    output decide differently for exactly that reason — the first has `compose` in the
+ *    command, the second does not. That asymmetry is inherited from the pre-split
+ *    single-Set implementation and is preserved deliberately; it is documented here
+ *    rather than silently "fixed" because changing it would change extractErrorKeywords
+ *    for every caller, which is a separate decision from this one.
  *
  * @param {string} cmd The command that was executed
  * @param {string} response The error output text

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-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

@@ -2,7 +2,7 @@
 // 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 { 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 +12,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 };
@@ -302,7 +300,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