claude-mem-lite 3.64.0 → 3.66.0

package/hook-shared.mjs

@@ -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 } from './haiku-client.mjs';
+import { getClaudePath as getClaudePathShared, 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.
@@ -18,6 +18,7 @@ import { memdirPath as _memdirPath, isAdopted as _isAdoptedMemdir } from './memd
 import { isAdopted as _isAdoptedClaudeMd } from './claudemd.mjs';
 import { PLUGIN_SLUG as _PLUGIN_SLUG } from './adopt-content.mjs';
 
+import { DAY_MS } from './lib/time-constants.mjs';
 // ─── Constants ────────────────────────────────────────────────────────────────
 
 export const RUNTIME_DIR = join(DB_DIR, 'runtime');
@@ -30,8 +31,14 @@ export const SESSION_EXPIRY_MS = 12 * 60 * 60 * 1000;    // 12h
 export const STALE_SESSION_MS = 24 * 60 * 60 * 1000;     // 24h
 export const STALE_LOCK_MS = 30000;                       // 30s
 export const DEDUP_WINDOW_MS = 5 * 60 * 1000;            // 5 min (title dedup)
-export const RELATED_OBS_WINDOW_MS = 7 * 86400000;       // 7 days
+export const RELATED_OBS_WINDOW_MS = 7 * DAY_MS;       // 7 days
 export const FALLBACK_OBS_WINDOW_MS = RELATED_OBS_WINDOW_MS; // same window
+// Candidate rows the SessionStart Key Context surface considers (hook-context.mjs
+// keyObs; each of the two sections then renders at most 5). The user-prompt
+// exclude-set does NOT mirror this query — it reads the ids actually rendered
+// from the keyctx marker (D#123 review C-1: query-mirroring suppressed
+// <memory-context> injection on quiet/adopted projects where nothing renders).
+export const KEY_CONTEXT_LIMIT = 10;
 
 // Phase A (v2.31.3+): MEM_QUIET_HOOKS=1 drops descriptive hook/MCP-instruction
 // bodies (File Lessons / Key Context headers, MCP WHEN-TO-USE & decision rules,
@@ -117,6 +124,89 @@ export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE
   return count;
 }
 
