claude-mem-lite 3.72.1 → 3.74.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.72.1",
+      "version": "3.74.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.72.1",
+  "version": "3.74.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/bash-utils.mjs

@@ -117,35 +117,97 @@ const ERROR_STOP_WORDS = new Set([
   'node', 'require', 'stack', 'trace',
 ]);
 
+const ERROR_LINE_RE = /error|fail|exception|cannot|not found|undefined|null/i;
+const ERROR_RECALL_MAX_TERMS = 6;
+
 /**
- * Extract discriminative keywords from a failed command and its error output.
- * Filters out common stop words to produce useful FTS5 search terms.
- * @param {string} cmd The command that was executed
- * @param {string} response The error output text
- * @returns {string[]|null} Array of 1-6 keywords or null if none found
+ * Split a failed command + its output into command-derived and error-derived terms.
+ * Shared by extractErrorKeywords (merged view, unchanged contract) and
+ * planErrorRecall (which needs the two classes kept apart). Dedup is deliberately
+ * ACROSS both classes, command-first, so the merged view is byte-identical to the
+ * pre-split single-Set implementation.
+ * @returns {{cmdWords: string[], errWords: string[]}}
  */
-export function extractErrorKeywords(cmd, response) {
-  const words = new Set();
-  const cmdParts = cmd.split(/[\s/\\|&;]+/).filter(w => w.length > 2 && !/^-/.test(w));
+function collectErrorTerms(cmd, response) {
+  const seen = new Set();
+  const cmdWords = [];
+  const cmdParts = String(cmd || '').split(/[\s/\\|&;]+/).filter(w => w.length > 2 && !/^-/.test(w));
   for (const w of cmdParts.slice(0, 3)) {
     const lw = w.toLowerCase();
-    if (!ERROR_STOP_WORDS.has(lw)) words.add(lw);
+    if (!ERROR_STOP_WORDS.has(lw) && !seen.has(lw)) { seen.add(lw); cmdWords.push(lw); }
   }
-  const errLines = response.split('\n').filter(l =>
-    /error|fail|exception|cannot|not found|undefined|null/i.test(l)
-  ).slice(0, 3);
+  const errWords = [];
+  const errLines = String(response || '').split('\n').filter(l => ERROR_LINE_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));
     for (const t of tokens.slice(0, 5)) {
       const lt = t.toLowerCase();
-      if (!ERROR_STOP_WORDS.has(lt)) words.add(lt);
+      if (!ERROR_STOP_WORDS.has(lt) && !seen.has(lt)) { seen.add(lt); errWords.push(lt); }
     }
   }
-  const result = [...words].slice(0, 6);
+  return { cmdWords, errWords };
+}
+
+/**
+ * Extract discriminative keywords from a failed command and its error output.
+ * Filters out common stop words to produce useful FTS5 search terms.
+ * @param {string} cmd The command that was executed
+ * @param {string} response The error output text
+ * @returns {string[]|null} Array of 1-6 keywords or null if none found
+ */
+export function extractErrorKeywords(cmd, response) {
+  const { cmdWords, errWords } = collectErrorTerms(cmd, response);
+  const result = [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS);
   return result.length >= 1 ? result : null;
 }
 
+/**
+ * Decide whether the error-recall surface should fire, and with which terms (D#136).
+ *
+ * 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.)
+ *
+ * 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
+ *    they demonstrably let BM25 return release records for a missing-module failure.
+ *    Replaying five real failures against the live DB (2026-08-22) says the trade is
+ *    not one-way: error-terms-only did fix `npm run build` (it surfaced #8721
+ *    ERR_MODULE_NOT_FOUND and #8185 SOURCE_FILES, the rows that actually explain it),
+ *    but it REGRESSED two others — dropping `database` lost #8673 (plugin-mode
+ *    data-dir skew) for a failed DB open, and dropping `vitest` lost #8725 (test
+ *    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.
+ *
+ * @param {string} cmd The command that was executed
+ * @param {string} response The error output text
+ * @returns {{terms: string[]}|null} null ⇒ do not inject
+ */
+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) };
+}
+
 // ─── File Paths ──────────────────────────────────────────────────────────────
 
 /**

package/haiku-client.mjs

@@ -6,83 +6,12 @@
 // overridable via OPENROUTER_MODEL
 
 import { execFileSync, spawn } from 'child_process';
-import http from 'node:http';
-import https from 'node:https';
-import tls from 'node:tls';
 import { readFileSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { debugLog, debugCatch, parseJsonFromLLM } from './utils.mjs';
 import { DB_DIR } from './schema.mjs';
-
-// ─── Proxy support (native fetch ignores HTTP(S)_PROXY) ──────────────────────
-//
-// Node's global fetch (undici) does NOT honour HTTP(S)_PROXY env vars, and
-// undici's ProxyAgent isn't importable without adding a dependency. In an env
-// that requires a local proxy to reach external APIs (e.g.
-// HTTPS_PROXY=http://127.0.0.1:PORT), a direct fetch to openrouter.ai
-// hangs/times out. We tunnel HTTPS through the HTTP CONNECT proxy using built-ins
-// only. No proxy var (or a NO_PROXY host) → null → callers keep native fetch,
-// unchanged (zero behaviour change when no proxy is configured).
-function httpConnectProxyFor(targetUrl) {
-  const proxy = process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy;
-  if (!proxy || !/^https?:\/\//.test(proxy)) return null; // socks5 ALL_PROXY not supported here
-  try {
-    const host = new URL(targetUrl).hostname;
-    const noProxy = (process.env.NO_PROXY || process.env.no_proxy || '').split(',').map((s) => s.trim()).filter(Boolean);
-    if (noProxy.some((n) => n === host || (n.startsWith('.') && host.endsWith(n.slice(1))))) return null;
-    return proxy;
-  } catch {
-    return null;
-  }
-}
-
-// fetch-compatible (subset) POST over an HTTP CONNECT tunnel: returns
-// { ok, status, json(), text() }. Rejects on connect/timeout/socket error so the
-// caller's try/catch degrades to the CLI exactly as a failed fetch would.
-function postViaConnectProxy(proxy, url, { headers = {}, body = '', timeout = 20000 }) {
-  return new Promise((resolve, reject) => {
-    const p = new URL(proxy);
-    const t = new URL(url);
-    const port = Number(t.port) || 443;
-    let settled = false;
-    const finish = (fn, arg) => { if (!settled) { settled = true; fn(arg); } };
-    const connReq = http.request({
-      host: p.hostname,
-      port: Number(p.port) || 80,
-      method: 'CONNECT',
-      path: `${t.hostname}:${port}`,
-      headers: { Host: `${t.hostname}:${port}` },
-    });
-    connReq.setTimeout(timeout, () => connReq.destroy(new Error('proxy CONNECT timeout')));
-    connReq.on('error', (e) => finish(reject, e));
-    connReq.on('connect', (res, socket) => {
-      if (res.statusCode !== 200) {
-        socket.destroy();
-        return finish(reject, new Error(`proxy CONNECT ${res.statusCode}`));
-      }
-      const req = https.request(
-        url,
-        { method: 'POST', headers, createConnection: () => tls.connect({ socket, servername: t.hostname }) },
-        (resp) => {
-          let data = '';
-          resp.setEncoding('utf8');
-          resp.on('data', (c) => (data += c));
-          resp.on('end', () => finish(resolve, {
-            ok: resp.statusCode >= 200 && resp.statusCode < 300,
-            status: resp.statusCode,
-            json: () => JSON.parse(data),
-            text: () => data,
-          }));
-        }
-      );
-      req.setTimeout(timeout, () => req.destroy(new Error('proxy request timeout')));
-      req.on('error', (e) => finish(reject, e));
-      req.end(body);
-    });
-    connReq.end();
-  });
-}
+import { httpConnectProxyFor, postViaConnectProxy } from './lib/proxy-fetch.mjs';
 
 // ─── Model Resolution ────────────────────────────────────────────────────────
 
@@ -465,16 +394,26 @@ async function callModelAPI(prompt, model, { timeout, maxTokens, temperature = D
       body.system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
     }
 
-    const res = await fetch('https://api.anthropic.com/v1/messages', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-api-key': apiKey,
-        'anthropic-version': '2023-06-01',
-      },
-      body: JSON.stringify(body),
-      signal: controller.signal,
-    });
+    // 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', `${model}-api`, `HTTP ${res.status}`);
@@ -767,16 +706,26 @@ async function callHaikuAPI(prompt, { timeout, maxTokens, temperature = DEFAULT_
       body.system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
     }
 
-    const res = await fetch('https://api.anthropic.com/v1/messages', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-api-key': apiKey,
-        'anthropic-version': '2023-06-01',
-      },
-      body: JSON.stringify(body),
-      signal: controller.signal,
-    });
+    // 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}`);

package/hook-llm.mjs

@@ -13,7 +13,7 @@ import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector, vecTextForRow } from './tfidf.mjs';
-import { insertObservationRow, insertObservationFiles, insertObservationVector, normalizeScope } from './lib/observation-write.mjs';
+import { insertObservationRow, insertObservationFiles, insertObservationVector, normalizeScope, SCOPE_PROMPT_LEGEND } from './lib/observation-write.mjs';
 import { DEDUP_JACCARD_THRESHOLD, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
@@ -740,7 +740,7 @@ type: pick by strongest signal. decision = explicit tradeoff / "chose X over Y b
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
 importance: Be strict — default to 1. 0=pure browsing with zero learning value. 1=routine file edits, standard changes, normal workflow (MOST episodes). 2=notable ONLY if it reveals something non-obvious: error fix with discovered root cause, architectural decision with explicit tradeoff, config change with unexpected side effects. 3=critical: breaking change affecting users, security vulnerability fix, data migration. Ask yourself: "would a future session benefit from knowing this?" — if not, it's importance=1.
 lesson_learned: The non-obvious insight a future session would benefit from. Examples: "FTS5 porter stemmer doesn't tokenize CJK — need bigram workaround", "vitest --reporter=verbose hangs on large test suites, use default reporter". Look hard before giving up — most coding episodes contain at least one micro-lesson (an undocumented flag, a surprising default, a debugging shortcut, an unexpected interaction). If literally no insight worth teaching (e.g. version bump, whitespace fix, file rename), output JSON null. Do NOT invent a lesson, do NOT write the strings "none"/"n/a"/"todo"/"tbd"/"-" — those will be discarded as noise.
-scope: where does the lesson APPLY (not where it was learned)? file = specific to the touched file(s)' own code. module = a directory/subsystem of this project. project = a project-wide convention, architecture, or workflow. environment = a tooling/OS/CI/network/registry/service quirk (proxy, npm, git, GitHub, shell, runner, editor) that would hold in ANY project — even though some project files were touched when it surfaced. When lesson_learned is null, still classify the episode's dominant subject.
+scope: ${SCOPE_PROMPT_LEGEND}
 search_aliases: 2-6 alternative search terms someone might use to find this memory later (include CJK if project uses Chinese)`;
 
   let prompt;

package/hook-optimize.mjs

@@ -20,6 +20,7 @@ import { getVocabulary, computeVector, cosineSimilarity, vecTextForRow } from '.
 import { MERGE_JACCARD_LOW, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { DB_DIR } from './schema.mjs';
 import { OBS_TYPE_SET } from './lib/obs-types.mjs';
+import { normalizeScope, SCOPE_PROMPT_LEGEND } from './lib/observation-write.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 
 import { DAY_MS } from './lib/time-constants.mjs';
@@ -92,10 +93,38 @@ export function rebuildVector(db, obsId, textPartsOrRow) {
  *
  * @param {object} db better-sqlite3 database handle
  * @param {number} limit max candidates to return
- * @param {{ scope?: 'narrow' | 'wide', project?: string }} [opts] Optional project filter (e.g. inferProject()-resolved name) narrows candidates to a single project — opt-in to preserve prior cross-project default.
+ * @param {{ scope?: 'narrow' | 'wide' | 'aliases' | 'scopes', project?: string }} [opts] Optional project filter (e.g. inferProject()-resolved name) narrows candidates to a single project — opt-in to preserve prior cross-project default.
  */
 export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', project } = {}) {
   const projectClause = project ? 'AND project = ?' : '';
