claude-mem-lite 3.66.1 → 3.67.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.66.1",
+      "version": "3.67.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.66.1",
+  "version": "3.67.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/haiku-client.mjs

@@ -428,26 +428,122 @@ async function callModelAPI(prompt, model, { timeout, maxTokens, temperature = D
   }
 }
 
+// ─── Headless CLI flag compatibility ─────────────────────────────────────────
+//
+// --no-session-persistence + DISABLE_CLAUDEMD_HOOKS (2026-08-16): these headless
+// calls were paying the full interactive-session tax — 1,004 transcripts piled up
+// in ~/.claude/projects/-tmp/, and every spawn ran the claudemd plugin's whole
+// hook fan-out (its SessionStart banner alone logged 682 rows in 3 days, drowning
+// that project's telemetry). The persistence flag is OAuth-safe (probed);
+// `--bare`/CLAUDE_CODE_SIMPLE are NOT (they hard-require ANTHROPIC_API_KEY —
+// "Not logged in" on OAuth machines). The user's global CLAUDE.md injection has
+// no OAuth-safe opt-out; accepted (haiku + prompt caching keeps it cheap).
+//
+// The flag is an unguarded dependency on a recent Claude Code CLI: package.json
+// declares only node>=20, no Claude Code floor. On an older binary the spawn dies
+// in argument parsing, the catch swallows it, and every CLI-leg LLM call returns
+// null — no retry, no telemetry. That leg is what the keyed providers degrade to,
+// so such a user loses enrichment, summarization and optimize all at once. So:
+// detect the arg-parse rejection, retry once without the flag, and cache the
+// negative only AFTER the retry actually succeeded. Caching on the failure
+// instead would let one transient non-zero exit that happens to mention the flag
+// push a healthy CLI back onto the session tax for the rest of the process.
+// Hooks are short-lived, so an old binary pays one extra fail-fast spawn per
+// process; the long-lived MCP server pays it once per run.
+const HEADLESS_FLAG = '--no-session-persistence';
+let _headlessFlagOk = true;
+
+/** @internal test hook — module-level compat state must not leak across cases. */
+export function _resetHeadlessFlag() { _headlessFlagOk = true; }
+
+function claudeArgs(modelName) {
+  return _headlessFlagOk
+    ? ['-p', '--model', modelName, HEADLESS_FLAG]
+    : ['-p', '--model', modelName];
+}
+
+// A retry is only ever worth it when the diagnostic NAMES the token it rejected —
+// every argv parser does, and requiring it is what keeps this from firing on
+// Claude Code's own config diagnostics. The installed CLI carries strings like
+// `Skill X has invalid effort 'y'. Valid options: …` and `Input validation error:
+// Invalid arguments for tool`, which an unanchored unknown-word/option-word regex
+// matches outright. Those are emitted for a malformed agent/skill file — a
+// *persistent* condition — so an unanchored match would fire on the next transient
+// 529, permanently revert v3.66.0's session-tax fix on a perfectly healthy CLI,
+// and log a WARN blaming a flag that was never the problem (pre-tag review, HIGH).
+// Deliberately NOT keyed on exit code alone either: a non-zero exit is also the
+// normal shape of an overload/auth failure.
+const FLAG_TOKEN = /no-session-persistence/;
+const PARSE_REJECTION = /(unknown|unrecognized|unsupported|invalid|unexpected)[^\n]{0,40}(option|argument|flag|switch)/i;
+
+// Below this many ms left, a retry can only spawn a process and immediately kill
+// it — worse than returning the original failure.
+const RETRY_MIN_BUDGET_MS = 500;
+
+export function _isUnknownFlagError(diagnostic) {
+  if (!diagnostic) return false;
+  return FLAG_TOKEN.test(diagnostic) && (PARSE_REJECTION.test(diagnostic) || /usage:/i.test(diagnostic));
+}
+
+// stdout as well as stderr: a parser that prints its rejection (or usage banner)
+// on stdout is otherwise invisible here, and FLAG_TOKEN keeps the widened input
+// from loosening the match.
+function cliDiagnostic(e) {
+  const err = e?.stderr?.toString?.() || e?.output?.[2]?.toString?.() || '';
+  const out = e?.stdout?.toString?.() || e?.output?.[1]?.toString?.() || '';
+  return `${err}\n${out}`;
+}
+
+/**
+ * Shared blocking `claude -p` runner for every sync CLI leg (callModelCLI,
+ * callHaikuCLI, hook-shared#callLLM). Throws exactly what execFileSync throws so
+ * each caller keeps its own partial-output salvage; the only added behaviour is
+ * the one-shot flag-compat retry described above.
+ * @param {string} modelName CLI model name ('haiku'|'sonnet')
+ * @param {{input:string, timeout:number}} opts
+ * @returns {string} raw stdout
+ */
+export function execClaudeCliSync(modelName, { input, timeout }) {
+  const opts = {
+    input,
+    timeout,
+    encoding: 'utf8',
+    env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1', DISABLE_CLAUDEMD_HOOKS: '1' },
+    stdio: ['pipe', 'pipe', 'pipe'],
+    cwd: '/tmp', // Prevent ghost sessions in the user's /resume list
+  };
+  const args = claudeArgs(modelName);
+  const started = Date.now();
+  try {
+    return execFileSync(getClaudePath(), args, opts);
+  } catch (e) {
+    // A timeout is NOT a parse rejection. execFileSync kills the child and throws
+    // with its partial buffers attached (callModelCLI's salvage depends on exactly
+    // that), so without this guard a slow call whose output merely looked
+    // parse-shaped would be retried on the FULL original budget — doubling a
+    // latency-bound ceiling. lesson-bridge runs this leg at 2500ms on PreToolUse,
+    // where the CLI is measured at 8–13s and therefore times out routinely.
+    if (e?.killed || e?.signal) throw e;
+    // `args`, not the live flag: what matters is whether THIS attempt carried it.
+    // Symmetry with the async leg, where the distinction is load-bearing (a
+    // sibling can flip the flag across an await). Here execFileSync blocks the
+    // event loop for the whole child, so no other JS can interleave and the two
+    // readings are behaviourally identical — the substitution is deliberately
+    // mutation-silent, kept so the two legs cannot drift apart in meaning.
+    if (!args.includes(HEADLESS_FLAG) || !_isUnknownFlagError(cliDiagnostic(e))) throw e;
+    const remaining = timeout - (Date.now() - started);
+    if (remaining < RETRY_MIN_BUDGET_MS) throw e;
+    const out = execFileSync(getClaudePath(), ['-p', '--model', modelName], { ...opts, timeout: remaining });
+    _headlessFlagOk = false;
+    debugLog('WARN', 'cli-compat', `claude CLI rejected ${HEADLESS_FLAG}; dropped for this process (the headless session tax returns — upgrade Claude Code to avoid it)`);
+    return out;
+  }
+}
+
 function callModelCLI(prompt, model, { timeout }) {
   const modelName = MODEL_MAP[model] ? model : 'haiku';
   try {
-    // --no-session-persistence + DISABLE_CLAUDEMD_HOOKS (2026-08-16): these
-    // headless calls were paying the full interactive-session tax — 1,004
-    // transcripts piled up in ~/.claude/projects/-tmp/, and every spawn ran
-    // the claudemd plugin's whole hook fan-out (its SessionStart banner alone
-    // logged 682 rows in 3 days, drowning that project's telemetry). The
-    // persistence flag is OAuth-safe (probed); `--bare`/CLAUDE_CODE_SIMPLE are
-    // NOT (they hard-require ANTHROPIC_API_KEY — "Not logged in" on OAuth
-    // machines). The user's global CLAUDE.md injection has no OAuth-safe
-    // opt-out; accepted (haiku + prompt caching keeps it cheap).
-    const result = execFileSync(getClaudePath(), ['-p', '--model', modelName, '--no-session-persistence'], {
-      input: flattenForCLI(prompt),
-      timeout,
-      encoding: 'utf8',
-      env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1', DISABLE_CLAUDEMD_HOOKS: '1' },
-      stdio: ['pipe', 'pipe', 'pipe'],
-      cwd: '/tmp',
-    });
+    const result = execClaudeCliSync(modelName, { input: flattenForCLI(prompt), timeout });
     const text = result.trim();
     return text ? { text } : null;
   } catch (e) {
@@ -479,23 +575,31 @@ function callModelCLI(prompt, model, { timeout }) {
  * @param {{timeout:number}} opts  SIGKILL after `timeout` ms; no retry.
  * @returns {Promise<{text:string}|null>}
  */
-export function callModelCLIAsync(prompt, model, { timeout }) {
-  return new Promise((resolve) => {
-    const modelName = MODEL_MAP[model] ? model : 'haiku';
+export async function callModelCLIAsync(prompt, model, { timeout }) {
+  const modelName = MODEL_MAP[model] ? model : 'haiku';
+  const payload = flattenForCLI(prompt);
+  const started = Date.now();
+
+  // One spawn. Resolves {result, stderr, stdout, code}, never rejects. `code` is
+  // a number ONLY when the child exited on its own; a timeout/SIGKILL or a spawn
+  // error reports null, which is what keeps either from being mistaken for an
+  // argument-parse rejection and costing a second full-budget spawn.
+  const attempt = (args, budget) => new Promise((resolve) => {
     let child;
     try {
-      // Same headless-tax flags as callModelCLI (rationale there).
-      child = spawn(getClaudePath(), ['-p', '--model', modelName, '--no-session-persistence'], {
+      // Same headless-tax flags + flag-compat retry as callModelCLI (rationale there).
+      child = spawn(getClaudePath(), args, {
         env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1', DISABLE_CLAUDEMD_HOOKS: '1' },
         cwd: '/tmp',
         stdio: ['pipe', 'pipe', 'pipe'],
       });
     } catch (e) {
       debugCatch(e, `${model}-cli-async`);
-      resolve(null);
+      resolve({ result: null, stderr: '', stdout: '', code: null });
       return;
     }
     let stdout = '';
+    let stderr = '';
     let settled = false;
     const done = (val) => {
       if (settled) return;
@@ -510,26 +614,59 @@ export function callModelCLIAsync(prompt, model, { timeout }) {
       // brace check would discard a complete-but-```json-fenced payload (#8605);
       // parseJsonFromLLM strips fences before validating, and the caller re-parses
       // the returned text the same way.
-      if (t && parseJsonFromLLM(t) !== null) { done({ text: t }); return; }
-      done(null);
-    }, timeout);
+      if (t && parseJsonFromLLM(t) !== null) { done({ result: { text: t }, stderr, stdout, code: null }); return; }
+      done({ result: null, stderr, stdout, code: null });
+    }, budget);
     child.stdout?.setEncoding('utf8'); // decode multi-byte UTF-8 (CJK) across chunk boundaries
     child.stdout?.on('data', (d) => { stdout += d; });
-    child.stderr?.on('data', () => {}); // drain stderr so a chatty child can't block on a full pipe
-    child.on('error', (e) => { debugCatch(e, `${model}-cli-async`); done(null); });
-    child.on('close', () => {
+    // Keep draining stderr so a chatty child can't block on a full pipe, but keep
+    // a bounded head of it — the flag-compat probe needs the parser's complaint.
+    // Slice AFTER appending: checking the length first lets one arbitrarily large
+    // chunk through whole, which is the shape a single big stderr write takes.
+    child.stderr?.setEncoding?.('utf8');
+    child.stderr?.on('data', (d) => { stderr = (stderr + d).slice(0, 4096); });
+    child.on('error', (e) => { debugCatch(e, `${model}-cli-async`); done({ result: null, stderr: '', stdout: '', code: null }); });
+    child.on('close', (code) => {
       const t = stdout.trim();
-      done(t ? { text: t } : null);
+      done({ result: t ? { text: t } : null, stderr, stdout, code });
     });
     // EPIPE guard: the child may exit before we finish writing stdin.
     child.stdin?.on('error', () => {});
     try {
-      child.stdin?.write(flattenForCLI(prompt));
+      child.stdin?.write(payload);
       child.stdin?.end();
     } catch (e) {
       debugCatch(e, `${model}-cli-async:stdin`);
     }
   });
+
+  const firstArgs = claudeArgs(modelName);
+  const first = await attempt(firstArgs, timeout);
+  // Judged on `firstArgs`, not the live flag: a concurrent sibling may have
+  // flipped it between our spawn and our resume, and reading the global there
+  // would silently deny THIS call the retry it earned (MCP server, concurrent
+  // deep-search escalations). Gating on the exit code before `first.result` also
+  // covers a CLI that prints its usage banner to stdout and exits non-zero —
+  // otherwise that banner is returned as the model's answer and nothing retries.
+  const rejected = firstArgs.includes(HEADLESS_FLAG)
+    && typeof first.code === 'number' && first.code !== 0
+    && _isUnknownFlagError(`${first.stderr}\n${first.stdout.slice(0, 4096)}`);
+  if (!rejected) return first.result;
+  // The rejection is instantaneous (the child dies in argv parsing), so the retry
+  // normally gets nearly the whole budget; spend only what is left of it.
+  const remaining = timeout - (Date.now() - started);
+  if (remaining < RETRY_MIN_BUDGET_MS) return first.result;
+  const second = await attempt(['-p', '--model', modelName], remaining);
+  // Cache on the retry's EXIT, not its payload. Empty output is a designed
+  // outcome here (emit-nothing prompts, an `N/A` that trims away), so keying on
+  // text left the long-lived MCP server re-probing — two spawns per call, for the
+  // life of the process — on exactly the old CLI this exists to rescue. The sync
+  // twin caches on any non-throwing run; this now means the same thing.
+  if (second.code === 0) {
+    _headlessFlagOk = false;
+    debugLog('WARN', `${model}-cli-async`, `claude CLI rejected ${HEADLESS_FLAG}; dropped for this process (the headless session tax returns — upgrade Claude Code to avoid it)`);
+  }
+  return second.result;
 }
 
 // ─── API Mode ────────────────────────────────────────────────────────────────
@@ -635,15 +772,8 @@ async function callOpenRouterAPI(prompt, tier, { timeout, maxTokens, temperature
 function callHaikuCLI(prompt, { timeout }) {
   const { cli: modelName } = resolveModel();
   try {
-    // Same headless-tax flags as callModelCLI (rationale there).
-    const result = execFileSync(getClaudePath(), ['-p', '--model', modelName, '--no-session-persistence'], {
-      input: flattenForCLI(prompt),
-      timeout,
-      encoding: 'utf8',
-      env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1', DISABLE_CLAUDEMD_HOOKS: '1' },
-      stdio: ['pipe', 'pipe', 'pipe'],
-      cwd: '/tmp', // Prevent ghost sessions in user's /resume list
-    });
+    // Same headless-tax flags + flag-compat retry as callModelCLI (rationale there).
+    const result = execClaudeCliSync(modelName, { input: flattenForCLI(prompt), timeout });
     const text = result.trim();
     return text ? { text } : null;
   } catch (e) {

package/hook-semaphore.mjs

@@ -4,9 +4,33 @@
 import { join } from 'path';
 import { readFileSync, unlinkSync, readdirSync, openSync, closeSync, writeSync, constants as fsConstants } from 'fs';
 import { RUNTIME_DIR } from './hook-shared.mjs';
+import { BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
 
 export const LLM_SEM_MAX = 2;
-export const LLM_SEM_TIMEOUT = 30000; // 30s max wait
+
+// D#134 MEDIUM-2 — both budgets are DERIVED from the longest a slot can
+// legitimately be held, not hand-set. They used to be the literals 30000 and
+// 60000, sized for the ~15-20s LLM calls of the time; v3.66.0 raised the
+// background call budget to 45s and neither literal followed, leaving two
+// silent failures:
+//
+//   • wait budget < hold: with both slots busy the third worker gave up after
+//     30s while a holder was still legitimately working, and its caller fell
+//     through to degraded storage — the observation is SAVED but never
+//     enriched. Nothing errors; the row just quietly lacks aliases/lesson.
+//   • stale threshold barely above hold: a 45s holder had 15s of margin, so a
+//     slow SIGTERM, GC pause, or loaded machine let a PEER delete the live
+//     holder's file. That drops it out of `active`, and the peer then sees
+//     room that does not exist — more than LLM_SEM_MAX concurrent calls.
+//
+// Wait one full hold plus a wait-cycle of slack: the worst honest case is
+// arriving just as a 45s call started.
+export const LLM_SEM_TIMEOUT = BG_LLM_TIMEOUT_MS + 15000; // 60s max wait
+// Reaping is the PID-REUSE backstop, not the liveness test (that is
+// process.kill(pid, 0) below). At 2x the hold plus slack it cannot fire on a
+// working holder, which is why the ts written at acquire never needs
+// refreshing — a heartbeat would buy nothing this margin doesn't.
+export const LLM_SEM_STALE_MS = BG_LLM_TIMEOUT_MS * 2 + 30000; // 120s
 
 export const sleepMs = (ms) => new Promise(r => setTimeout(r, ms));
 
@@ -57,18 +81,24 @@ export async function acquireLLMSlot() {
           const raw = readFileSync(fp, 'utf8');
           const info = JSON.parse(raw);
           const age = Date.now() - (info.ts || 0);
-          if (age > 60000) {
-            try { unlinkSync(fp); } catch {}
-            continue;
-          }
+          // Liveness FIRST, age second. The pre-D#134 order reaped on age alone,
+          // which evicted holders that were alive and mid-call (see the budget
+          // note at the top of this file). A dead holder is reaped at any age;
+          // a live one only once its age is implausible as a real hold, which is
+          // the pid-reuse case the age check exists for.
           if (info.pid) {
-            try { process.kill(info.pid, 0); active++; } catch (killErr) {
-              if (killErr.code === 'ESRCH') { try { unlinkSync(fp); } catch {} }
-              else { active++; } // EPERM = process exists but different user
+            let alive;
+            try { process.kill(info.pid, 0); alive = true; } catch (killErr) {
+              // EPERM = process exists but belongs to another user → alive.
+              alive = killErr.code !== 'ESRCH';
             }
-          } else {
-            active++;
+            if (!alive) { try { unlinkSync(fp); } catch {} continue; }
+          }
+          if (age > LLM_SEM_STALE_MS) {
+            try { unlinkSync(fp); } catch {}
+            continue;
           }
+          active++;
         } catch {
           // Corrupt/unreadable semaphore file — treat as stale and remove
           try { unlinkSync(fp); } catch {}

package/hook-shared.mjs

@@ -1,7 +1,7 @@
 // claude-mem-lite: Shared infrastructure for hook.mjs and hook-llm.mjs
 // Constants, session management, DB access, LLM calls, process utilities
 
-import { execFileSync, spawn } from 'child_process';
+import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import { join } from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync, statSync, unlinkSync, chmodSync } from 'fs';
@@ -10,7 +10,7 @@ import { ensureDbWithWalRecovery, DB_DIR } from './schema.mjs';
 // Pure-`node:`/local module (it imports only binding-probe + native-binding-hint, and
 // neither imports this file) — no cycle.
 import { recordHookError } from './lib/hook-telemetry.mjs';
-import { getClaudePath as getClaudePathShared, resolveModel as resolveModelShared, flattenForCLI as _flattenForCLI, detectMode as detectLLMMode, callHaiku, BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
+import { execClaudeCliSync, resolveModel as resolveModelShared, flattenForCLI as _flattenForCLI, detectMode as detectLLMMode, callHaiku, BG_LLM_TIMEOUT_MS } from './haiku-client.mjs';
 // Phase D: invited-memory sentinel detection. memdir.mjs/claudemd.mjs only pull in
 // fs/path/os/crypto; adopt-content.mjs is pure strings. No circular deps —
 // neither imports hook-shared.
@@ -318,16 +318,10 @@ export async function callLLM(prompt, timeoutMs = BG_LLM_TIMEOUT_MS) {
 
   const { cli: modelName } = resolveModelShared();
   try {
-    // Same headless-tax flags as haiku-client.mjs#callModelCLI (rationale
-    // there): no transcript persistence, no claudemd hook fan-out.
-    const result = execFileSync(getClaudePathShared(), ['-p', '--model', modelName, '--no-session-persistence'], {
-      input: _flattenForCLI(prompt),
-      timeout: timeoutMs,
-      encoding: 'utf8',
-      env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1', DISABLE_CLAUDEMD_HOOKS: '1' },
-      stdio: ['pipe', 'pipe', 'pipe'],
-      cwd: '/tmp', // Prevent ghost sessions in user's /resume list
-    });
+    // Shared runner with haiku-client.mjs#callModelCLI (rationale there): no
+    // transcript persistence, no claudemd hook fan-out, and the one-shot
+    // retry-without-flag that keeps this leg alive on an older Claude Code CLI.
+    const result = execClaudeCliSync(modelName, { input: _flattenForCLI(prompt), timeout: timeoutMs });
     return result.trim();
   } catch (e) {
     const out = _extractResponseFromError(e);

package/hook.mjs

@@ -53,12 +53,14 @@ import { cleanupBroken, decayAndMarkIdle, boostAccessed, selectFuzzyDedupeIds, h
 import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
-  extractAllInjected,
+  extractInjectedBySurface,
+  unionSurfaces,
   extractInjectedFromKeyContext,
   bumpCitationAccess,
   computeCiteRecall,
   applyCitationDecay,
   recordCitationFunnel,
+  recordCitationSurfaces,
   hasMainThreadAssistantText,
 } from './lib/citation-tracker.mjs';
 import { resolveEdgeAttribution, readPreRecallFileEdges } from './lib/edge-attribution.mjs';
@@ -741,7 +743,14 @@ async function handleStop() {
             // filter as citedMain (the numerator, below) — an obs injected only
             // inside a subagent (sidechain) would otherwise enter the denominator
             // but never the numerator and streak-demote despite being used there.
-            const injected = extractAllInjected(transcriptPath, { mainOnly: true });
+            // v45: take the per-FACE breakdown and union it, instead of asking
+            // for the union directly. Same ids (extractAllInjected IS this union
+            // — see unionSurfaces), same single transcript walk, but the split
+            // survives to citation_surface_log below so "which face earns its
+            // budget" becomes answerable. Before this, every face was merged
+            // before anything was recorded and no lever had a target.
+            const injectedBySurface = extractInjectedBySurface(transcriptPath, { mainOnly: true });
+            const injected = unionSurfaces(injectedBySurface);
             // P5 ①: cite-back signals — observations whose warned file the agent
             // edited this session. Union into injected so they're resolved (they
             // were injected via pre-tool-recall) and, below, into cited so the
@@ -789,6 +798,19 @@ async function handleStop() {
                 // obs resolved this run (denominator), promoted = obs cited this run
                 // (numerator). Idempotent (touched is 0 on re-fire) + best-effort.
                 recordCitationFunnel(db, project, sessionId, r.touched, r.promoted);
+                // v45: the same funnel split by injection FACE. Keyed on
+                // ccSessionId — the SAME D#60 reasoning as applyCitationDecay
+                // above, and load-bearing here for a second reason: this table
+                // OVERWRITES rather than accumulates, and the memory sessionId
+                // is one file per PROJECT, so two concurrent CC sessions in one
+                // project would share a row and the later Stop would erase the
+                // earlier session's counts outright. citation_log survives the
+                // shared key only because it adds deltas.
+                // keyctx rides along for VISIBILITY only — it is a separate
+                // telemetry table, so recording it here cannot widen the decay
+                // denominator the way v3.66.0's union did.
+                recordCitationSurfaces(db, project, ccSessionId || sessionId,
+                  { ...injectedBySurface, keyctx: keyCtxIds }, citedMain);
                 // P1 (D#78): per-edge attribution. The session cooldown file
                 // (keyed by CC session id) records which FILE each obs was
                 // injected for; resolve those (obs,file) edges as hit/miss with

package/lib/citation-tracker.mjs

@@ -223,28 +223,6 @@ function eachHookAttachment(transcriptPath, fn, opts = {}) {
   }
 }
 
-/**
- * Extract observation IDs injected by pre-tool-recall hook in this transcript.
- *
- * Tighter than `computeCiteRecall`'s over-inclusive "any #NN in non-assistant
- * text" — only counts IDs the agent actually saw from us, not user-pasted
- * references or unrelated #NN tokens in tool output.
- *
- * @param {string|null|undefined} transcriptPath
- * @returns {Set<number>} unique injected IDs (empty set on missing path/file)
- */
-export function extractInjectedFromPreToolUse(transcriptPath, opts = {}) {
-  const ids = new Set();
-  eachHookAttachment(transcriptPath, ({ command, text }) => {
-    if (!command.includes('pre-tool-recall')) return;
-    for (const line of text.split('\n')) {
-      const m = INJECTED_ROW_RE.exec(line);
-      if (m) addObsId(ids, m[1]);
-    }
-  }, opts);
-  return ids;
-}
-
 // v34.x: UserPromptSubmit injection extractor. hook.mjs handleUserPrompt emits
 // formatMemoryLine `- [type] title | Lesson: X (#NN)[ [verify-before-use]]`,
 // which INJECTED_RE (anchored on `#NN [type]`) never matched — leaving this
@@ -260,88 +238,169 @@ const UPS_ID_RE = /\(#(\d{1,7})\)/g;
 // `node "/abs/hook.mjs" user-prompt` → normalized to `node /abs/hook.mjs user-prompt`.
 const UPS_COMMAND_SUFFIX = 'hook.mjs user-prompt';
 
+// user-prompt-search.js formatResults emits `[mem] FYI — Related memories ...`
+// then one `#NN <icon> title` row per obs (raw stdout, line-leading id). Distinct
+// from the `<memory-context>` block (hook.mjs) — the two UPS injectors dedup obs
+// by id at inject time, so they carry DISJOINT obs sets; both must be extracted
+// or the FYI-carried (highest-importance keyContext) obs never reach decay.
+const FYI_HEADER = '[mem] FYI — Related memories';
+// Anchored at line start so `P#NN` past-question rows (user_prompts, different id
+// space) and any `#NN` inside lesson text are NOT matched.
+const FYI_LINE_ID_RE = /^#(\d{1,7})\s/;
+
 /**
- * Extract observation IDs injected by the UserPromptSubmit `<memory-context>`
- * block (hook.mjs handleUserPrompt). Disjoint from pre-tool-recall extraction —
- * the Stop handler unions all surfaces via extractAllInjected.
+ * The injection FACES memory can reach the model through, as stored in
+ * `citation_surface_log.surface` (schema v45). The first four are
+ * query-conditioned — a row appears there because it MATCHED something — and
+ * are the ones that feed the citation-decay denominator via extractAllInjected.
+ * `keyctx` is the odd one out: an unconditional SessionStart render, recorded
+ * for VISIBILITY only and promotion-only in the decay loop (see
+ * extractInjectedFromKeyContext).
+ * @type {ReadonlyArray<'pretool'|'ups'|'error_recall'|'fyi'|'keyctx'>}
+ */
+export const CITATION_SURFACES = ['pretool', 'ups', 'error_recall', 'fyi', 'keyctx'];
+
+// Single source of truth for "which attachment belongs to which face, and how
+// its ids are read off". Both the per-face extractors below AND the one-pass
+// extractInjectedBySurface dispatch through this table, so a face can never be
+// taught to one path and forgotten on the other — the shape of miss that let
+// UserPromptSubmit go unmetered for a whole minor version (v34.x) and that
+// #10379 records as the repeat offender.
+const SURFACE_MATCHERS = {
+  pretool: {
+    // Tighter than `computeCiteRecall`'s over-inclusive "any #NN in
+    // non-assistant text" — only counts IDs the agent actually saw from us,
+    // not user-pasted references or unrelated #NN tokens in tool output.
+    accepts: ({ command }) => command.includes('pre-tool-recall'),
+    collect: (text, add) => {
+      for (const line of text.split('\n')) {
+        const m = INJECTED_ROW_RE.exec(line);
+        if (m) add(m[1]);
+      }
+    },
+  },
+  ups: {
+    // The `<memory-context>` block emitted by hook.mjs handleUserPrompt.
+    // Disjoint from pre-tool-recall by construction: PTR has `[type]` AFTER
+    // `#NN`, UPS has `(#NN)` at end-of-line.
+    accepts: ({ command, text }) =>
+      command.includes(UPS_COMMAND_SUFFIX) && text.includes('<memory-context'),
+    collect: (text, add) => {
+      for (const memLine of text.split('\n')) {
+        if (!memLine.startsWith(UPS_LINE_PREFIX)) continue;
+        // Take the LAST (#NN) on the line — formatMemoryLine puts the obs id
+        // in trailing parens, possibly followed by ` [verify-before-use]`. Any
+        // earlier (#NN) refs are inside title/lesson text.
+        const matches = [...memLine.matchAll(UPS_ID_RE)];
+        if (matches.length === 0) continue;
+        add(matches[matches.length - 1][1]);
+      }
+    },
+  },
+  error_recall: {
+    // hook.mjs triggerErrorRecall → `[claude-mem-lite] Related memories found
+    // for this error:` followed by `  #NN [type] title` lines, delivered via
+    // post-tool-use.sh. High-volume surface that NO extractor matched before
+    // v3.47 — error-recall'd obs accrued injection_count but never reached
+    // applyCitationDecay, so they could neither promote nor demote.
+    accepts: ({ command, text }) =>
+      command.includes('post-tool-use') && text.includes('Related memories found for this error'),
+    collect: (text, add) => {
+      // Per-line anchored: match only a row that STARTS with `#NN [type]` (after its
+      // indent), NOT every such token in the block. The inlined lesson body (v3.16.x)
+      // can quote another obs id, which must not enter the injected set; the trailing
+      // `Use mem_get(ids=[...])` line (bare numbers) is excluded too.
+      for (const line of text.split('\n')) {
+        const m = INJECTED_ROW_RE.exec(line);
+        if (m) add(m[1]);
+      }
+    },
+  },
+  fyi: {
+    accepts: ({ command, text }) =>
+      command.includes('user-prompt-search') && text.includes(FYI_HEADER),
+    collect: (text, add) => {
+      for (const fyiLine of text.split('\n')) {
+        const m = FYI_LINE_ID_RE.exec(fyiLine);
+        if (m) add(m[1]);
+      }
+    },
+  },
+};
+
+// The query-conditioned faces, in citation_surface_log label order. keyctx is
+// absent on purpose: it has no hook attachment to walk.
+const ATTACHMENT_SURFACES = Object.keys(SURFACE_MATCHERS);
+
+/**
+ * Split a transcript's injections by FACE in ONE walk.
+ *
+ * This is the primitive; `extractAllInjected` is its union. Pre-v45 each face
+ * re-read and re-parsed the whole transcript (4 walks per Stop) AND the union
+ * was a separate list that had to be kept in sync by hand — this collapses both
+ * problems into the SURFACE_MATCHERS table.
  *
  * @param {string|null|undefined} transcriptPath
- * @returns {Set<number>}
+ * @param {{mainOnly?: boolean}} [opts]
+ * @returns {{pretool: Set<number>, ups: Set<number>, error_recall: Set<number>, fyi: Set<number>}}
+ *   Always all four keys, always Sets (empty on missing/unreadable transcript).
  */
-export function extractInjectedFromUserPromptSubmit(transcriptPath, opts = {}) {
-  const ids = new Set();
-  eachHookAttachment(transcriptPath, ({ command, text }) => {
-    if (!command.includes(UPS_COMMAND_SUFFIX)) return;
-    if (!text.includes('<memory-context')) return;
-    for (const memLine of text.split('\n')) {
-      if (!memLine.startsWith(UPS_LINE_PREFIX)) continue;
-      // Take the LAST (#NN) on the line — formatMemoryLine puts the obs id
-      // in trailing parens, possibly followed by ` [verify-before-use]`. Any
-      // earlier (#NN) refs are inside title/lesson text.
-      const matches = [...memLine.matchAll(UPS_ID_RE)];
-      if (matches.length === 0) continue;
-      addObsId(ids, matches[matches.length - 1][1]);
+export function extractInjectedBySurface(transcriptPath, opts = {}) {
+  const out = {};
+  for (const face of ATTACHMENT_SURFACES) out[face] = new Set();
+  eachHookAttachment(transcriptPath, (ctx) => {
+    for (const face of ATTACHMENT_SURFACES) {
+      const matcher = SURFACE_MATCHERS[face];
+      if (!matcher.accepts(ctx)) continue;
+      const target = out[face];
+      matcher.collect(ctx.text, (raw) => addObsId(target, raw));
     }
   }, opts);
-  return ids;
+  return out;
+}
+
+// Per-face extractors: thin wrappers over the shared table, kept as named
+// exports because callers and tests address individual faces.
+function extractOneSurface(face, transcriptPath, opts) {
+  return extractInjectedBySurface(transcriptPath, opts)[face];
 }
 
 /**
- * Extract observation IDs injected by the PostToolUse error-recall hint
- * (hook.mjs triggerErrorRecall → `[claude-mem-lite] Related memories found for
- * this error:` followed by `  #NN [type] title` lines, delivered via
- * post-tool-use.sh). This is a high-volume surface that NO extractor matched
- * before — error-recall'd obs accrued injection_count but never reached
- * applyCitationDecay, so they could neither promote nor demote.
- *
+ * Extract observation IDs injected by pre-tool-recall hook in this transcript.
+ * @param {string|null|undefined} transcriptPath
+ * @returns {Set<number>} unique injected IDs (empty set on missing path/file)
+ */
+export function extractInjectedFromPreToolUse(transcriptPath, opts = {}) {
+  return extractOneSurface('pretool', transcriptPath, opts);
+}
+
+/**
+ * Extract observation IDs injected by the UserPromptSubmit `<memory-context>`
+ * block (hook.mjs handleUserPrompt).
  * @param {string|null|undefined} transcriptPath
  * @returns {Set<number>}
  */
-export function extractInjectedFromErrorRecall(transcriptPath, opts = {}) {
-  const ids = new Set();
-  eachHookAttachment(transcriptPath, ({ command, text }) => {
-    if (!command.includes('post-tool-use')) return;
-    if (!text.includes('Related memories found for this error')) return;
-    // Per-line anchored: match only a row that STARTS with `#NN [type]` (after its
-    // indent), NOT every such token in the block. The inlined lesson body (v3.16.x)
-    // can quote another obs id, which must not enter the injected set; the trailing
-    // `Use mem_get(ids=[...])` line (bare numbers) is excluded too.
-    for (const line of text.split('\n')) {
-      const m = INJECTED_ROW_RE.exec(line);
-      if (m) addObsId(ids, m[1]);
-    }
-  }, opts);
-  return ids;
+export function extractInjectedFromUserPromptSubmit(transcriptPath, opts = {}) {
+  return extractOneSurface('ups', transcriptPath, opts);
 }
 
-// user-prompt-search.js formatResults emits `[mem] FYI — Related memories ...`
-// then one `#NN <icon> title` row per obs (raw stdout, line-leading id). Distinct
-// from the `<memory-context>` block (hook.mjs) — the two UPS injectors dedup obs
-// by id at inject time, so they carry DISJOINT obs sets; both must be extracted
-// or the FYI-carried (highest-importance keyContext) obs never reach decay.
-const FYI_HEADER = '[mem] FYI — Related memories';
-// Anchored at line start so `P#NN` past-question rows (user_prompts, different id
-// space) and any `#NN` inside lesson text are NOT matched.
-const FYI_LINE_ID_RE = /^#(\d{1,7})\s/;
+/**
+ * Extract observation IDs injected by the PostToolUse error-recall hint.
+ * @param {string|null|undefined} transcriptPath
+ * @returns {Set<number>}
+ */
+export function extractInjectedFromErrorRecall(transcriptPath, opts = {}) {
+  return extractOneSurface('error_recall', transcriptPath, opts);
+}
 
 /**
  * Extract observation IDs injected by the user-prompt-search.js `[mem] FYI —
  * Related memories` block.
- *
  * @param {string|null|undefined} transcriptPath
  * @returns {Set<number>}
  */
 export function extractInjectedFromFyi(transcriptPath, opts = {}) {
-  const ids = new Set();
-  eachHookAttachment(transcriptPath, ({ command, text }) => {
-    if (!command.includes('user-prompt-search')) return;
-    if (!text.includes(FYI_HEADER)) return;
-    for (const fyiLine of text.split('\n')) {
-      const m = FYI_LINE_ID_RE.exec(fyiLine);
-      if (m) addObsId(ids, m[1]);
-    }
-  }, opts);
-  return ids;
+  return extractOneSurface('fyi', transcriptPath, opts);
 }
 
 /**
@@ -409,12 +468,25 @@ export function extractInjectedFromKeyContext({ runtimeDir, project, sessionId =
  * @returns {Set<number>}
  */
 export function extractAllInjected(transcriptPath, opts = {}) {
-  return new Set([
-    ...extractInjectedFromPreToolUse(transcriptPath, opts),
-    ...extractInjectedFromUserPromptSubmit(transcriptPath, opts),
-    ...extractInjectedFromErrorRecall(transcriptPath, opts),
-    ...extractInjectedFromFyi(transcriptPath, opts),
-  ]);
+  return unionSurfaces(extractInjectedBySurface(transcriptPath, opts));
+}
+
+/**
+ * Flatten a per-face breakdown into the single injected set the decay loop
+ * takes. Derived — NOT a second hand-maintained face list — so adding a face to
+ * SURFACE_MATCHERS automatically widens the denominator (v45; the pre-v45 union
+ * enumerated the faces a second time and that is exactly how a face goes
+ * unmetered).
+ *
+ * @param {Record<string, Set<number>>} bySurface
+ * @returns {Set<number>}
+ */
+export function unionSurfaces(bySurface) {
+  const out = new Set();
+  for (const face of ATTACHMENT_SURFACES) {
+    for (const id of bySurface?.[face] || []) out.add(id);
+  }
+  return out;
 }
 
 /**
@@ -617,6 +689,47 @@ export function computeCitationAdoption(db, project) {
   } catch (e) { debugCatch(e, 'computeCitationAdoption'); return empty; }
 }
 
+/**
+ * D#61: a lesson injected live and then superseded mid-session (auto-dedup /
+ * `supersedes=` save) leaves its citation crediting NOBODY — every consumer
+ * excludes superseded rows by design, so the keeper that now carries the lesson
+ * goes uncredited. Redirect such ids to their NUMERIC superseded_by keeper (one
+ * hop; superseded_by is polymorphic — the typeof guard mirrors timeline-core).
+ *
+ * Returns a COPY: callers own their input sets. Shared by the per-obs decay loop
+ * and the per-surface funnel so the two can't disagree about who gets credit —
+ * the superseded invariant has been reopened once per surface that forgot it.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} project
+ * @param {Set<number>|Iterable<number>} ids
+ * @returns {Set<number>}
+ */
+export function redirectSupersededIds(db, project, ids) {
+  const src = ids instanceof Set ? ids : new Set(ids || []);
+  const out = new Set();
+  // Both bail-outs copy: returning `src` would hand back the CALLER'S own Set
+  // on the very paths that skip the redirect, quietly breaking the contract one
+  // line below this and making a future caller's mutation action-at-a-distance.
+  if (!db || !project) return new Set(src);
+  let stmt;
+  try {
+    stmt = db.prepare(
+      'SELECT superseded_by FROM observations WHERE id = ? AND project = ? AND superseded_at IS NOT NULL'
+    );
+  } catch (e) { debugCatch(e, 'redirectSupersededIds-prepare'); return new Set(src); }
+  for (const id of src) {
+    const r = stmt.get(id, project);
+    if (r && typeof r.superseded_by === 'number' && Number.isInteger(r.superseded_by)
+        && r.superseded_by > 0 && r.superseded_by !== id) {
+      out.add(r.superseded_by);
+    } else {
+      out.add(id);
+    }
+  }
+  return out;
+}
+
 /**
  * Apply the citation-feedback loop for one session: for each injected obs id,
  * decide cited vs uncited and mutate importance/streak/cited_count per spec.
@@ -657,31 +770,8 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   if (injected.size === 0) return empty;
   let cited = citedIds instanceof Set ? citedIds : new Set(citedIds || []);
 
-  // D#61: a lesson injected live and then superseded mid-session (auto-dedup /
-  // supersedes= save) leaves its citation crediting NOBODY — selectStmt below
-  // excludes superseded rows by design (defense-in-depth parity), so the keeper
-  // that now carries the lesson goes uncredited. Redirect such ids to their
-  // NUMERIC superseded_by keeper (one hop; superseded_by is polymorphic — the
-  // typeof guard mirrors timeline-core). Copies, not mutation: callers own the
-  // input sets.
-  const redirectStmt = db.prepare(
-    'SELECT superseded_by FROM observations WHERE id = ? AND project = ? AND superseded_at IS NOT NULL'
-  );
-  const redirectSet = (set) => {
-    const out = new Set();
-    for (const id of set) {
-      const r = redirectStmt.get(id, project);
-      if (r && typeof r.superseded_by === 'number' && Number.isInteger(r.superseded_by)
-          && r.superseded_by > 0 && r.superseded_by !== id) {
-        out.add(r.superseded_by);
-      } else {
-        out.add(id);
-      }
-    }
-    return out;
-  };
-  injected = redirectSet(injected);
-  cited = redirectSet(cited);
+  injected = redirectSupersededIds(db, project, injected);
+  cited = redirectSupersededIds(db, project, cited);
 
   // Adoption gate (snapshot taken before any mutation this run). Suppress only
   // demotion; promotion always proceeds. Threshold overridable via env.
@@ -840,6 +930,122 @@ export function recordCitationFunnel(db, project, sessionId, injectedDelta, cite
   } catch (e) { debugCatch(e, 'recordCitationFunnel'); }
 }
 
+/**
+ * v45 — persist this session's invocation→cite funnel split by INJECTION FACE.
+ *
+ * The aggregate twin (recordCitationFunnel) accumulates deltas because its
+ * source is applyCitationDecay's per-run return. This one OVERWRITES, because
+ * its source is the transcript, which only ever grows: recomputing after a Stop
+ * re-fire yields the same-or-larger sets, so overwrite is idempotent by
+ * construction AND lets a cross-turn late citation raise cited_n without
+ * double-counting injected_n. No per-obs state, no idempotency key needed.
+ *
+ * NOT A PARTITION, and NOT comparable to citation_log in either direction.
+ * Upward: an obs carried by two faces is counted in BOTH rows. Downward: the
+ * Stop handler unions cite-back signals into the aggregate denominator AFTER
+ * taking this breakdown, and those ids belong to no face (and skip the mainOnly
+ * filter), so citation_log can exceed the surface sum too. A per-face view
+ * answers "which face earns its budget", not "how was the budget divided".
+ *
+ * Ids are filtered to observations that actually exist in this project and are
+ * not superseded (redirected to their keeper first), mirroring the decay loop's
+ * SELECT — so a cross-project id, a deleted row, or an events-table id can't
+ * inflate a face's denominator.
+ *
+ * Telemetry only: every write is wrapped, and a failure here can never break the
+ * Stop handler.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} project
+ * @param {string} sessionId — the CLAUDE CODE session id, NOT the memory
+ *   session id citation_log uses. Overwrite semantics make the key choice
+ *   load-bearing: the memory session id is one file per PROJECT, so two
+ *   concurrent CC sessions in one project share it and the second Stop would
+ *   erase the first's counts. citation_log survives that only because it
+ *   accumulates. Same reasoning as D#60 for applyCitationDecay.
+ * @param {Record<string, Set<number>|Iterable<number>>} surfaceSets — keys must
+ *   be CITATION_SURFACES members; unknown labels are dropped, not written.
+ * @param {Set<number>|Iterable<number>} citedIds — this session's cited set
+ *   (same one the decay loop uses)
+ * @returns {Record<string, {injected: number, cited: number}>} what was written
+ */
+export function recordCitationSurfaces(db, project, sessionId, surfaceSets, citedIds) {
+  const written = {};
+  if (!db || !project || !sessionId || !surfaceSets || typeof surfaceSets !== 'object') return written;
+  try {
+    const cited = redirectSupersededIds(db, project, citedIds instanceof Set ? citedIds : new Set(citedIds || []));
+    const liveStmt = db.prepare(
+      'SELECT 1 AS ok FROM observations WHERE id = ? AND project = ? AND superseded_at IS NULL'
+    );
+    const upsert = db.prepare(`
+      INSERT INTO citation_surface_log (project, session_id, surface, resolved_at, injected_n, cited_n)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project, session_id, surface) DO UPDATE SET
+        injected_n = excluded.injected_n,
+        cited_n = excluded.cited_n,
+        resolved_at = excluded.resolved_at
+    `);
+    const now = Date.now();
+    const rows = [];
+    for (const [surface, rawIds] of Object.entries(surfaceSets)) {
+      if (!CITATION_SURFACES.includes(surface)) continue; // unknown label → unqueryable row
+      const ids = redirectSupersededIds(db, project, rawIds instanceof Set ? rawIds : new Set(rawIds || []));
+      let injected = 0, citedN = 0;
+      for (const id of ids) {
+        if (!liveStmt.get(id, project)) continue;
+        injected++;
+        if (cited.has(id)) citedN++;
+      }
+      if (injected === 0) continue; // empty face → no telemetry noise
+      rows.push([surface, injected, citedN]);
+      written[surface] = { injected, cited: citedN };
+    }
+    if (rows.length === 0) return written;
+    const txn = db.transaction(() => {
+      for (const [surface, injected, citedN] of rows) {
+        upsert.run(project, sessionId, surface, now, injected, citedN);
+      }
+    });
+    txn();
+  } catch (e) { debugCatch(e, 'recordCitationSurfaces'); }
+  return written;
+}
+
+/**
+ * v45 — read citation_surface_log back as a per-face cite-rate leaderboard for
+ * the window, highest injection volume first (the face spending the most budget
+ * is the one worth aiming a lever at).
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{days?: number, project?: string|null}} [opts]
+ * @returns {{window_days: number, surfaces: Array<{surface: string, injected: number, cited: number, rate: number, sessions: number}>}}
+ */
+export function computeSurfaceFunnel(db, { days = 7, project = null } = {}) {
+  const empty = { window_days: days, surfaces: [] };
+  if (!db) return empty;
+  try {
+    const windowStart = Date.now() - days * DAY_MS;
+    const params = project ? [windowStart, project] : [windowStart];
+    const rows = db.prepare(`
+      SELECT surface,
+             COALESCE(SUM(injected_n), 0)   AS injected,
+             COALESCE(SUM(cited_n), 0)      AS cited,
+             -- DISTINCT, not COUNT(*): rows are keyed (project, session,
+             -- surface), so an unfiltered COUNT(*) counts project-sessions and
+             -- over-reports "over N sessions" whenever a session spans projects.
+             COUNT(DISTINCT session_id)     AS sessions
+        FROM citation_surface_log
+       WHERE resolved_at >= ? ${project ? 'AND project = ?' : ''}
+    GROUP BY surface
+    ORDER BY injected DESC, surface ASC
+    `).all(...params);
+    return {
+      window_days: days,
+      surfaces: rows.map(r => ({ ...r, rate: r.injected > 0 ? r.cited / r.injected : 0 })),
+    };
+  } catch (e) { debugCatch(e, 'computeSurfaceFunnel'); return empty; }
+}
+
 /**
  * R1 — read the per-session invocation→cite funnel as a windowed trend.
  * `window` aggregates [now-days, now]; `prior` aggregates [now-2*days, now-days)

package/mem-cli.mjs

@@ -55,7 +55,18 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, parseDuration, coreRunSearchPipeline } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
-import { computeCitationFunnelTrend } from './lib/citation-tracker.mjs';
+import { computeCitationFunnelTrend, computeSurfaceFunnel } from './lib/citation-tracker.mjs';
+
+// Human labels for citation_surface_log.surface. Padded to a common width so
+// the citation-stats face table lines up; the enum itself lives in
+// lib/citation-tracker.mjs (CITATION_SURFACES).
+const SURFACE_LABELS = {
+  pretool:      'PreToolUse recall  ',
+  ups:          'UserPromptSubmit   ',
+  error_recall: 'error-recall       ',
+  fyi:          'FYI (prompt-search)',
+  keyctx:       'Key Context        ',
+};
 import { aggregateMetrics, readMetrics } from './lib/metrics.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
@@ -2524,6 +2535,8 @@ function cmdCitationStats(db, args) {
   // R1: per-session invocation→cite funnel trend (citation_log). Same `days` window
   // as the per-project cite rate above; funnel.prior/delta_pt show the direction.
   const funnel = computeCitationFunnelTrend(db, { days });
+  // v45: per-injection-face split of the same funnel (citation_surface_log).
+  const surfaceFunnel = computeSurfaceFunnel(db, { days });
 
   // Survivorship-honesty: the per-project rate (cited_count/decay_seen_count over
   // SURVIVING in-window obs) is doubly biased — GC drops uncited obs from the
@@ -2542,7 +2555,7 @@ function cmdCitationStats(db, args) {
   }
 
   if (json) {
-    out(JSON.stringify({ window_days: days, per_project: perProject, decay_queue: decayQueue, promoted, demoted, data_pollution_note: dataPollutionNote, funnel }, null, 2));
+    out(JSON.stringify({ window_days: days, per_project: perProject, decay_queue: decayQueue, promoted, demoted, data_pollution_note: dataPollutionNote, funnel, surface_funnel: surfaceFunnel }, null, 2));
     return;
   }
 
@@ -2577,6 +2590,25 @@ function cmdCitationStats(db, args) {
   }
   out(trendLine);
   out('');
+
+  // v45: the same funnel split by INJECTION FACE. The aggregate above says
+  // whether effectiveness is rising; this says WHICH face to aim a lever at.
+  out(`Cite rate by injection face (last ${days}d):`);
+  out('  a per-face VIEW, not a partition — do NOT reconcile against the funnel above: faces overlap (an obs carried by two counts in both) and the funnel also counts cite-back signals that belong to no face:');
+  if (surfaceFunnel.surfaces.length === 0) {
+    // Deliberately does NOT claim "no data yet": the reader swallows a query
+    // error, so an absent or unreadable citation_surface_log renders exactly
+    // like an empty one. Say what is true (nothing came back) and name the
+    // check, rather than assert the benign cause (pre-tag review b4).
+    out('  (nothing returned for this window — rows accrue at Stop; if this stays empty after a few sessions, check the table exists: claude-mem-lite fts-check)');
+  } else {
+    for (const s of surfaceFunnel.surfaces) {
+      const pct = (s.rate * 100).toFixed(1) + '%';
+      const note = s.surface === 'keyctx' ? '  (promotion-only: never demotes)' : '';
+      out(`  ${SURFACE_LABELS[s.surface] || s.surface}  inj ${String(s.injected).padStart(4)}  cited ${String(s.cited).padStart(4)}  ${pct.padStart(6)}  over ${s.sessions} session(s)${note}`);
+    }
+  }
+  out('');
   out('Active decay queue (uncited_streak >= 2, next miss → demote):');
   if (decayQueue.length === 0) out('  (none)');
   for (const r of decayQueue) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.66.1",
+  "version": "3.67.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.66.1",
+      "version": "3.67.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.66.1",
+  "version": "3.67.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/schema.mjs

@@ -129,7 +129,30 @@ export const CODE_DIR = join(homedir(), '.claude-mem-lite');
 // 2026-07-14 on this machine's own DB). One version per migration batch keeps
 // the version number itself the detector. LATEST_MIGRATION_COLUMN advances to
 // observations.scope.
-export const CURRENT_SCHEMA_VERSION = 44;
+// v45 (per-surface funnel): citation_surface_log — the same invocation→cite
+// funnel as citation_log (v38) but split by INJECTION FACE. citation_log answers
+// "is effectiveness rising or falling" for a project; it cannot answer "which
+// face is burning the budget", because hook.mjs unions all four
+// query-conditioned faces (pre-tool-recall / UserPromptSubmit <memory-context> /
+// PostToolUse error-recall / user-prompt-search FYI) before anything is
+// recorded. Without per-face cite-rate there is no evidence to aim any
+// precision lever at, which is what gated D#44 and D#129's remaining legs.
+// The two tables are NOT comparable in either direction and the readers say so
+// out loud: an obs carried by two faces is counted in both rows (pushes the
+// surface sum UP), while cite-back signals join citation_log's denominator
+// without belonging to any face and without the mainOnly filter (pushes the
+// aggregate UP). Neither is a partition of the other.
+// Keyed on the CC session id, NOT the memory session id — see the DDL comment.
+// The column was renamed memory_session_id -> session_id BEFORE v45 ever
+// shipped (pre-tag review), so no released database carries the old shape and
+// no rename migration exists; the sentinel stays on `surface`, which is a
+// table-presence check either way.
+// New TABLE (not a column) reached via CORE_SCHEMA's CREATE TABLE IF NOT EXISTS
+// on the forced migration pass. UNLIKE v38/v39 this DOES register a sentinel
+// (citation_surface_log.surface) in LATEST_MIGRATION_COLUMNS: a table that only
+// the forced pass can create is unreachable forever once the version row says
+// "done", which is not a hypothetical — see the note there.
+export const CURRENT_SCHEMA_VERSION = 45;
 
 // Sentinel columns for the LATEST migration set(s). The fast-path uses these
 // to self-heal half-migrated DBs — schema_version bumped but column ALTERs
@@ -139,7 +162,18 @@ export const CURRENT_SCHEMA_VERSION = 44;
 // table's pre-migration shape while the version row and the other table stay
 // current — a single sentinel can't see that hole, so every recent batch
 // keeps a representative column here until it is ancient enough to retire.
+// A new TABLE needs an entry here just as much as a new COLUMN does, and v38/v39
+// not having one is a latent hole, not a precedent: CORE_SCHEMA is reached ONLY
+// on the forced pass, so if anything stamps the version without running it (a
+// half-applied dev tree, an interrupted migration, a peer on a newer build), the
+// fast-path returns forever and the table can never appear. Observed live during
+// v45 development — the version bump and the CREATE landed in two edits, a hook
+// fired between them, and the DB sat at v45 with no citation_surface_log while
+// every reader silently swallowed "no such table" as "no data yet".
+// pragma_table_info on a missing table returns zero rows (it does not throw), so
+// naming any column of the new table is a table-presence check.
 const LATEST_MIGRATION_COLUMNS = [
+  { table: 'citation_surface_log', column: 'surface' },            // v45
   { table: 'observations', column: 'scope' },                      // v44
   { table: 'observation_files', column: 'last_cited_session_id' }, // v43
 ];
@@ -243,6 +277,34 @@ const CORE_SCHEMA = `
     PRIMARY KEY (project, memory_session_id)
   );
 
+  -- v45: per-INJECTION-FACE twin of citation_log. One row per
+  -- (project, session, surface); the surface column is one of the
+  -- CITATION_SURFACES enum in lib/citation-tracker.mjs
+  -- (pretool | ups | error_recall | fyi | keyctx).
+  --
+  -- session_id is the CLAUDE CODE session id, NOT the memory session id that
+  -- keys citation_log. The two tables therefore do NOT join, on purpose. The
+  -- memory session id lives in one file per PROJECT (hook-shared session-<project>,
+  -- 12h), so two concurrent CC sessions in one project share it -- which is
+  -- survivable for citation_log because that table ACCUMULATES deltas, and
+  -- destructive here because this one OVERWRITES: the second session's Stop
+  -- would erase the first's counts. Same reasoning that moved applyCitationDecay
+  -- onto the CC session id in D#60.
+  --
+  -- Overwrite (not accumulate) is correct for this table because its source --
+  -- ONE CC session's transcript -- only ever grows, so a Stop re-fire recomputes
+  -- the same-or-larger sets: idempotent by construction, and a cross-turn late
+  -- citation raises cited_n without touching injected_n.
+  CREATE TABLE IF NOT EXISTS citation_surface_log (
+    project TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    surface TEXT NOT NULL,
+    resolved_at INTEGER,
+    injected_n INTEGER NOT NULL DEFAULT 0,
+    cited_n INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (project, session_id, surface)
+  );
+
   CREATE TABLE IF NOT EXISTS migration_cleanups (
     name TEXT PRIMARY KEY,
     done_at_epoch INTEGER NOT NULL
@@ -904,11 +966,13 @@ const DEFERRED_CLEANUPS = [
             // Rename the short project to canonical on EVERY project-scoped table.
             // Originally only the first three were rewritten, so a short-named
             // project's deferred TODOs (deferred_work), activity (events), citation
-            // history (citation_log), and /clear-/exit handoffs (session_handoffs)
-            // were stranded on the old name — invisible to every project-scoped query
-            // after normalization. All seven carry a `project` column (verified).
+            // history (citation_log + v45 citation_surface_log), and /clear-/exit
+            // handoffs (session_handoffs) were stranded on the old name — invisible to
+            // every project-scoped query after normalization. All eight carry a
+            // `project` column (verified).
             for (const table of ['observations', 'sdk_sessions', 'session_summaries',
-                                 'session_handoffs', 'citation_log', 'events', 'deferred_work']) {
+                                 'session_handoffs', 'citation_log', 'citation_surface_log',
+                                 'events', 'deferred_work']) {
               db.prepare(`UPDATE ${table} SET project = ? WHERE project = ?`).run(canonical.project, shortName);
             }
           }