+// ─── Per-project marker GC (P2-15) ───────────────────────────────────────────
+// RUNTIME_DIR had three sweeps and a hole. Per-SESSION files age out at 24h
+// (hook.mjs) and orphaned episode/read trackers at 1h/24h (above), but the
+// per-PROJECT markers — one file per project, written once, never revisited —
+// had no reclamation path at all. A live install on 2026-08-16 held 253 files,
+// 152 of them past 30 days, including entire families for test sandboxes
+// deleted months earlier (session-tmp--sdscc-e2e-*, cite-recall-scratchpad--
+// fixture-*) and a .skill-reco-cooldown-* family that nothing had ever swept.
+//
+// Deliberately a NAMED list rather than a wildcard: these markers share a shape
+// but not a meaning. The GC-able ones are caches — delete them and the next
+// session re-derives the state (or, for a cooldown, merely allows a suggestion
+// sooner). The preserved ones are records of a side effect already performed;
+// removing them re-arms it (.auto-adopt-* re-attempts a write into the user's
+// project CLAUDE.md, the migration sentinels re-run their one-time work), which
+// is a bad trade for the 13-45 bytes each occupies.
+export const STALE_PROJECT_MARKER_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+// Regenerated on demand; safe to lose at any time.
+export const GC_PROJECT_MARKER_PREFIXES = Object.freeze([
+  'session-',                 // project → memory-session-id pointer
+  'cite-recall-',             // last session's cite-recall snapshot (nudge input)
+  '.skill-cooldown-',         // suggestion throttle timestamp
+  '.skill-reco-cooldown-',    // recommendation throttle timestamp
+  // These two have NO writer and NO reader left in the tree (verified by grep,
+  // 2026-08-16) — they are version-keyed one-time markers from retired code
+  // paths (live dir holds `.mcp-dedup-v2.10`, `.residue-warned-v2.55`). Nothing
+  // recreates them, so sweeping them is a one-shot cleanup, not a policy.
+  '.mcp-dedup-',
+  '.residue-warned-',
+]);
+
+// Records of a completed side effect — never age out. `ep-`/`ep-flush-`/
+// `pending-`/`reads-` are absent from BOTH lists on purpose: the first holds
+// unflushed observations (data, not cache) and the rest already belong to
+// sweepOrphanEpisodeFiles on tighter cutoffs.
+export const GC_PRESERVED_MARKER_PREFIXES = Object.freeze([
+  '.auto-adopt-',
+  '.deferred-block-migrated-',
+  '.legacy-claude-md-cleaned-',
+]);
+
+/**
+ * Sweep per-project runtime markers older than `ageMs`. fs-only, best-effort,
+ * never throws. Returns the number of files removed.
+ *
+ * The two prefix lists are injectable ONLY so the precedence rule below can be
+ * exercised: with the shipped lists they are disjoint, which makes the
+ * preserved check redundant today and load-bearing the moment a future family
+ * nests inside a GC-able one. Production callers pass neither.
+ *
+ * @param {string} runtimeDir
+ * @param {{ageMs?: number, now?: number, gcPrefixes?: string[], preservedPrefixes?: string[]}} [opts]
+ * @returns {number}
+ */
+export function sweepStaleProjectMarkers(runtimeDir, {
+  ageMs = STALE_PROJECT_MARKER_AGE_MS,
+  now = Date.now(),
+  gcPrefixes = GC_PROJECT_MARKER_PREFIXES,
+  preservedPrefixes = GC_PRESERVED_MARKER_PREFIXES,
+  env = process.env,
+} = {}) {
+  // Kill switch (naming mirrors SKIP_COMPRESS / SKIP_OPTIMIZE / SKIP_SAVE_ENRICH):
+  // this is the only sweep that deletes files a user might want to inspect, so a
+  // released default that reclaims state needs a documented way back out.
+  if (env.CLAUDE_MEM_SKIP_MARKER_GC === '1') return 0;
+  let entries;
+  try { entries = readdirSync(runtimeDir); } catch { return 0; }
+  const cutoff = now - ageMs;
+  let count = 0;
+  for (const f of entries) {
+    // Preserved wins on any overlap, so a future prefix added to both lists
+    // fails safe (kept) instead of deleting a side-effect record.
+    if (preservedPrefixes.some((p) => f.startsWith(p))) continue;
+    if (!gcPrefixes.some((p) => f.startsWith(p))) continue;
+    const full = join(runtimeDir, f);
+    try {
+      if (statSync(full).mtimeMs < cutoff) { unlinkSync(full); count++; }
+    } catch { /* concurrent unlink / permission / directory — ignore */ }
+  }
+  return count;
+}
+
 // Ensure runtime directory exists AND is owner-only (0700), matching the DB dir
 // (schema.mjs). Runtime aux files carry captured file paths + scrubbed activity; on a
 // shared host a 0755 dir would let another local user read them. hardenRuntimeFiles()