+  if (scope === 'scopes') {
+    // D#135 P3 scope backfill: substantive rows with observations.scope still
+    // NULL, REGARDLESS of lesson or aliases. narrow/wide need lesson IS NULL and
+    // aliases needs search_aliases IS NULL, so a legacy lesson-bearing row with
+    // aliases is reachable by NONE of them — that shape was 1955 of the 2041
+    // scope-less rows on 2026-08-19, i.e. the pool is ~97% invisible to the
+    // existing passes. Idempotent via scope becoming non-null; deliberately NOT
+    // gated on optimized_at (the alias branch's precedent — an optimized row can
+    // still be unclassified) and it never SETS optimized_at, so the wide pass
+    // keeps its own candidates.
+    // Lesson-bearing first: CLAUDE_MEM_SCOPE_FILTER gates pre-tool recall, which
+    // injects lesson-bearing rows — classifying those first is what makes the
+    // lever usable before the backlog is fully drained.
+    const stmt = db.prepare(`
+      SELECT id, title, narrative, type, lesson_learned, importance, project
+      FROM observations
+      WHERE ${liveObsFilterSql('')}
+        AND scope IS NULL
+        AND LENGTH(COALESCE(narrative, '')) > 100
+        AND ${notLowSignalTitleClause('')}
+        ${projectClause}
+      ORDER BY
+        CASE WHEN lesson_learned IS NOT NULL AND lesson_learned != '' THEN 0 ELSE 1 END,
+        created_at_epoch DESC
+      LIMIT ?
+    `);
+    return project ? stmt.all(project, limit) : stmt.all(limit);
+  }
   if (scope === 'aliases') {
     // P1 alias backfill: substantive rows missing search_aliases, REGARDLESS of
     // lesson. Targets lesson-bearing manual saves (mem_save writes no aliases →
@@ -150,6 +179,29 @@ export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', proje
   return project ? stmt.all(project, limit) : stmt.all(limit);
 }
 
+/**
+ * Row count for a re-enrich pool, without materialising it. Only the 'scopes'
+ * pool is served: it is the one large enough for the difference to matter
+ * (2041 rows at introduction, against ~22 alias candidates), and keeping the
+ * predicate here rather than duplicating it would drift — so this shares the
+ * finder's WHERE by construction, via a SELECT COUNT over the same clauses.
+ * @returns {number}
+ */
+export function countReenrichCandidates(db, scope = 'scopes', project) {
+  if (scope !== 'scopes') return findReenrichCandidates(db, 5000, { scope, project }).length;
+  const projectClause = project ? 'AND project = ?' : '';
+  const stmt = db.prepare(`
+    SELECT COUNT(*) c
+    FROM observations
+    WHERE ${liveObsFilterSql('')}
+      AND scope IS NULL
+      AND LENGTH(COALESCE(narrative, '')) > 100
+      AND ${notLowSignalTitleClause('')}
+      ${projectClause}
+  `);
+  return (project ? stmt.get(project) : stmt.get()).c;
+}
+
 export async function executeReenrich(db, limit = 10, { scope = 'narrow', project } = {}) {
   const candidates = findReenrichCandidates(db, limit, { scope, project });
   if (candidates.length === 0) return { processed: 0, skipped: 0 };
@@ -162,6 +214,34 @@ export async function executeReenrich(db, limit = 10, { scope = 'narrow', projec
     if (!gotSlot) { skipped++; continue; }
 
     try {
+      if (scope === 'scopes') {
+        // Classification-only pass (D#135 P3). One cheap Haiku call per row, and
+        // the UPDATE touches exactly ONE column — this pool is full of curated
+        // lesson-bearing rows, so borrowing the general re-enrich (which rewrites
+        // title/narrative/lesson and stamps optimized_at) would risk permanent
+        // content loss to buy a single enum value.
+        const scopePrompt = `Classify where this coding memory APPLIES. Return ONLY valid JSON, no markdown fences.
+
+Title: ${truncate(cand.title || '(untitled)', 200)}
+Narrative: ${truncate(cand.narrative || '(no narrative)', 500)}
+Lesson: ${truncate(cand.lesson_learned || '(none)', 300)}
+
+JSON: {"scope":"file|module|project|environment"}
+scope: ${SCOPE_PROMPT_LEGEND}`;
+        const parsed = await callModelJSONAsync(scopePrompt, 'haiku', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 60 });
+        const scopeValue = normalizeScope(parsed && parsed.scope);
+        if (!scopeValue) { skipped++; continue; }
+        // `AND scope IS NULL` is the fill-only-empty guard: a save-enrich worker or
+        // an episode upgrade can land between candidate selection and this write,
+        // and a classifier round-trip is long enough for that to be real.
+        const res = db.prepare('UPDATE observations SET scope = ? WHERE id = ? AND scope IS NULL')
+          .run(scopeValue, cand.id);
+        if (res.changes === 0) { skipped++; continue; }
+        // No rebuildVector: scope is a filter column, absent from the FTS text
+        // field and from vecTextForRow — a rebuild here would be a no-op write.
+        processed++;
+        continue;
+      }
       if (scope === 'aliases') {
         // Alias-only backfill: generate search_aliases and APPEND them (plus any
         // CJK bigrams) to the EXISTING FTS text. Never rebuild text from
@@ -173,8 +253,9 @@ export async function executeReenrich(db, limit = 10, { scope = 'narrow', projec
 Title: ${truncate(cand.title || '(untitled)', 200)}
 Narrative: ${truncate(cand.narrative || '(no narrative)', 500)}
 
-JSON: {"search_aliases":["alt phrasing","synonym","spelled-out jargon","CJK term if the domain word has one"]}
-Give 3-6 aliases: words a user might search for the SAME concept but that are NOT already in the title (synonyms, the spelled-out form of an acronym, the jargon term for a described symptom, a CJK translation of a key domain term).`;
+JSON: {"search_aliases":["alt phrasing","synonym","spelled-out jargon","CJK term if the domain word has one"],"scope":"file|module|project|environment"}
+Give 3-6 aliases: words a user might search for the SAME concept but that are NOT already in the title (synonyms, the spelled-out form of an acronym, the jargon term for a described symptom, a CJK translation of a key domain term).
+scope: ${SCOPE_PROMPT_LEGEND}`;
         const parsed = await callModelJSONAsync(aliasPrompt, 'haiku', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 300 });
         const aliasArr = parsed && Array.isArray(parsed.search_aliases)
           ? parsed.search_aliases.filter((a) => typeof a === 'string' && a.trim().length > 0)
@@ -184,8 +265,11 @@ Give 3-6 aliases: words a user might search for the SAME concept but that are NO
         const aliasBigrams = cjkBigrams(searchAliases);
         const appendedText = [cand.text || '', searchAliases, aliasBigrams].filter(Boolean).join(' ');
         const safe = scrubRecord('observations', { text: appendedText, search_aliases: searchAliases });
-        db.prepare(`UPDATE observations SET search_aliases = ?, text = ? WHERE id = ?`)
-          .run(safe.search_aliases, safe.text, cand.id);
+        // scope rides this call for free (D#135 P3). COALESCE, not a plain set:
+        // an omitted or off-enum value normalizes to null and must not erase a
+        // classification an earlier face already wrote.
+        db.prepare(`UPDATE observations SET search_aliases = ?, text = ?, scope = COALESCE(?, scope) WHERE id = ?`)
+          .run(safe.search_aliases, safe.text, normalizeScope(parsed.scope), cand.id);
         // Refresh the TF-IDF vector from the just-updated FTS text so the new
         // aliases reach the vector arm too — the narrow/wide branch rebuilds, this
         // one must as well. No-ops when the vector arm is off / vocab unbuilt.
@@ -199,10 +283,11 @@ Title: ${truncate(cand.title || '(untitled)', 200)}
 Narrative: ${truncate(cand.narrative || '(no narrative)', 500)}
 Type: ${cand.type || 'change'}
 
-JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"improved ≤120 char title","narrative":"improved 2-3 sentence narrative","concepts":["kw1","kw2"],"facts":["specific fact 1","specific fact 2"],"importance":1,"lesson_learned":"non-obvious insight or 'none' if routine","search_aliases":["alt query 1","alt query 2"]}
+JSON: {"type":"decision|bugfix|feature|refactor|discovery|change","title":"improved ≤120 char title","narrative":"improved 2-3 sentence narrative","concepts":["kw1","kw2"],"facts":["specific fact 1","specific fact 2"],"importance":1,"lesson_learned":"non-obvious insight or 'none' if routine","search_aliases":["alt query 1","alt query 2"],"scope":"file|module|project|environment"}
 importance: 0=no value, 1=routine, 2=notable non-obvious insight, 3=critical. Default 1.
 lesson_learned: State what was learned. If routine, write "none".
-search_aliases: 2-6 alternative search terms (include CJK if applicable).`;
+search_aliases: 2-6 alternative search terms (include CJK if applicable).
+scope: ${SCOPE_PROMPT_LEGEND}`;
 
       const parsed = await callModelJSONAsync(prompt, 'haiku', { timeout: BG_LLM_TIMEOUT_MS, maxTokens: 500 });
       if (!parsed || !parsed.title) { skipped++; continue; }
@@ -266,10 +351,15 @@ search_aliases: 2-6 alternative search terms (include CJK if applicable).`;
       });
       db.prepare(`
         UPDATE observations SET type=?, title=?, narrative=?, concepts=?, facts=?,
-          text=?, importance=?, lesson_learned=?, search_aliases=?, minhash_sig=?, optimized_at=?
+          text=?, importance=?, lesson_learned=?, search_aliases=?, minhash_sig=?, optimized_at=?,
+          scope=COALESCE(?, scope)
         WHERE id = ?
       `).run(type, safe.title, safe.narrative, safe.concepts, safe.facts, safe.text,
-        importance, safe.lesson_learned, safe.search_aliases, minhashSig, Date.now(), cand.id);
+        importance, safe.lesson_learned, safe.search_aliases, minhashSig, Date.now(),
+        // COALESCE (mirrors the hook-llm upgrade path): a re-enrich that omits
+        // scope, or emits an off-enum value, must never blank an existing label —
+        // and THIS update stamps optimized_at, so the loss would be permanent.
+        normalizeScope(parsed.scope), cand.id);
 
       rebuildVector(db, cand.id, { title, narrative, concepts: conceptsText, lesson_learned: safe.lesson_learned, search_aliases: safe.search_aliases });
 
@@ -869,6 +959,14 @@ export function optimizePreview(db, { project, detail = false } = {}) {
   // P1: alias-backfill eligibility — substantive rows missing search_aliases
   // (incl. lesson-bearing manual saves) that narrow+wide both skip.
   const reenrichAliases = findReenrichCandidates(db, 5000, { scope: 'aliases', project }).length;
+  // D#135 P3: the scope-backfill backlog. Reported so the one-shot drain
+  // (`optimize --run --task re-enrich --scope scopes --max N`) can be sized —
+  // the daily pass alone would take months on a multi-thousand-row pool.
+  // COUNT, not `findReenrichCandidates(5000).length`: this pool started at 2041
+  // rows against the aliases pool's ~22, and the finder selects narrative +
+  // lesson_learned per row, so counting by materialising was the one place this
+  // round pulled megabytes to print an integer. (pre-tag review NOTE 11)
+  const reenrichScopes = countReenrichCandidates(db, 'scopes', project);
 
   const concepts = extractUniqueConcepts(db, 500, { project });
   const normalizeReady = shouldRunNormalize(project) && concepts.length >= 5;
@@ -884,6 +982,7 @@ export function optimizePreview(db, { project, detail = false } = {}) {
     reenrich,
     reenrichWide,
     reenrichAliases,
+    reenrichScopes,
     normalize: normalizeReady ? concepts.length : 0,
     normalizeGateOpen: shouldRunNormalize(project),
     clusterMerge,
@@ -911,6 +1010,9 @@ export function optimizePreview(db, { project, detail = false } = {}) {
  *   slice from distributeBudget() — otherwise explicit `--max N --task re-enrich`
  *   would silently waste 60% of the requested budget.
  * @param {number} [opts.maxItems=15] Total item budget across all selected tasks.
+ *   Exception: the 'scopes' side-pass the default re-enrich run performs (D#135 P3)
+ *   is budgeted separately, up to the re-enrich slice again — see the rationale at
+ *   the call site. Its calls are enum-classification only (maxTokens 60).
  * @param {boolean} [opts.force=false] Bypass time-based gates (e.g. normalize interval).
  * @param {'narrow'|'wide'|'aliases'} [opts.reenrichScope='narrow'] Scope for the re-enrich task.
  *   'wide' targets bugfix/refactor/feature/decision with narrative but no lesson (R-7).
@@ -949,16 +1051,37 @@ export async function optimizeRun(db, { tasks, maxItems = 15, force = false, ree
             // (reachable only via manual `optimize --max ≤4`; the daily path runs reenrich=6),
             // and the starved scope self-corrects next cycle.
             // An explicit --scope aliases still runs exactly that one scope (below).
+            //
+            // D#135 P3 adds a THIRD claimant, 'scopes' (observations.scope backfill),
+            // for the same cadence reason — but it is budgeted SEPARATELY, not carved
+            // out of budget.reenrich like aliases. Two measured reasons:
+            //   • Its candidate pool is a near-superset of the others' (any live
+            //     substantive row with scope NULL: 2041 rows on 2026-08-19 vs 36 wide
+            //     and 22 alias candidates), so an adaptive half-share would not be
+            //     occasional — it would permanently halve the lesson-enrichment
+            //     cadence that the main scope exists to provide.
+            //   • It is a fundamentally cheaper call: one enum token (maxTokens 60)
+            //     against a full re-enrich's 500, so charging it one full item slot
+            //     mis-prices it by an order of magnitude.
+            // Cap is budget.reenrich, so the daily pass adds at most that many cheap
+            // classification calls and an empty pool still costs nothing.
             const half = Math.max(1, Math.floor(budget.reenrich / 2));
             const aliasBudget = Math.min(half, findReenrichCandidates(db, half, { scope: 'aliases', project }).length);
+            const scopesBudget = Math.min(
+              budget.reenrich,
+              findReenrichCandidates(db, budget.reenrich, { scope: 'scopes', project }).length,
+            );
             const mainRes = await executeReenrich(db, budget.reenrich - aliasBudget, { scope: reenrichScope, project });
             const aliasRes = aliasBudget > 0
               ? await executeReenrich(db, aliasBudget, { scope: 'aliases', project })
               : { processed: 0, skipped: 0 };
+            const scopesRes = scopesBudget > 0
+              ? await executeReenrich(db, scopesBudget, { scope: 'scopes', project })
+              : { processed: 0, skipped: 0 };
             results.reenrich = {
-              processed: (mainRes.processed || 0) + (aliasRes.processed || 0),
-              skipped: (mainRes.skipped || 0) + (aliasRes.skipped || 0),
-              byScope: { [reenrichScope]: mainRes, aliases: aliasRes },
+              processed: (mainRes.processed || 0) + (aliasRes.processed || 0) + (scopesRes.processed || 0),
+              skipped: (mainRes.skipped || 0) + (aliasRes.skipped || 0) + (scopesRes.skipped || 0),
+              byScope: { [reenrichScope]: mainRes, aliases: aliasRes, scopes: scopesRes },
             };
           } else {
             results.reenrich = await executeReenrich(db, budget.reenrich, { scope: reenrichScope, project });

package/hook-update.mjs

@@ -13,6 +13,11 @@ import { debugCatch, debugLog } from './utils.mjs';
 // extracted tarball's own source-files.mjs inside installExtractedRelease.
 // See loadReleaseManifest below.
 import { SOURCE_FILES as LOCAL_SOURCE_FILES, HOOK_SCRIPT_FILES as LOCAL_HOOK_SCRIPT_FILES } from './source-files.mjs';
+// Native fetch ignores HTTP(S)_PROXY. Without this the whole update path — the
+// version check AND the release download — dies instantly behind a proxy, and
+// because checkForUpdate is silent on network failure the plugin then reports
+// itself permanently up to date. Same tunnel the OpenRouter call site uses.
+import { httpConnectProxyFor, getViaConnectProxy } from './lib/proxy-fetch.mjs';
 import { acquireLock } from './lib/proc-lock.mjs';
 import { atomicWriteFileSync } from './lib/atomic-write.mjs';
 import { verifyReleaseFiles, verifyManifestSignature } from './lib/release-digest.mjs';
@@ -234,7 +239,17 @@ async function fetchWithTimeout(url, headers) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   try {
-    const res = await fetch(url, { signal: controller.signal, headers });
+    // Proxy configured → CONNECT tunnel; otherwise native fetch, byte-for-byte
+    // the previous behaviour. Both shapes expose { status, ok, json() }, and the
+    // tunnel REJECTS on transport failure exactly as a failed fetch does, so the
+    // catch below still returns null and the caller still stays silent.
+    // The AbortController above governs only the fetch branch; the tunnel takes
+    // the same budget as an explicit argument and bounds the whole call with it
+    // (redirect chain included). (pre-tag review NOTE 7)
+    const proxy = httpConnectProxyFor(url);
+    const res = proxy
+      ? await getViaConnectProxy(proxy, url, { headers, timeout: FETCH_TIMEOUT_MS })
+      : await fetch(url, { signal: controller.signal, headers });
     if (res.status === 403 || res.status === 429) {
       // 429 = GitHub secondary rate limit (403 = primary). Both must route to the 6h
       // rate-limit backoff, not the 24h transient-failure path — else a 429 defers the
@@ -452,16 +467,24 @@ export function verifyDownloadedRelease(extractedDir, manifestBytes, signatureB6
 
 // Fetch a GitHub Release asset as a Buffer. Host-locked to github.com (the asset
 // browser_download_url); GitHub's own 302 to its CDN is followed by fetch.
-async function fetchAssetBuffer(url) {
+export async function fetchAssetBuffer(url) {
+  // Host lock is checked BEFORE transport selection, so having a proxy
+  // configured can never route around this supply-chain guard.
   if (!/^https:\/\/github\.com\/[\w./%~-]+$/.test(url || '')) {
     throw new Error(`rejected asset url: ${url}`);
   }
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   try {
-    const res = await fetch(url, { signal: controller.signal, redirect: 'follow' });
+    // getViaConnectProxy follows redirects itself — native fetch does that for
+    // free, and this URL always 302s from github.com to the asset CDN, so a
+    // tunnel without redirect handling would hand back an empty 302 body.
+    const proxy = httpConnectProxyFor(url);
+    const res = proxy
+      ? await getViaConnectProxy(proxy, url, { timeout: FETCH_TIMEOUT_MS })
+      : await fetch(url, { signal: controller.signal, redirect: 'follow' });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return Buffer.from(await res.arrayBuffer());
+    return proxy ? res.buffer() : Buffer.from(await res.arrayBuffer());
   } finally {
     clearTimeout(timeout);
   }

package/hook.mjs

@@ -24,7 +24,7 @@ import { readFileSync, writeFileSync, unlinkSync, readdirSync, renameSync, statS
 import { homedir } from 'os';
 import {
   truncate, inferProject, detectBashSignificance,
-  extractErrorKeywords, extractFilePaths, isRelatedToEpisode,
+  planErrorRecall, extractFilePaths, isRelatedToEpisode,
   makeEntryDesc, scrubSecrets, stripPrivate, EDIT_TOOLS, debugCatch, debugLog,
   COMPRESSED_AUTO, OBS_BM25, notLowSignalTitleClause, formatErrorRecallHints,
   MAX_HOOK_STDIN_BYTES,
@@ -473,13 +473,20 @@ function triggerErrorRecall(db, toolInput, response) {
   try {
     const project = inferProject();
 
-    // Extract error keywords
+    // Extract error keywords. planErrorRecall (D#136) returns null when the output
+    // carried NO error-signal token. isHardError above and that check do NOT use the
+    // same pattern list: HARD_ERROR_RE accepts `ERR!`/`enoent`/`traceback`, while the
+    // line filter wants the whole word `error`. npm's own failure text clears the
+    // former and yields zero lines to the latter, so `npm run build` failing on
+    // ENOENT used to query ['npm','run','build'] — the command's topic, not the
+    // failure. Silence is the honest answer there.
+    // The term list itself is unchanged when the gate passes (rationale at the seam).
     const cmd = toolInput.command || '';
-    const keywords = extractErrorKeywords(cmd, response);
-    if (!keywords || keywords.length === 0) return;
+    const plan = planErrorRecall(cmd, response);
+    if (!plan) return;
 
     // FTS5 OR query for broader recall
-    const ftsQuery = keywords.map(t => `"${t.replace(/"/g, '""')}"`).join(' OR ');
+    const ftsQuery = plan.terms.map(t => `"${t.replace(/"/g, '""')}"`).join(' OR ');
     if (!ftsQuery) return;
 
     const nowR = Date.now();

package/install.mjs

@@ -1737,8 +1737,17 @@ async function doctor() {
     try { currentVersion = JSON.parse(readFileSync(join(PROJECT_DIR, 'package.json'), 'utf8')).version; } catch { /* fall through with empty version */ }
     const stale = lines.filter(l => isStaleMemProcess(l, currentVersion));
     if (stale.length > 0) {
+      // ⚠-level ONLY, deliberately not `issues++`. buildDoctorSummary's contract is
+      // "issues are ✗-level (action required); warnings are ⚠-level (informational)",
+      // and an old process is the one finding here the user cannot act on from a
+      // doctor run: auto-update bumps installed_plugins.json but cannot kill the MCP
+      // process an active session already spawned, so a correct, healthy install
+      // reports this for as long as that session lives. Counting it made `doctor`
+      // exit 1 while every line on screen was ✓ or ⚠ — it failed the v3.70.0 release
+      // `validate` job (where the "old processes" were vitest's own workers) and it
+      // reddens doctor-install-shape-e2e's "instead of going red forever" case on any
+      // dev box with a previous-version session still open.
       warn(`Old processes running${currentVersion ? ` (current: v${currentVersion})` : ''}:\n    ` + stale.join('\n    '));
-      issues++;
     } else {
       ok('No stale processes');
     }
@@ -1770,6 +1779,20 @@ async function doctor() {
     dwarn('Update state: failed to read');
   }
 
+  // LLM provider reachability. Doctor had no provider check at all, which is how
+  // a configured OPENROUTER_API_KEY could sit unusable for weeks behind an
+  // all-green report while every background call silently paid the CLI fallback.
+  // Transport only, and only when a key is set — no key means no probe and no
+  // network touched.
+  try {
+    const { llmProviderStatus } = await import('./lib/llm-provider-probe.mjs');
+    const st = await llmProviderStatus();
+    if (st.level === 'ok') ok(st.message);
+    else dwarn(st.message);
+  } catch {
+    dwarn('LLM provider: check failed');
+  }
+
   // Dev drift: in dev-mode installs, all SOURCE_FILES entries should be
   // symlinks. A plain file means an earlier install (or manual cp) copied it
   // (edits in the repo won't propagate). A missing entry (neither symlink nor

package/lib/llm-provider-probe.mjs

@@ -0,0 +1,103 @@
+// lib/llm-provider-probe.mjs — "is the configured LLM provider actually usable?"
+//
+// Every keyed-provider dispatcher in haiku-client.mjs degrades to `claude -p`
+// when the API call fails, and says so with one debugLog('WARN') that no surface
+// reads. That is the right RUNTIME behaviour — a memory hook must never block on
+// a provider outage — but it means a permanently broken provider is invisible.
+//
+// Observed 2026-08-19 on the dev box: OPENROUTER_API_KEY set, every call failing
+// at the socket (a local firewall denied the node binary's egress), doctor
+// reporting 21/21 green with no mention of the provider. Cost of the silence:
+// 13.5s per background LLM call instead of 1.4s, for weeks.
+//
+// Scope: TRANSPORT only. A rejected key answers HTTP 401 — loud, and it costs a
+// real request plus shipping the key to learn. Unreachability is the silent
+// class, and one socket open/close answers it.
+
+import net from 'node:net';
+import { httpConnectProxyFor, connectProbeViaProxy, redactProxyUrl } from './proxy-fetch.mjs';
+
+const PROVIDER_HOST = { api: 'api.anthropic.com', openrouter: 'openrouter.ai' };
+
+/**
+ * Open and immediately close a TCP connection. No TLS, no request, no key.
+ * @param {string} host
+ * @param {{port?: number, timeout?: number}} [opts]
+ * @returns {Promise<{reachable: boolean, error?: string}>} never rejects
+ */
+export function tcpReachable(host, { port = 443, timeout = 4000 } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    const socket = net.connect({ host, port });
+    socket.setTimeout(timeout, () => { socket.destroy(); done({ reachable: false, error: 'timeout' }); });
+    socket.on('connect', () => { socket.destroy(); done({ reachable: true }); });
+    socket.on('error', (e) => { socket.destroy(); done({ reachable: false, error: e.code || e.message }); });
+  });
+}
+
+/**
+ * One doctor line about the LLM provider.
+ *
+ * Mode detection is duplicated from haiku-client's detectMode ON PURPOSE: that
+ * one memoizes into a module-level `_mode` for the life of the process, which is
+ * correct for a worker and wrong for a diagnostic. The precedence order is the
+ * shared contract and must not drift — ANTHROPIC_API_KEY, then OPENROUTER_API_KEY,
+ * then the CLI.
+ *
+ * Two seams, not one: the proxied and direct paths ask different questions of
+ * different endpoints, so a single injected probe would have to switch on its
+ * own arguments — the shape that hides which path a test actually exercised.
+ *
+ * @param {{_probe?: Function, _proxyProbe?: Function}} [seams]
+ * @returns {Promise<{mode: string, level: 'ok'|'warn', message: string}>}
+ */
+export async function llmProviderStatus({ _probe = tcpReachable, _proxyProbe = connectProbeViaProxy } = {}) {
+  const mode = process.env.ANTHROPIC_API_KEY ? 'api'
+    : process.env.OPENROUTER_API_KEY ? 'openrouter' : 'cli';
+
+  if (mode === 'cli') {
+    return {
+      mode,
+      level: 'ok',
+      message: 'LLM provider: claude CLI (no ANTHROPIC_API_KEY / OPENROUTER_API_KEY set)',
+    };
+  }
+
+  const host = PROVIDER_HOST[mode];
+  const proxy = httpConnectProxyFor(`https://${host}/`);
+  // Report the hop actually exercised. When a proxy is configured the request
+  // path is node → proxy → host, so probing the host directly would answer a
+  // question the product never asks — and on a machine where only the proxy is
+  // permitted, it would answer it wrong.
+  // Redacted: HTTP(S)_PROXY legitimately carries user:pass@ and this string is
+  // printed and serialized into `doctor --json`. (pre-tag review)
+  const via = proxy ? `via proxy ${redactProxyUrl(proxy)}` : 'direct';
+
+  let result;
+  try {
+    // Through a proxy the question is "does a tunnel open", not "is the port
+    // occupied": a plain TCP connect passes against a SOCKS-only listener or a
+    // proxy that forbids CONNECT, and doctor would then certify a dead
+    // provider. (pre-tag review)
+    result = proxy
+      ? await _proxyProbe(proxy, host, { timeout: 4000 })
+      : await _probe(host, { port: 443 });
+  } catch (e) {
+    result = { reachable: false, error: e?.message || String(e) };
+  }
+
+  if (result?.reachable) {
+    return { mode, level: 'ok', message: `LLM provider: ${mode} key set, ${host} reachable (${via})` };
+  }
+  return {
+    mode,
+    level: 'warn',
+    // Name the consequence, not just the probe: "unreachable" alone reads as
+    // cosmetic, and the actual cost (every background call silently falling back
+    // to a ~10x slower path) is the reason anyone should care.
+    message: `LLM provider: ${mode} key set but unreachable ${via} (${result?.error || 'unknown'}) — `
+      + 'every background LLM call fails and silently falls back to the claude CLI (~10x slower); '
+      + 'check egress/proxy for this node binary',
+  };
+}

package/lib/observation-write.mjs

@@ -28,6 +28,15 @@ const VALID_SCOPES = new Set(['file', 'module', 'project', 'environment']);
 export function normalizeScope(value) {
   return typeof value === 'string' && VALID_SCOPES.has(value) ? value : null;
 }
+
+// Single source for the scope-classification legend (D#135 P3). THREE write
+// faces classify scope — the episode summarizer (hook-llm), save-time enrichment
+// (lib/save-enrich) and the re-enrich passes (hook-optimize). Hand-copied
+// definitions would drift, and a column whose `environment` means something
+// different per face makes the CLAUDE_MEM_SCOPE_FILTER read lever incoherent —
+// the same OBS_TYPE_ENUM hard-copy problem the 2026-07-17 audit flagged.
+// Rendered as `scope: ${SCOPE_PROMPT_LEGEND}` in every prompt.
+export const SCOPE_PROMPT_LEGEND = "where does the lesson APPLY (not where it was learned)? file = specific to the touched file(s)' own code. module = a directory/subsystem of this project. project = a project-wide convention, architecture, or workflow. environment = a tooling/OS/CI/network/registry/service quirk (proxy, npm, git, GitHub, shell, runner, editor) that would hold in ANY project — even though some project files were touched when it surfaced. When lesson_learned is null, still classify the episode's dominant subject.";
 // Defaults for columns a caller omits. NULL-default columns (subtitle,
 // search_aliases) match the schema DEFAULT, so omitting == the old short INSERT.
 // concepts/facts/files_read default to the empty literals the manual path used.

package/lib/proxy-fetch.mjs

@@ -0,0 +1,245 @@
+// lib/proxy-fetch.mjs — HTTPS over an HTTP CONNECT tunnel, using node: built-ins only.
+//
+// Node's global fetch (undici) does NOT honour HTTP(S)_PROXY, and undici's
+// ProxyAgent is not importable without adding a dependency (this package ships
+// three: @modelcontextprotocol/sdk, better-sqlite3, zod — a proxy shim is not
+// worth a fourth). In an environment where external hosts are only reachable
+// through a local proxy, a direct fetch hangs or dies instantly, so every
+// network feature silently stops working.
+//
+// This lived as two private functions inside haiku-client.mjs (added for the
+// OpenRouter path, memory #8757). It is a lib module now because it was needed
+// in a SECOND place and nobody could see that: hook-update.mjs kept calling bare
+// `fetch`, so on a proxy-bound machine the auto-update version check and the
+// release download both failed silently and the plugin reported itself
+// permanently up to date. Measured on the dev box 2026-08-19: direct egress to
+// api.github.com / openrouter.ai = HTTP 000, the same requests through the proxy
+// = HTTP 200.
+//
+// Zero behaviour change when no proxy is configured: httpConnectProxyFor returns
+// null and callers keep native fetch.
+
+import http from 'node:http';
+import https from 'node:https';
+import tls from 'node:tls';
+
+/**
+ * The HTTP proxy that should carry `targetUrl`, or null to use native fetch.
+ * Deliberately ignores socks5:// (ALL_PROXY on Clash/v2ray setups): an HTTP
+ * CONNECT sent into a SOCKS listener does not fail fast, it hangs.
+ * @param {string} targetUrl
+ * @returns {string|null}
+ */
+export function httpConnectProxyFor(targetUrl) {
+  const proxy = process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy;
+  if (!proxy || !/^https?:\/\//.test(proxy)) return null; // socks5 ALL_PROXY not supported here
+  try {
+    const host = new URL(targetUrl).hostname;
+    const noProxy = (process.env.NO_PROXY || process.env.no_proxy || '').split(',').map((s) => s.trim()).filter(Boolean);
+    if (noProxy.some((n) => n === host || (n.startsWith('.') && host.endsWith(n.slice(1))))) return null;
+    return proxy;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A proxy URL safe to print. HTTP(S)_PROXY legitimately carries `user:pass@`,
+ * and this string reaches doctor's stdout and `doctor --json` — the text users
+ * paste into bug reports. Host and port survive so the line stays diagnosable.
+ * Never returns the input on the error path: echoing an unparseable value back
+ * is how the leak would return through the defensive branch. (pre-tag review)
+ * @param {string|null|undefined} proxy
+ * @returns {string}
+ */
+export function redactProxyUrl(proxy) {
+  if (!proxy || typeof proxy !== 'string') return '(unset)';
+  try {
+    const u = new URL(proxy);
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return '(unparseable proxy url)';
+  }
+}
+
+/**
+ * Does this proxy actually establish a tunnel to `host`? Opens a CONNECT,
+ * checks for 200, closes. No TLS, no request, no credentials.
+ *
+ * A plain TCP connect to the proxy port is NOT this question: anything
+ * listening there answers it yes — a SOCKS-only listener, a proxy that forbids
+ * CONNECT, or whatever took the port after the proxy died. That gap made
+ * doctor's provider check report a healthy provider against a socket that
+ * could not carry one request. (pre-tag review)
+ *
+ * @param {string} proxy
+ * @param {string} host target hostname
+ * @param {{timeout?: number, port?: number}} [opts]
+ * @returns {Promise<{reachable: boolean, error?: string}>} never rejects
+ */
+export function connectProbeViaProxy(proxy, host, { timeout = 4000, port = 443 } = {}) {
+  return new Promise((resolve) => {
+    let p;
+    try { p = new URL(proxy); } catch { return resolve({ reachable: false, error: 'unparseable proxy url' }); }
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    const req = http.request({
+      host: p.hostname,
+      port: Number(p.port) || 80,
+      method: 'CONNECT',
+      path: `${host}:${port}`,
+      headers: { Host: `${host}:${port}` },
+    });
+    req.setTimeout(timeout, () => { req.destroy(); done({ reachable: false, error: 'timeout' }); });
+    req.on('connect', (res, socket) => {
+      socket.destroy();
+      done(res.statusCode === 200
+        ? { reachable: true }
+        : { reachable: false, error: `proxy CONNECT ${res.statusCode}` });
+    });
+    // A listener that accepts TCP then closes (not a proxy) lands here, as does
+    // a refused connection. Both are "no tunnel", which is the whole question.
+    req.on('error', (e) => done({ reachable: false, error: e.code || e.message }));
+    req.on('close', () => done({ reachable: false, error: 'closed without CONNECT response' }));
+    req.end();
+  });
+}
+
+/**
+ * ONE request over a freshly-opened CONNECT tunnel — no redirect handling.
+ * fetch-compatible subset: resolves { ok, status, headers, text(), json(),
+ * buffer() }; REJECTS on connect/timeout/socket error so a caller's try/catch
+ * degrades exactly as it would for a failed fetch.
+ *
+ * The body is collected as Buffers (not a utf8 string) so the same primitive
+ * serves the JSON call sites and the release manifest/signature asset download.
+ *
+ * @param {string} proxy proxy origin, e.g. http://127.0.0.1:10808
+ * @param {string} url absolute https:// target
+ * @param {{method?:string, headers?:object, body?:string|Buffer, timeout?:number}} [opts]
+ */
+export function onceViaConnectProxy(proxy, url, { method = 'GET', headers = {}, body = '', timeout = 20000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let p, t;
+    try { p = new URL(proxy); t = new URL(url); } catch (e) { return reject(e); }
+    const port = Number(t.port) || 443;
+    let settled = false;
+    const finish = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(overall);
+      fn(arg);
+    };
+    // `timeout` bounds the WHOLE call, not each phase. Two per-phase
+    // socket timers made a 1000ms budget reject at 2008ms — every caller's
+    // network deadline was silently double what it asked for. Recomputing each
+    // phase's timer from a deadline did NOT fix it: a TLS socket wrapping an
+    // already-connected socket never completes its handshake here, and
+    // ClientRequest.setTimeout arms against socket events that then never come.
+    // So the bound is an explicit timer rather than a claim about when Node
+    // arms its own. unref'd: a background worker must not be held open by it.
+    // (pre-tag review)
+    const deadline = Date.now() + timeout;
+    const remaining = () => Math.max(1, deadline - Date.now());
+    const sockets = [];
+    const overall = setTimeout(() => {
+      for (const s of sockets) { try { s.destroy(); } catch { /* already gone */ } }
+      finish(reject, new Error('proxy request timeout'));
+    }, timeout);
+    if (typeof overall.unref === 'function') overall.unref();
+    const connReq = http.request({
+      host: p.hostname,
+      port: Number(p.port) || 80,
+      method: 'CONNECT',
+      path: `${t.hostname}:${port}`,
+      headers: { Host: `${t.hostname}:${port}` },
+    });
+    connReq.setTimeout(remaining(), () => connReq.destroy(new Error('proxy CONNECT timeout')));
+    connReq.on('error', (e) => finish(reject, e));
+    connReq.on('socket', (s) => sockets.push(s));
+    connReq.on('connect', (res, socket) => {
+      sockets.push(socket);
+      if (res.statusCode !== 200) {
+        socket.destroy();
+        return finish(reject, new Error(`proxy CONNECT ${res.statusCode}`));
+      }
+      const req = https.request(
+        url,
+        { method, headers, createConnection: () => tls.connect({ socket, servername: t.hostname }) },
+        (resp) => {
+          const chunks = [];
+          resp.on('data', (c) => chunks.push(Buffer.from(c)));
+          resp.on('end', () => {
+            const buf = Buffer.concat(chunks);
+            finish(resolve, {
+              ok: resp.statusCode >= 200 && resp.statusCode < 300,
+              status: resp.statusCode,
+              headers: resp.headers,
+              buffer: () => buf,
+              text: () => buf.toString('utf8'),
+              json: () => JSON.parse(buf.toString('utf8')),
+            });
+          });
+        }
+      );
+      req.setTimeout(remaining(), () => req.destroy(new Error('proxy request timeout')));
+      req.on('error', (e) => finish(reject, e));
+      req.end(body);
+    });
+    connReq.end();
+  });
+}
+
+/**
+ * onceViaConnectProxy + redirect following. Native fetch follows redirects by
+ * default, so a call site swapped from fetch to the tunnel needs this or the
+ * GitHub release asset (302 github.com → objects.githubusercontent.com) comes
+ * back as an unusable 302 body.
+ *
+ * Two safety rules the loop enforces, both of which fetch also applies:
+ *   • Authorization is dropped when the hop crosses to a different host — a
+ *     redirect must not be able to walk a credential to another origin.
+ *   • The body is not replayed; a redirected request continues as a bodiless
+ *     GET (fetch's behaviour for 301/302/303).
+ *
+ * @param {string} proxy
+ * @param {string} url
+ * @param {{method?:string, headers?:object, body?:string|Buffer, timeout?:number, maxRedirects?:number}} [opts]
+ * @param {{_once?: Function}} [seams] injectable transport (tests)
+ */
+export async function requestViaConnectProxy(proxy, url, opts = {}, { _once = onceViaConnectProxy } = {}) {
+  const { maxRedirects = 5, ...rest } = opts;
+  let current = url;
+  let next = { method: 'GET', headers: {}, body: '', timeout: 20000, ...rest };
+  // `timeout` is the budget for the CHAIN, not per hop. Native fetch aborts the
+  // whole redirect sequence on one signal; giving each hop a fresh full budget
+  // made a 3s caller worst-case ~18s across 6 hops. (pre-tag review NOTE 7)
+  const chainDeadline = Date.now() + (next.timeout || 20000);
+  for (let hop = 0; ; hop++) {
+    next = { ...next, timeout: Math.max(1, chainDeadline - Date.now()) };
+    const res = await _once(proxy, current, next);
+    const location = res.status >= 300 && res.status < 400 && res.headers && res.headers.location;
+    if (!location || hop >= maxRedirects) return res;
+    const target = new URL(location, current);
+    const sameHost = target.hostname === new URL(current).hostname;
+    const headers = { ...next.headers };
+    if (!sameHost) { delete headers.Authorization; delete headers.authorization; }
+    next = { ...next, method: 'GET', body: '', headers };
+    current = target.toString();
+  }
+}
+
+/** GET convenience wrapper — the shape hook-update's two call sites need. */
+export function getViaConnectProxy(proxy, url, { headers = {}, timeout = 20000, maxRedirects = 5 } = {}) {
+  return requestViaConnectProxy(proxy, url, { method: 'GET', headers, timeout, maxRedirects });
+}
+
+/**
+ * POST convenience wrapper. Kept for the OpenRouter call site, whose contract
+ * predates this module: single request, NO redirect following (the API does not
+ * redirect, and silently re-issuing a prompt POST as a GET would be worse than
+ * surfacing the status).
+ */
+export function postViaConnectProxy(proxy, url, { headers = {}, body = '', timeout = 20000 } = {}) {
+  return onceViaConnectProxy(proxy, url, { method: 'POST', headers, body, timeout });
+}

package/lib/save-enrich.mjs

@@ -9,10 +9,17 @@
 // lesson_learned (obligated types only) + search_aliases (every manual save),
 // executed by a detached worker so the save path itself stays zero-latency.
 //
+// D#135 P3: the same call also classifies `scope` (where the lesson APPLIES).
+// v44 shipped the column plus the CLAUDE_MEM_SCOPE_FILTER read lever, but only
+// hook-llm's episode summarizer ever wrote it — manual saves left it NULL, so on
+// 2026-08-19 every bugfix/decision/discovery row was unclassified (0/41 of the
+// 08-16..08-17 cohort) and the lever was inert on exactly the rows pre-tool
+// recall injects. Riding this Haiku call costs no extra round trip.
+//
 // Contract (empty-overwrite is the historical audit main-class — R1/R4):
-//   • FILL-ONLY-EMPTY: never replaces a caller-written lesson or aliases filled
-//     by a concurrent optimize pass (re-checked inside a BEGIN IMMEDIATE txn).
-//   • Touches ONLY lesson_learned / search_aliases / text (alias append) —
+//   • FILL-ONLY-EMPTY: never replaces a caller-written lesson, aliases, or scope
+//     filled by a concurrent optimize pass (re-checked inside a BEGIN IMMEDIATE txn).
+//   • Touches ONLY lesson_learned / search_aliases / scope / text (alias append) —
 //     title/narrative/type/importance/concepts/facts stay byte-identical.
 //   • Never sets optimized_at: the daily wide re-enrich stays the safety net.
 //   • Silent degradation: no Haiku, bad JSON, ineligible row → row unchanged.
@@ -26,6 +33,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { scrubSecrets, cjkBigrams, truncate, debugCatch } from '../utils.mjs';
 import { scrubRecord } from './scrub-record.mjs';
+import { normalizeScope, SCOPE_PROMPT_LEGEND } from './observation-write.mjs';
 
 export const ENRICH_OBLIGATED_TYPES = new Set(['bugfix', 'decision']);
 
@@ -72,7 +80,7 @@ export function queueSaveEnrich(id) {
  */
 export async function executeSaveEnrich(db, id, { callJson } = {}) {
   const row = db.prepare(`
-    SELECT id, type, title, narrative, text, lesson_learned, search_aliases,
+    SELECT id, type, title, narrative, text, lesson_learned, search_aliases, scope,
            superseded_at, compressed_into
     FROM observations WHERE id = ?
   `).get(id);
@@ -82,7 +90,8 @@ export async function executeSaveEnrich(db, id, { callJson } = {}) {
   const wantLesson = ENRICH_OBLIGATED_TYPES.has(row.type)
     && !(row.lesson_learned && row.lesson_learned.trim());
   const wantAliases = !(row.search_aliases && row.search_aliases.trim());
-  if (!wantLesson && !wantAliases) return { enriched: false, reason: 'complete' };
+  const wantScope = !row.scope;
+  if (!wantLesson && !wantAliases && !wantScope) return { enriched: false, reason: 'complete' };
 
   const { callModelJSON, BG_LLM_TIMEOUT_MS } = await import('../haiku-client.mjs');
   const call = callJson || callModelJSON;
@@ -92,8 +101,9 @@ Title: ${truncate(row.title || '(untitled)', 200)}
 Context: ${truncate(row.narrative || row.text || '(none)', 500)}
 Type: ${row.type || 'change'}
 
-JSON: {"lesson_learned":"the transferable insight (root cause + fix, or constraint + tradeoff) in 1-2 sentences — or 'none' if routine","search_aliases":["alt phrasing","synonym","spelled-out jargon","CJK term if a key domain word has one"]}
-search_aliases: 3-6 terms a user might search for the SAME memory that are NOT already in the title.`;
+JSON: {"lesson_learned":"the transferable insight (root cause + fix, or constraint + tradeoff) in 1-2 sentences — or 'none' if routine","search_aliases":["alt phrasing","synonym","spelled-out jargon","CJK term if a key domain word has one"],"scope":"file|module|project|environment"}
+search_aliases: 3-6 terms a user might search for the SAME memory that are NOT already in the title.
+scope: ${SCOPE_PROMPT_LEGEND}`;
 
   let parsed = null;
   try {
@@ -109,7 +119,10 @@ search_aliases: 3-6 terms a user might search for the SAME memory that are NOT a
   const aliasArr = wantAliases && Array.isArray(parsed.search_aliases)
     ? parsed.search_aliases.filter((a) => typeof a === 'string' && a.trim().length > 0).slice(0, 6)
     : [];
-  if (!lesson && aliasArr.length === 0) return { enriched: false, reason: 'nothing-usable' };
+  // Whitelist-validated: Haiku output is untrusted, anything off-enum becomes null
+  // (= "unclassified", which every scope-aware read path treats as do-not-filter).
+  const scope = wantScope ? normalizeScope(parsed.scope) : null;
+  if (!lesson && aliasArr.length === 0 && !scope) return { enriched: false, reason: 'nothing-usable' };
 
   // Fill-only-empty under BEGIN IMMEDIATE: a concurrent daily-optimize pass (or
   // a caller's mem_update) may have filled either field between spawn and now —
@@ -117,7 +130,7 @@ search_aliases: 3-6 terms a user might search for the SAME memory that are NOT a
   let enriched = false;
   const txn = db.transaction(() => {
     const fresh = db.prepare(`
-      SELECT lesson_learned, search_aliases, text, superseded_at, compressed_into
+      SELECT lesson_learned, search_aliases, scope, text, superseded_at, compressed_into
       FROM observations WHERE id = ?
     `).get(id);
     if (!fresh || fresh.superseded_at || fresh.compressed_into) return;
@@ -139,6 +152,12 @@ search_aliases: 3-6 terms a user might search for the SAME memory that are NOT a
       sets.push('search_aliases = ?', 'text = ?');
       vals.push(safe.search_aliases, safe.text);
     }
+    // Enum value, not free text — no scrubRecord pass needed (and none possible:
+    // a secret can't survive normalizeScope's four-value whitelist).
+    if (scope && !fresh.scope) {
+      sets.push('scope = ?');
+      vals.push(scope);
+    }
     if (sets.length === 0) return;
     db.prepare(`UPDATE observations SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
     enriched = true;

package/mem-cli.mjs

@@ -2790,10 +2790,13 @@ Commands:
     --run-all           Execute bypassing gates
     --task T            Comma-separated: re-enrich,normalize,cluster-merge,smart-compress
     --max N             Max items per task (1-100, default 15)
-    --scope S           re-enrich scope: narrow (default) | wide | aliases
+    --scope S           re-enrich scope: narrow (default) | wide | aliases | scopes
                         (aliases: backfill search_aliases on substantive rows that
                          lack them — incl. lesson-bearing manual saves — adds ONLY
                          aliases, never rewrites title/narrative/lesson)
+                        (scopes: backfill the applicability label observations.scope
+                         on rows that lack it — writes ONLY that column, never stamps
+                         optimized_at; feeds CLAUDE_MEM_SCOPE_FILTER)
     --project P         Limit to a single project (.|current = the current project)
     --verbose / -v      Preview also dumps cluster contents + re-enrich samples
 
@@ -3133,8 +3136,8 @@ async function cmdOptimize(db, args) {
   let reenrichScope = 'narrow';
   if (scopeIdx >= 0 && args[scopeIdx + 1] !== undefined) {
     const raw = args[scopeIdx + 1];
-    if (raw !== 'narrow' && raw !== 'wide' && raw !== 'aliases') {
-      fail(`[mem] Invalid --scope "${raw}". Use: narrow, wide, aliases`);
+    if (raw !== 'narrow' && raw !== 'wide' && raw !== 'aliases' && raw !== 'scopes') {
+      fail(`[mem] Invalid --scope "${raw}". Use: narrow, wide, aliases, scopes`);
       return;
     }
     reenrichScope = raw;
@@ -3153,7 +3156,7 @@ async function cmdOptimize(db, args) {
     const preview = optimizePreview(db, { project, detail: verbose });
     out('[mem] 🔍 LLM Optimization Preview:');
     if (project) out(`  Project filter: ${project}`);
-    out(`  Re-enrich candidates: ${preview.reenrich}${preview.reenrichWide !== undefined && preview.reenrichWide !== null ? `  (wide scope: ${preview.reenrichWide})` : ''}${preview.reenrichAliases ? `  (aliases scope: ${preview.reenrichAliases})` : ''}`);
+    out(`  Re-enrich candidates: ${preview.reenrich}${preview.reenrichWide !== undefined && preview.reenrichWide !== null ? `  (wide scope: ${preview.reenrichWide})` : ''}${preview.reenrichAliases ? `  (aliases scope: ${preview.reenrichAliases})` : ''}${preview.reenrichScopes ? `  (scopes scope: ${preview.reenrichScopes})` : ''}`);
     out(`  Normalize: ${preview.normalizeGateOpen ? `${preview.normalize} unique concepts` : 'gate closed (7-day interval)'}`);
     // "candidates" matches the MCP wording (server.mjs mem_optimize preview) AND the
     // Re-enrich line just above, which already read that way on both surfaces. The two

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.72.1",
+  "version": "3.74.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.72.1",
+      "version": "3.74.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.72.1",
+  "version": "3.74.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",
@@ -83,6 +83,8 @@
     "lib/hook-stdout.mjs",
     "lib/proc-lock.mjs",
     "lib/atomic-write.mjs",
+    "lib/proxy-fetch.mjs",
+    "lib/llm-provider-probe.mjs",
     "lib/release-digest.mjs",
     "lib/mem-override.mjs",
     "lib/injected-ids.mjs",

package/source-files.mjs

@@ -111,6 +111,8 @@ export const SOURCE_FILES = [
   // + auto-update lock). Must ship or a partial install/update skips them.
   'lib/proc-lock.mjs',
   'lib/atomic-write.mjs',
+  'lib/proxy-fetch.mjs',
+  'lib/llm-provider-probe.mjs',
   // P1 supply-chain: shared release-signing core (sha256 manifest + Ed25519
   // verify). Imported by hook-update.mjs (verify) + scripts/sign-release.mjs (CI
   // sign). Must ship or auto-update can't verify release signatures.

package/utils.mjs

@@ -16,7 +16,7 @@ export { scrubSecrets, SECRET_PATTERNS } from './secret-scrub.mjs';
 export { stripPrivate } from './lib/private-strip.mjs';
 export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey, formatErrorRecallHints, neutralizeContextDelimiters } from './format-utils.mjs';
 export { computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity } from './hash-utils.mjs';
-export { detectBashSignificance, extractErrorKeywords, extractFilePaths, stripTestSuffix } from './bash-utils.mjs';
+export { detectBashSignificance, extractErrorKeywords, planErrorRecall, extractFilePaths, stripTestSuffix } from './bash-utils.mjs';
 
 // Internal imports for functions that remain in this module
 import { truncate } from './format-utils.mjs';