@@ -189,7 +279,7 @@ export function openDb() {
 // response string (callers run parseJsonFromLLM themselves) or null.
 // maxTokens is sized for session-summary / episode JSON (larger than the
 // registry/optimize callers' budgets).
-export async function callLLM(prompt, timeoutMs = 15000) {
+export async function callLLM(prompt, timeoutMs = BG_LLM_TIMEOUT_MS) {
   if (detectLLMMode() !== 'cli') {
     const result = await callHaiku(prompt, { timeout: timeoutMs, maxTokens: 2000 });
     return result?.text ?? null;
@@ -197,11 +287,13 @@ export async function callLLM(prompt, timeoutMs = 15000) {
 
   const { cli: modelName } = resolveModelShared();
   try {
-    const result = execFileSync(getClaudePathShared(), ['-p', '--model', modelName], {
+    // 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' },
+      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
     });

package/hook.mjs

@@ -42,7 +42,7 @@ import {
   SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS,
   HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT,
   sessionFile, getSessionId, createSessionId, openDb,
-  spawnBackground, sweepOrphanEpisodeFiles,
+  spawnBackground, sweepOrphanEpisodeFiles, sweepStaleProjectMarkers,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation, saveEpisodeImmediate } from './hook-llm.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
@@ -68,7 +68,8 @@ import { formatTaskImperative } from './lib/task-imperative.mjs';
 import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs';
 import { gcOldMetricShards, recordMetric } from './lib/metrics.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
-import { injectedIdsFileName } from './lib/injected-ids.mjs';
+import { injectedIdsFileName, keyContextIdsFileName } from './lib/injected-ids.mjs';
+import { recordKeyContextInjection } from './lib/keyctx-marker.mjs';
 import { liveObsFilterSql, recencyDecaySql } from './lib/inject-search-core.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-update.mjs';
@@ -90,6 +91,7 @@ async function loadCacheGuard() {
 import { SKIP_TOOLS, SKIP_PREFIXES } from './skip-tools.mjs';
 import { getVocabulary } from './tfidf.mjs';
 
+import { DAY_MS } from './lib/time-constants.mjs';
 // Prevent recursive hooks from background claude -p calls
 // Background workers (llm-episode, llm-summary) are exempt — they're ours
 const event = process.argv[2];
@@ -738,7 +740,12 @@ 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 });
+            // runtimeDir + project enable the 5th (Key Context) face — see
+            // extractInjectedFromKeyContext: it is marker-derived, because the
+            // SessionStart block leaves no hook attachment to parse.
+            const injected = extractAllInjected(transcriptPath, {
+              mainOnly: true, runtimeDir: RUNTIME_DIR, project, sessionId: ccSessionId,
+            });
             // 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
@@ -869,7 +876,8 @@ function gcStalePreRecallCooldowns() {
       // D#120: the injected-ids marker is also per-session now — same growth
       // shape as the cooldown files, same 24h GC (dedup window is 5 min).
       const isCooldown = name.startsWith('pre-recall-cooldown-') && name.endsWith('.json');
-      const isInjectedMarker = name.startsWith('.claude-mem-injected-');
+      const isInjectedMarker = name.startsWith('.claude-mem-injected-')
+        || name.startsWith('.claude-mem-keyctx-'); // D#123 Key Context marker — same per-session growth, same 24h GC
       if (!isCooldown && !isInjectedMarker) continue;
       try {
         const p = join(RUNTIME_DIR, name);
@@ -889,7 +897,7 @@ function gcStalePreRecallCooldowns() {
 function runSessionStartDbMutations(db, { sessionId, project, prevSessionId, now }) {
   // ── DB mutations in a transaction (crash-safe consistency) ──
   const staleSessionCutoff = Date.now() - STALE_SESSION_MS;
-  const autoCompressAge = Date.now() - 30 * 86400000; // 30 days (accelerated from 90)
+  const autoCompressAge = Date.now() - 30 * DAY_MS; // 30 days (accelerated from 90)
 
   db.transaction(() => {
     // Ensure session exists in DB (INSERT OR IGNORE avoids race condition)
@@ -944,7 +952,7 @@ function runSessionStartDbMutations(db, { sessionId, project, prevSessionId, now
     // imp=1 on these already; this just shrinks the GC latency so the
     // projected 32.5% corpus reduction materializes within a week on live
     // DBs instead of bleeding into the 30-day tier.
-    const noiseCompressAge = Date.now() - 7 * 86400000;
+    const noiseCompressAge = Date.now() - 7 * DAY_MS;
     const noiseCompressed = db.prepare(`
       UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}
       WHERE COALESCE(compressed_into, 0) = 0
@@ -974,7 +982,7 @@ function runSessionStartAutoMaintain(db) {
   } catch {}
   if (shouldMaintain) {
     try {
-      const STALE_AGE = Date.now() - 30 * 86400000;
+      const STALE_AGE = Date.now() - 30 * DAY_MS;
       const OP_CAP = 500;
       // Shared maintenance context (whole-DB, cap 500) — used by every maintain-core
       // op below AND the MED-2 snapshot guard. injection_count>0 protection lives in
@@ -994,7 +1002,7 @@ function runSessionStartAutoMaintain(db) {
       // children (compressed_into dangling at a deleted id). purgeStale recovers them
       // first and caps at opCap. Schema has no marked_at_epoch, so retention anchors on
       // created_at_epoch: 30d marking gate + 7d grace = 37d.
-      const purged = purgeStale(db, mctx, Date.now() - 37 * 86400000);
+      const purged = purgeStale(db, mctx, Date.now() - 37 * DAY_MS);
       if (purged > 0) debugLog('DEBUG', 'auto-maintain', `purged ${purged} stale observations`);
 
       const cleaned = cleanupBroken(db, mctx);
@@ -1108,7 +1116,7 @@ function runSessionStartAutoMaintain(db) {
           DELETE FROM session_handoffs
           WHERE (type = 'clear' AND created_at_epoch < ?)
              OR (type != 'clear' AND created_at_epoch < ?)
-        `).run(Date.now() - HANDOFF_EXPIRY_CLEAR - 86400000, Date.now() - HANDOFF_EXPIRY_EXIT - 86400000);
+        `).run(Date.now() - HANDOFF_EXPIRY_CLEAR - DAY_MS, Date.now() - HANDOFF_EXPIRY_EXIT - DAY_MS);
         if (gc.changes > 0) debugLog('DEBUG', 'auto-maintain', `gc'd ${gc.changes} expired session_handoffs`);
       } catch (e) { debugCatch(e, 'auto-maintain-handoff-gc'); }
 
@@ -1348,6 +1356,10 @@ async function handleSessionStart() {
   // GC stale per-session cooldown files. Cheap (<5ms typical) and idempotent;
   // moved here from pre-tool-recall.js's hot path.
   gcStalePreRecallCooldowns();
+  // P2-15: the per-PROJECT half of the same problem — markers written once per
+  // project and never revisited (session-/cite-recall-/skill cooldowns). Same
+  // SessionStart cadence, 30d gate, named family list (hook-shared.mjs).
+  try { sweepStaleProjectMarkers(RUNTIME_DIR); } catch { /* best-effort */ }
   // Bound the shadow-recommendation log (daily JSONL shards, no GC at write time).
   try { gcOldShadowShards(); } catch { /* best-effort, never blocks SessionStart */ }
   // Same for the opt-in metrics sink (RUNTIME_DIR's parent is DB_DIR). Runs even when
@@ -1471,13 +1483,31 @@ async function handleSessionStart() {
     // token-budgeted observation pool directly from the DB.
     // Pass CC session id so the Working State block is scoped to this session,
     // preventing parallel sessions from seeing each other's /clear handoff.
-    const fullContext = buildSessionContextLines(db, project, now, ccSessionId);
+    const contextCollector = {};
+    const fullContext = buildSessionContextLines(db, project, now, ccSessionId, contextCollector);
 
     // Stdout is the sole context-delivery channel. The SessionStart hook output
     // is injected as a <system-reminder> at session start, giving Claude the
     // full summary + handoff state + observations table fresh from the DB.
     process.stdout.write(`<claude-mem-context>\n${fullContext}\n</claude-mem-context>\n`);
 
+    // D#123 (review C-1): persist the Key Context ids ACTUALLY rendered above so
+    // handleUserPrompt can exclude exactly those from <memory-context> — and
+    // nothing else. Under quiet/adopted the sections don't render, the id list is
+    // empty, and prompt-time injection is NOT suppressed (the old query-mirroring
+    // exclude-set blanked the same-project leg on adopted projects). Written
+    // unconditionally (even when empty) so a resumed session can't act on a
+    // previous session's stale marker semantics; 24h GC below.
+    // D#124: the same call also bumps injection_count on the rendered rows —
+    // Key Context was a shown-but-uncounted surface, so its rows could never
+    // reach applyCitationDecay's denominator. One recorder, both writers.
+    recordKeyContextInjection(db, {
+      runtimeDir: RUNTIME_DIR,
+      project,
+      sessionId: ccSessionId,
+      ids: contextCollector.keyContextIds || [],
+    });
+
     // One-time migration: remove any stale <claude-mem-context> block left in
     // CLAUDE.md by pre-v2.30 installs. Idempotent no-op afterwards.
     cleanupClaudeMdLegacyBlock();
@@ -1651,13 +1681,21 @@ async function handleUserPrompt() {
     // (mirrors CC built-in memoryTypes.ts:215). Skip both Key Context lookup
     // and the <memory-context> emission for this turn.
     if (!detectMemOverride(promptText)) try {
-      const keyObs = db.prepare(`
-        SELECT id FROM observations
-        WHERE project = ? AND COALESCE(compressed_into, 0) = 0
-          AND COALESCE(importance, 1) >= 2
-        ORDER BY created_at_epoch DESC LIMIT 5
-      `).all(project);
-      const keyContextIds = keyObs.map(o => o.id);
+      // D#123 (review C-1): the exclude-set is the Key Context ids ACTUALLY
+      // rendered at SessionStart — read from the marker handleSessionStart wrote,
+      // not re-derived from a query. The old query-mirroring set excluded rows
+      // that were never shown (quiet/adopted projects render no Key Context at
+      // all), blanking the same-project <memory-context> leg outright. Missing
+      // or other-session marker → empty set: unknown injections must fail open
+      // (inject, maybe duplicate) rather than fail closed (suppress).
+      const keyContextIds = [];
+      try {
+        const raw = readFileSync(join(RUNTIME_DIR, keyContextIdsFileName(project, ccSessionId)), 'utf8');
+        const { ids, session } = JSON.parse(raw);
+        if (Array.isArray(ids) && !(session && ccSessionId && session !== ccSessionId)) {
+          keyContextIds.push(...ids);
+        }
+      } catch { /* no marker — nothing was injected, exclude nothing */ }
       const pathAInjectedIds = [];
 
       // Read IDs already injected by user-prompt-search.js to avoid duplicate injection
@@ -1686,8 +1724,9 @@ async function handleUserPrompt() {
       const taskImperativeOn = process.env.CLAUDE_MEM_TASK_IMPERATIVE === 'on'
         || process.env.CLAUDE_MEM_TASK_IMPERATIVE === '1';
       // Exclude only ids path-A (user-prompt-search.js) already injected — NOT the
-      // key-context top-5, which overlaps the high-value lesson pool and would suppress
-      // the pick. The chosen id is excluded from the <memory-context> block below instead.
+      // SessionStart Key Context set, which overlaps the high-value lesson pool and
+      // would suppress the pick. The chosen id is excluded from the <memory-context>
+      // block below instead.
       const imperativePick = taskImperativeOn
         ? selectImperativeLesson(db, promptText, project, pathAInjectedIds)
         : null;
@@ -1772,7 +1811,7 @@ function handleAutoCompress() {
   if (!db) return;
 
   try {
-    const compressCutoff = Date.now() - 60 * 86400000; // 60 days
+    const compressCutoff = Date.now() - 60 * DAY_MS; // 60 days
     const compressCandidates = selectCompressionCandidates(db, { cutoff: compressCutoff, includeAutoMarked: true });
     if (compressCandidates.length < 3) return;
 

package/lib/citation-tracker.mjs

@@ -13,7 +13,9 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
 import { debugCatch } from '../utils.mjs';
+import { keyContextIdsFileName } from './injected-ids.mjs';
 
+import { DAY_MS } from './time-constants.mjs';
 // `#123` / `#45678` at a word boundary — matches the CLAUDE.md cite pattern.
 // Bounded to 1-7 digits to skip URL fragments, markdown anchors, etc.
 const CITATION_RE = /#(\d{1,7})\b/g;
@@ -342,16 +344,55 @@ export function extractInjectedFromFyi(transcriptPath, opts = {}) {
   return ids;
 }
 
+/**
+ * Extract observation IDs rendered into the SessionStart / PreCompact
+ * `<claude-mem-context>` File Lessons + Key Context sections (D#124).
+ *
+ * The odd one out among the extractors: this surface leaves no hook attachment
+ * in the transcript — the block is written straight to stdout at SessionStart —
+ * so there is nothing to parse. It reads the per-session marker instead, the
+ * same file handleUserPrompt uses as its exclude-set, which by construction
+ * lists what was ACTUALLY rendered (empty on quiet/adopted projects where the
+ * sections never appear).
+ *
+ * Session-gated: a marker whose recorded session differs from the caller's is
+ * another window's render and must not enter this session's denominator. No
+ * coordinates → empty set, so transcript-only callers keep their old behaviour.
+ *
+ * @param {object} [ctx]
+ * @param {string} [ctx.runtimeDir]
+ * @param {string} [ctx.project]
+ * @param {string|null} [ctx.sessionId]
+ * @returns {Set<number>}
+ */
+export function extractInjectedFromKeyContext({ runtimeDir, project, sessionId = null } = {}) {
+  const ids = new Set();
+  if (!runtimeDir || !project) return ids;
+  try {
+    const raw = readFileSync(join(runtimeDir, keyContextIdsFileName(project, sessionId)), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (sessionId && parsed?.session && parsed.session !== sessionId) return ids;
+    for (const id of Array.isArray(parsed?.ids) ? parsed.ids : []) addObsId(ids, id);
+  } catch { /* no marker / torn write → nothing was rendered, fail open */ }
+  return ids;
+}
+
 /**
  * Union of every injection surface's IDs for a transcript: pre-tool-recall +
  * UserPromptSubmit `<memory-context>` + PostToolUse error-recall + the
- * user-prompt-search FYI block. Single integration point the Stop handler calls.
+ * user-prompt-search FYI block + the SessionStart Key Context block. Single
+ * integration point the Stop handler calls.
  *
  * @param {string|null|undefined} transcriptPath
  * @param {object} [opts]
  * @param {boolean} [opts.mainOnly=false] Skip sidechain-injected IDs. The
  *   citation-decay caller passes true so the injected denominator matches the
  *   mainOnly cited numerator; the P4 access-bump caller omits it (broader).
+ * @param {string} [opts.runtimeDir] With `project`, enables the Key Context
+ *   face. Omitted by callers that only have a transcript path (computeCiteRecall
+ *   over an arbitrary file), which then see the four transcript-derived faces.
+ * @param {string} [opts.project]
+ * @param {string|null} [opts.sessionId]
  * @returns {Set<number>}
  */
 export function extractAllInjected(transcriptPath, opts = {}) {
@@ -360,6 +401,9 @@ export function extractAllInjected(transcriptPath, opts = {}) {
     ...extractInjectedFromUserPromptSubmit(transcriptPath, opts),
     ...extractInjectedFromErrorRecall(transcriptPath, opts),
     ...extractInjectedFromFyi(transcriptPath, opts),
+    // Marker-derived, not transcript-derived: no-op unless the caller passes
+    // runtimeDir + project (see extractInjectedFromKeyContext).
+    ...extractInjectedFromKeyContext(opts),
   ]);
 }
 
@@ -808,8 +852,8 @@ export function computeCitationFunnelTrend(db, { days = 7, limit = 10, project =
   if (!db) return empty;
   try {
     const now = Date.now();
-    const windowStart = now - days * 86400000;
-    const priorStart = now - 2 * days * 86400000;
+    const windowStart = now - days * DAY_MS;
+    const priorStart = now - 2 * days * DAY_MS;
     const projClause = project ? 'AND project = ?' : '';
 
     const sessions = db.prepare(`

package/lib/db-backup.mjs

@@ -11,6 +11,7 @@ import { readdirSync, unlinkSync, statSync } from 'fs';
 import { dirname, basename, join } from 'path';
 import { debugLog } from '../utils.mjs';
 
+import { DAY_MS } from './time-constants.mjs';
 // M-9 (audit 2026-08-14): per-tag retention alone let one-shot tags live forever —
 // each tag kept its newest 3, but a tag written once (pre-backfill-v3390 and four
 // siblings) never got a second snapshot to age it out, so 9 orphaned .bak files held
@@ -35,7 +36,7 @@ export function backupBudgetBytes() {
 // a per-tag exemption would make every one-shot tag's only snapshot immortal —
 // exactly the 360MB orphan shape M-9 exists to evict. Mirrors the purge grace
 // convention (7d) used by stale-observation retention.
-export const BACKUP_EVICTION_GRACE_MS = 7 * 86400000;
+export const BACKUP_EVICTION_GRACE_MS = 7 * DAY_MS;
 
 // Canonical snapshot shape `<base>.<tag>-<ISO stamp>-<pid>-<seq>.bak` (what
 // snapshotDb writes). Budget eviction deletes ONLY names matching this — a

package/lib/deferred-work.mjs

@@ -1,3 +1,4 @@
+import { DAY_MS } from './time-constants.mjs';
 // claude-mem-lite — deferred_work data layer
 // Pure-data CRUD + ordinal resolver + transactional closure helper.
 // Decoupled from observations table: different lifecycle, different scoring.
@@ -60,7 +61,6 @@ export function listOpenWithOrdinal(db, project, limit = 10) {
 
 // ─── G11: list age + stale refresh hint (roadmap 2026-07-18) ─────────────────
 
-const DAY_MS = 86_400_000;
 // Internal const (was exported at v3.51.0 birth with zero external importers —
 // knip-baseline discipline: un-export rather than grow the unused-exports list).
 const DEFER_STALE_DAYS = 30;

package/lib/err-sampler.mjs

@@ -19,8 +19,8 @@ import { appendFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSyn
 import { join } from 'path';
 import { scrubSecrets } from '../secret-scrub.mjs';
 
-const DAY_MS = 86400000;
 
+import { DAY_MS } from './time-constants.mjs';
 function today() {
   // UTC date string; sharding daily keeps files bounded even at high sample rates.
   return new Date(Date.now()).toISOString().slice(0, 10);

package/lib/hook-telemetry.mjs

@@ -26,7 +26,7 @@ import { join } from 'path';
 import { isNativeBindingError } from './binding-probe.mjs';
 import { recordNativeBindingBreakage } from './native-binding-hint.mjs';
 
-const DAY_MS = 86400000;
+import { DAY_MS } from './time-constants.mjs';
 const RETENTION_MS = 14 * DAY_MS;
 const HOOK_ERRORS_SUBDIR = 'hook-errors';
 

package/lib/inject-search-core.mjs

@@ -1,10 +1,13 @@
-// lib/inject-search-core.mjs — the injection-side shared core (P2-11, audit
-// 2026-08-14). Shared home for the three SQL atoms that kept drifting across
-// hand-copied twins on the INJECTION-side retrieval surfaces (the five consumer
-// files the ledger test enforces — NOT yet the whole read surface: recall-core /
-// recent-core / timeline-core / hook-context / hook-handoff / hook-optimize /
-// deep-search / stats and the sessions/events decay arms in lib/search-core
-// still inline their own copies; extending them is the deferred second cut):
+// lib/inject-search-core.mjs — the retrieval-side shared core (P2-11, audit
+// 2026-08-14; second cut D#123, 2026-08-16). Shared home for the three SQL
+// atoms that kept drifting across hand-copied twins — first on the five
+// injection-side surfaces, then extended across the remaining read surfaces
+// (hook-context / hook-handoff / hook-optimize / mem-cli / search-scoring /
+// tfidf / deep-search / recall-core / recent-core / timeline-core / stats-core /
+// search-core incl. its sessions+events decay arms / maintain-core; the ledger
+// test enforces the full list). Deliberate compressed-only singles (maintain
+// UPDATE guards, stats noise-gauge counts, export tombstone toggles, session-own
+// history) stay inline — see the ledger test's non-member notes:
 //
 //   * live-row filter        — the compressed+superseded pair whose omission was
 //                              the superseded-invariant's recurring reopening
@@ -17,12 +20,12 @@
 //                              behavior factors (audit M-3: wired on every auto
 //                              surface, missing from the explicit-surface score)
 //
-// Consumers: scripts/user-prompt-search.js, scripts/pre-tool-recall.js,
-// hook-memory.mjs, hook.mjs (error-recall), search-engine.mjs. Each surface keeps
-// its own deliberate pipeline composition (BM25-sort + JS scoring vs SQL full
-// chain vs file-keyed sort — see #8786: per-surface asymmetries stay explicit);
-// only the ATOMS are shared. tests/inject-search-core.test.mjs holds the ledger:
-// the five consumer files must compose these builders, never re-inline copies.
+// Each surface keeps its own deliberate pipeline composition (BM25-sort + JS
+// scoring vs SQL full chain vs file-keyed sort — see #8786: per-surface
+// asymmetries stay explicit); only the ATOMS are shared.
+// tests/inject-search-core.test.mjs holds the ledger: consumer files must
+// compose these builders, never re-inline copies (and the decay shape may not
+// be hand-rolled anywhere, benchmark included).
 //
 // Lives under lib/ (not scripts/) so hook.mjs can statically import it without
 // colliding with the installExtractedRelease scripts-dir rename (same constraint

package/lib/injected-ids.mjs

@@ -27,3 +27,23 @@ export function injectedIdsFileName(project, sessionId) {
   const safe = String(sessionId).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
   return `${base}-${safe}`;
 }
+
+/**
+ * Runtime-dir FILE NAME for the SessionStart Key Context marker: the obs ids
+ * ACTUALLY rendered into the <claude-mem-context> File Lessons / Key Context
+ * sections (empty under quiet/adopted). handleUserPrompt reads it as its
+ * exclude-set — D#123 review C-1: excluding the injector's QUERY result instead
+ * of what was really shown suppressed <memory-context> injection outright on
+ * quiet/adopted projects, where Key Context never renders at all.
+ * Session-lifetime validity (no time window): the SessionStart block stays in
+ * context for the whole session. Swept with the same 24h GC as the marker above.
+ * @param {string} project - inferProject() value (already filename-safe)
+ * @param {string} [sessionId] - CC session id
+ * @returns {string}
+ */
+export function keyContextIdsFileName(project, sessionId) {
+  const base = `.claude-mem-keyctx-${project}`;
+  if (!sessionId) return base;
+  const safe = String(sessionId).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
+  return `${base}-${safe}`;
+}

package/lib/keyctx-marker.mjs

@@ -0,0 +1,71 @@
+// lib/keyctx-marker.mjs — the one place the SessionStart Key Context render is
+// recorded. Two things happen together because they must describe the SAME set:
+//
+//   ① the per-session marker file (D#123 review C-1): the obs ids ACTUALLY
+//      rendered into <claude-mem-context>, which handleUserPrompt reads as its
+//      exclude-set. Written even when empty, so a resumed session can never act
+//      on a previous session's stale semantics.
+//   ② injection_count / last_injected_at on those same rows (D#124): before
+//      this, Key Context was a shown-but-uncounted surface — up to 10 rows per
+//      session that could accrue no denominator and therefore never promote or
+//      demote through applyCitationDecay.
+//
+// handleSessionStart (hook.mjs) and handlePreCompact (hook-precompact.mjs) both
+// render the block, so both call this. Keeping the pair in one function is the
+// point: the CLI/MCP and SessionStart/PreCompact twin pairs in this repo have
+// drifted often enough that "two callers, one body" is the standing rule.
+//
+// Never throws: a marker-write failure must not break context delivery, and it
+// must not cost the metering either — the bump runs first.
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { debugCatch } from '../utils.mjs';
+import { keyContextIdsFileName } from './injected-ids.mjs';
+
+/**
+ * Record one Key Context render: bump the rendered rows, then persist the id
+ * list for the prompt-time exclude-set and the citation extractor.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {object} ctx
+ * @param {string} ctx.runtimeDir  RUNTIME_DIR of the caller
+ * @param {string} ctx.project     inferProject() value (filename-safe)
+ * @param {string|null} [ctx.sessionId] CC session id
+ * @param {number[]} [ctx.ids]     obs ids ACTUALLY rendered (empty on quiet projects)
+ * @returns {{bumped: number, written: boolean}}
+ */
+export function recordKeyContextInjection(db, { runtimeDir, project, sessionId = null, ids = [] } = {}) {
+  const clean = [];
+  for (const raw of Array.isArray(ids) ? ids : []) {
+    const id = Number(raw);
+    if (Number.isInteger(id) && id > 0 && id < 1e7) clean.push(id);
+  }
+
+  let bumped = 0;
+  if (db && clean.length > 0) {
+    try {
+      const now = Date.now();
+      // Mirrors hook-memory.mjs's UPS bump verbatim so the two surfaces feed the
+      // same counter with the same semantics. Per-row try/catch for FTS trigger
+      // safety (project_non_obvious.md).
+      const stmt = db.prepare(
+        'UPDATE observations SET injection_count = COALESCE(injection_count, 0) + 1, last_injected_at = ? WHERE id = ?'
+      );
+      for (const id of clean) {
+        try { stmt.run(now, id); bumped++; } catch { /* single-row failure must not drop the rest */ }
+      }
+    } catch (e) { debugCatch(e, 'keyctx-bump'); }
+  }
+
+  let written = false;
+  try {
+    writeFileSync(
+      join(runtimeDir, keyContextIdsFileName(project, sessionId)),
+      JSON.stringify({ ids: clean, ts: Date.now(), session: sessionId || null }),
+    );
+    written = true;
+  } catch (e) { debugCatch(e, 'keyctx-marker-write'); }
+
+  return { bumped, written };
+}