recallnest 2.5.4 → 2.6.1

package/src/recall-gate.ts

@@ -0,0 +1,305 @@
+/**
+ * Recall gate — pre-retrieval triage for auto-recall traffic.
+ *
+ * Borrowed from memory-lancedb-pro's adaptive-retrieval, reshaped per Codex
+ * review (2026-07-17) into a three-way verdict instead of a binary SKIP/FORCE:
+ *
+ *   - "full-recall":  message explicitly reaches for memory ("记得/上次/my
+ *                     preference") — always run resume + focused search.
+ *   - "resume-only":  bare continuity nudges ("继续", "下一步", "开始吧") —
+ *                     they need checkpoint/continuity, not an embedding search
+ *                     over their own two characters.
+ *   - "skip-all":     greetings, slash commands, heartbeats, whole-message
+ *                     acks, pure emoji, bare CLI invocations — no memory value.
+ *   - "pass":         no rule matched — default full pipeline.
+ *
+ * Rollout is governed by RECALLNEST_RECALL_GATE (observe-before-enforce,
+ * shared-behaviors §5): "observe" (default) computes the verdict and appends a
+ * shadow-log line but never changes behavior; "enforce" acts on the verdict;
+ * "off" disables even the shadow logging. Shadow entries carry rule id,
+ * message length, and decision — never the message text itself.
+ */
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { dataDir } from "./env-config.js";
+
+export type RecallGateDecision = "full-recall" | "resume-only" | "skip-all" | "pass";
+
+export interface RecallGateResult {
+  decision: RecallGateDecision;
+  /** Stable rule identifier, e.g. "force:memory-cue", "skip:ack", "pass:long". */
+  ruleId: string;
+}
+
+export type RecallGateMode = "observe" | "enforce" | "off";
+
+/** RECALLNEST_RECALL_GATE: unset/invalid → "observe" (shadow-only default). */
+export function resolveRecallGateMode(env: NodeJS.ProcessEnv = process.env): RecallGateMode {
+  const raw = (env.RECALLNEST_RECALL_GATE || "").trim().toLowerCase();
+  if (raw === "enforce") return "enforce";
+  if (raw === "off") return "off";
+  return "observe";
+}
+
+// Short-text rules below only ever fire on messages up to this length; longer
+// messages carry enough content to always deserve the full pipeline.
+const SHORT_TEXT_MAX_CHARS = 80;
+
+// --- full-recall cues (substring, any position, force-first per review) ---
+
+const FORCE_CUES_ZH = [
+  "记得",
+  "回忆",
+  "想起",
+  "上次",
+  "上回",
+  "之前讨论",
+  "之前说",
+  "之前聊",
+  "之前提",
+  "我的偏好",
+  "我说过",
+  "你说过",
+  "说过吗",
+  "存过",
+  "记过",
+  "提醒过",
+];
+
+// Word-bounded and hyphen/underscore-guarded: "recall" must not fire on
+// "auto-recall" or "recall-gate.test.ts" (identifiers, not memory intent).
+const FORCE_CUES_EN = [
+  /(?<![\w-])remember(?![\w-])/,
+  /(?<![\w-])recall(?![\w-])/,
+  /(?<![\w-])last time(?![\w-])/,
+  /(?<![\w-])previously(?![\w-])/,
+  /(?<![\w-])we discussed(?![\w-])/,
+  /(?<![\w-])my preferences?(?![\w-])/,
+  /(?<![\w-])you said(?![\w-])/,
+  /(?<![\w-])i told you(?![\w-])/,
+];
+
+// --- resume-only: whole-message continuity nudges ---
+
+// Matched against the whole message after trailing particles/punctuation are
+// stripped, so "继续吧" hits but "继续讨论刚才的方案" (real content) passes.
+const RESUME_PHRASES = new Set([
+  "继续",
+  "接着",
+  "接着来",
+  "接着做",
+  "接着干",
+  "接着说",
+  "继续做",
+  "继续干",
+  "下一步",
+  "开始",
+  "开工",
+  "走起",
+  "往下",
+  "往下走",
+  "continue",
+  "go on",
+  "next",
+  "next step",
+  "resume",
+  "keep going",
+  "carry on",
+  "proceed",
+  "pick up where we left off",
+]);
+
+// --- skip-all: whole-message greetings & acks ---
+
+const GREETINGS = new Set([
+  "你好",
+  "您好",
+  "哈喽",
+  "嗨",
+  "早",
+  "早上好",
+  "早安",
+  "中午好",
+  "下午好",
+  "晚上好",
+  "晚安",
+  "在吗",
+  "在不在",
+  "在么",
+  "hi",
+  "hello",
+  "hey",
+  "yo",
+  "good morning",
+  "good night",
+  "good evening",
+  "morning",
+  "gm",
+  "gn",
+]);
+
+const ACK_WORDS = new Set([
+  "好的",
+  "好",
+  "好嘞",
+  "好滴",
+  "好呀",
+  "嗯",
+  "嗯嗯",
+  "哦",
+  "噢",
+  "喔",
+  "行",
+  "可以",
+  "可",
+  "没问题",
+  "没事",
+  "收到",
+  "明白",
+  "了解",
+  "知道了",
+  "懂了",
+  "对",
+  "对的",
+  "是",
+  "是的",
+  "不用",
+  "不用了",
+  "谢谢",
+  "谢了",
+  "多谢",
+  "辛苦了",
+  "辛苦",
+  "牛",
+  "赞",
+  "棒",
+  "妙",
+  "ok",
+  "okay",
+  "k",
+  "kk",
+  "yes",
+  "yep",
+  "yeah",
+  "no",
+  "nope",
+  "sure",
+  "thanks",
+  "thank you",
+  "thx",
+  "ty",
+  "cool",
+  "nice",
+  "great",
+  "done",
+  "got it",
+  "will do",
+]);
+
+// Bare CLI invocations ("git push", "npm test"). A leading tool name alone is
+// not enough — the rest must look like arguments, not prose: any CJK character
+// or question mark ("git 为什么失败", "why does npm test hang?") disqualifies.
+const CLI_SHAPE =
+  /^(git|npm|npx|bun|bunx|yarn|pnpm|node|python3?|pip3?|cargo|make|docker|kubectl|brew|ssh|ls|cd|cat|grep|curl)(\s+[^㐀-鿿?？]*)?$/i;
+
+// Emoji message test: strip whitespace, then require every remaining unit to
+// be pictographic or an emoji modifier. \p{Extended_Pictographic} deliberately
+// excludes bare digits/#/* (they only render as emoji inside keycap sequences
+// with U+FE0F+U+20E3), so "42" and "#1" fall through to "pass".
+const EMOJI_UNIT =
+  /^(?:\p{Extended_Pictographic}|\p{Regional_Indicator}|[\u{1F3FB}-\u{1F3FF}\u{FE0F}\u{200D}\u{20E3}])+$/u;
+
+// Trailing tone particles + punctuation tolerated on whole-message matches
+// ("好的吧。", "继续吧!", "开始咯~").
+const TRAILING_FLUFF = /[吧呗啊呀哦嘛喽咯哈嘞捏诶欸了]*[\s。，,.!！?？~〜…‥·、;；:：'"'"()（）]*$/u;
+
+function stripTrailingFluff(text: string): string {
+  return text.replace(TRAILING_FLUFF, "");
+}
+
+function normalize(message: string): string {
+  return message.replace(/\s+/g, " ").trim();
+}
+
+function isAckMessage(lower: string): boolean {
+  const stripped = stripTrailingFluff(lower);
+  if (!stripped) return false;
+  if (ACK_WORDS.has(stripped)) return true;
+  // Multi-token acks ("好的 谢谢", "ok thanks"): every token must be an ack word.
+  const tokens = stripped.split(/[\s,，。!！~]+/).filter(Boolean);
+  return tokens.length > 1 && tokens.every((t) => ACK_WORDS.has(stripTrailingFluff(t)));
+}
+
+/**
+ * Classify one auto-recall message. Pure and deterministic — call order is
+ * force cues → length guard → structural skips → whole-message skips →
+ * resume nudges → default pass.
+ */
+export function classifyRecallGate(message: string): RecallGateResult {
+  const text = normalize(message);
+  if (!text) return { decision: "skip-all", ruleId: "skip:empty" };
+  const lower = text.toLowerCase();
+
+  // 1. Force cues outrank every short-text rule ("可以按上次方案做" must not
+  //    be swallowed by the ack rule).
+  for (const cue of FORCE_CUES_ZH) {
+    if (text.includes(cue)) return { decision: "full-recall", ruleId: "force:memory-cue-zh" };
+  }
+  for (const cue of FORCE_CUES_EN) {
+    if (cue.test(lower)) return { decision: "full-recall", ruleId: "force:memory-cue-en" };
+  }
+
+  // 2. Long messages always deserve the full pipeline.
+  if (text.length > SHORT_TEXT_MAX_CHARS) return { decision: "pass", ruleId: "pass:long" };
+
+  // 3. Structural skips.
+  if (/^\/\S+/.test(text)) return { decision: "skip-all", ruleId: "skip:slash" };
+  if (/^HEARTBEAT/i.test(text)) return { decision: "skip-all", ruleId: "skip:heartbeat" };
+  if (EMOJI_UNIT.test(text.replace(/\s+/g, ""))) {
+    return { decision: "skip-all", ruleId: "skip:emoji" };
+  }
+  if (text.length <= 60 && CLI_SHAPE.test(text)) {
+    return { decision: "skip-all", ruleId: "skip:cli" };
+  }
+
+  // 4. Whole-message conversational skips.
+  const strippedLower = stripTrailingFluff(lower);
+  if (GREETINGS.has(strippedLower)) return { decision: "skip-all", ruleId: "skip:greeting" };
+  if (isAckMessage(lower)) return { decision: "skip-all", ruleId: "skip:ack" };
+
+  // 5. Continuity nudges → resume context without a focused search.
+  if (RESUME_PHRASES.has(strippedLower)) {
+    return { decision: "resume-only", ruleId: "resume:continuity" };
+  }
+
+  return { decision: "pass", ruleId: "pass:default" };
+}
+
+// --- shadow log (observe-before-enforce evidence trail) ---
+
+export interface RecallGateShadowEntry {
+  ts: string;
+  decision: RecallGateDecision;
+  ruleId: string;
+  msgLen: number;
+  mode: Exclude<RecallGateMode, "off">;
+  /** Caller-provided origin, e.g. "api:/v1/auto-recall". Never message text. */
+  source?: string;
+}
+
+export const RECALL_GATE_SHADOW_FILE = "recall-gate-shadow.jsonl";
+
+/**
+ * Append one shadow-log line under dataDir(). Must never block or throw —
+ * gate telemetry failing is strictly better than recall failing.
+ */
+export function logRecallGateShadow(entry: RecallGateShadowEntry): void {
+  try {
+    const dir = dataDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, RECALL_GATE_SHADOW_FILE), `${JSON.stringify(entry)}\n`, "utf8");
+  } catch {
+    // Shadow logging is best-effort by design.
+  }
+}

package/src/retrieval-profiles.ts

@@ -1,7 +1,46 @@
-import type { RetrievalConfig } from "./retriever.js";
+import {
+  DEFAULT_CATEGORY_MIN_SCORES,
+  DEFAULT_RETRIEVAL_CONFIG,
+  type RetrievalConfig,
+} from "./retriever.js";
 
 export type RetrievalProfileName = "default" | "writing" | "debug" | "fact-check";
 
+/**
+ * Scale the default per-category thresholds by how loose/tight a profile is overall.
+ *
+ * Why this exists: a profile used to override `hardMinScore` only, while
+ * `Retriever.minScoreFor()` reads `categoryMinScores` first and only falls back to
+ * `hardMinScore` for categories not listed. Since the default map lists every
+ * category, a profile's looser/tighter intent never reached category admission at
+ * all — picking `debug` ("I want episodic detail") still admitted `events` at 0.35
+ * and `patterns` at 0.45, exactly as `default` would.
+ *
+ * IMPORTANT: the returned map must stay complete. A partial map would silently send
+ * unlisted categories to `hardMinScore` instead of their default threshold.
+ *
+ * simplified: proportional scaling only — the *relative* ordering across categories
+ * is inherited from DEFAULT_CATEGORY_MIN_SCORES unchanged. Re-designing that ordering
+ * per profile (e.g. `debug` favouring episodic categories, `writing` favouring
+ * semantic ones) is the better end state but needs canary evidence to pick numbers;
+ * do that via `bun run eval:canary` before touching the ratios here.
+ */
+function scaledCategoryMinScores(profileHardMinScore: number): Record<string, number> {
+  const factor = profileHardMinScore / DEFAULT_RETRIEVAL_CONFIG.hardMinScore;
+  return Object.fromEntries(
+    Object.entries(DEFAULT_CATEGORY_MIN_SCORES).map(([category, minScore]) => [
+      category,
+      Math.round(minScore * factor * 1000) / 1000,
+    ]),
+  );
+}
+
+// Kept as named constants so each profile's `hardMinScore` and its scaled category
+// thresholds cannot drift apart.
+const WRITING_HARD_MIN_SCORE = 0.24;
+const DEBUG_HARD_MIN_SCORE = 0.34;
+const FACT_CHECK_HARD_MIN_SCORE = 0.38;
+
 export interface RetrievalProfileDefinition {
   name: RetrievalProfileName;
   label: string;
@@ -27,7 +66,8 @@ export const RETRIEVAL_PROFILES: Record<RetrievalProfileName, RetrievalProfileDe
       recencyHalfLifeDays: 90,
       recencyWeight: 0.06,
       timeDecayHalfLifeDays: 365,
-      hardMinScore: 0.24,
+      hardMinScore: WRITING_HARD_MIN_SCORE,
+      categoryMinScores: scaledCategoryMinScores(WRITING_HARD_MIN_SCORE),
       lengthNormAnchor: 800,
     },
   },
@@ -42,7 +82,8 @@ export const RETRIEVAL_PROFILES: Record<RetrievalProfileName, RetrievalProfileDe
       recencyHalfLifeDays: 7,
       recencyWeight: 0.15,
       timeDecayHalfLifeDays: 30,
-      hardMinScore: 0.34,
+      hardMinScore: DEBUG_HARD_MIN_SCORE,
+      categoryMinScores: scaledCategoryMinScores(DEBUG_HARD_MIN_SCORE),
       lengthNormAnchor: 420,
     },
   },
@@ -57,7 +98,8 @@ export const RETRIEVAL_PROFILES: Record<RetrievalProfileName, RetrievalProfileDe
       recencyHalfLifeDays: 21,
       recencyWeight: 0.08,
       timeDecayHalfLifeDays: 45,
-      hardMinScore: 0.38,
+      hardMinScore: FACT_CHECK_HARD_MIN_SCORE,
+      categoryMinScores: scaledCategoryMinScores(FACT_CHECK_HARD_MIN_SCORE),
       lengthNormAnchor: 360,
     },
   },

package/src/retriever.ts

@@ -14,7 +14,7 @@ import { expandQuery } from "./query-expander.js";
 import { detectLang, tokenizeFts } from "./language-hook.js";
 import { type AccessTracker, computeHotnessScore, parseAccessMetadata } from "./access-tracker.js";
 import { weibullDecay, resolveTier, isDecayExempt, adjustHalfLifeForEmotion, computeArousalBoost } from "./decay-engine.js";
-import { logWarn } from "./stderr-log.js";
+import { logInfo, logWarn } from "./stderr-log.js";
 import { extractBoundaryMetadata, isDurableMemoryScope, isTranscriptScope } from "./memory-boundaries.js";
 import type { TraceCollector } from "./retrieval-trace.js";
 import { extractTopicTag } from "./topic-tag.js";
@@ -107,6 +107,7 @@ export interface RetrievalConfig {
   /**
    * Hotness blend weight. Blends access-frequency hotness into final score.
    * Formula: final = score * (1-alpha) + hotness * alpha.
+   * Zero-access rows keep their score unchanged (bonus-only cold start).
    * 0 = disabled (default), 0.15 = recommended.
    */
   hotnessWeight: number;
@@ -240,7 +241,16 @@ export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
   filterNoise: true,
   rerankModel: "jina-reranker-v3",
   rerankEndpoint: "https://api.jina.ai/v1/rerank",
-  lengthNormAnchor: 500,
+  // 2026-08-06：500 → 800。不是拍的——writing profile 早就在用 800
+  // （retrieval-profiles.ts），这里只是把一个已在生产跑着的值推广到 default。
+  // 实测（eval/ghost-scan.ts，14,949 条 active 全库快照）：结构性幽灵
+  // 775 → 245（5.18% → 1.64%），救回 530 条，中位长度 1,356 字符那批正落在
+  // 打折最重的区间。挤占效应见 eval/lengthnorm-shadow.ts：20 条真实 query
+  // 里 14 条 top-6 完全不变，6 条掉出在 limit 放大到 20 后全部复现
+  // ——即没有任何条目被删掉，只是挤出窗口，而那 6 条的重排来自
+  // applySourceDiversity + MMR（候选数 ≤ limit 时它根本不轮转，
+  // anchor 放大让更多候选过阈值才把这个既有行为激活），与本参数无关。
+  lengthNormAnchor: 800,
   hardMinScore: 0.35,
   timeDecayHalfLifeDays: 60,
   hotnessWeight: 0,
@@ -253,6 +263,14 @@ export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
  * （mem0/recallnest/GitHub），避免日常语义 query 误触发 BM25 噪声。
  */
 export function hasExactToken(query: string): boolean {
+  // 【为什么中文 query 不触发本函数 —— 这是实测后的决定，不是 ASCII-only 的遗漏】
+  // 2026-08-01 用临时开关对 5 条真实中文 query 做过 A/B：强制让中文触发 BM25 补偿后，
+  // 3/4 的 query 零新增（BM25 捞回的条目 vector 早已召回，被 vecIds 去重滤掉），
+  // 唯一有新增的那次补进 3 条、其中 1 条是当天无关对话，且补偿结果是**插在队首**的。
+  // 中文分词本身没问题（babel-memory 已注册，detectLang 正确返回 zh，
+  // "双机契约" → "双机 契约"），所以这不是 tokenizer 问题 ——
+  // 是 BM25 对中文**语义类** query 的边际收益本就接近零，放开只会拿噪声占前三名。
+  // 若将来要重开，先复现那组 A/B，别只凭"中文没走 BM25"这个现象下判断。
   for (const t of query.split(/[\s，。、；：（）()【】「」"'`?？!！]+/)) {
     if (t.length < 5) continue;
     // 全大写 + 下划线常量（必须含下划线，避免 JSON/HTTP/GitHub 等普通缩写/驼峰误触发）
@@ -780,6 +798,16 @@ export class MemoryRetriever {
 
     let results: RetrievalResult[];
 
+    // 分派前必须先让 store 完成惰性初始化，否则下面读到的 hasFtsSupport 是初始化前的
+    // false，hybrid 模式的**首次**检索会静默落回 vector 路径（同一实例第二次才正常）。
+    // 该缺陷自 c10607a 初始版本就在，长期未暴露有两个原因：生产 mode 一直是 "vector"，
+    // 第一个条件短路、根本读不到第二个；而 eval 的 createFreshEvalComponentsFactory 每
+    // case 新建组件，每个 case 都停在"首次"，于是 eval 从未测到过 hybrid 路径。
+    // 注：supplementExactTokenWithBm25 那里的顺序依赖是被意识到的（见其注释"hasFtsSupport
+    // 在 vectorOnly 触发 store init 后为真"），漏的只是这个分派点。
+    // `?.` 是必需的：测试大量使用鸭子类型的 fake store，它们没有 ready()。
+    await this.store.ready?.();
+
     // For vector-only mode, use legacy behavior
     if (this.config.mode === "vector" || !this.store.hasFtsSupport) {
       results = await this.vectorOnlyRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace);
@@ -1262,10 +1290,14 @@ export class MemoryRetriever {
       ? hardFiltered
       : hardFiltered.filter(r => isActiveMemory(r.entry.metadata));
 
-    trace?.startStage("noise_filter", evolutionFiltered.length);
+    // LA-1: 资格层准入 —— 默认让 durable 层回答，evidence 留给 deja / 显式溯源。
+    // 放在各类 dedup 之前：先定"谁有资格进候选集"，再谈多样性与去重。
+    const layerAdmitted = this.applyLayerAdmission(evolutionFiltered, trace);
+
+    trace?.startStage("noise_filter", layerAdmitted.length);
     const denoised = this.config.filterNoise
-      ? filterNoise(evolutionFiltered, r => r.entry.text)
-      : evolutionFiltered;
+      ? filterNoise(layerAdmitted, r => r.entry.text)
+      : layerAdmitted;
     trace?.endStage(denoised.length, denoised.map(r => r.score));
 
     // RIF: demote near-duplicate weak results to improve diversity
@@ -1766,6 +1798,49 @@ export class MemoryRetriever {
     return weighted.sort((a, b) => b.score - a.score);
   }
 
+  /** LA-1: 一条结果是否属于 evidence 层（transcript 碎片）。判据与 applyBoundaryWeight 保持一致。 */
+  private isEvidenceLayer(r: RetrievalResult): boolean {
+    const boundary = extractBoundaryMetadata(r.entry.metadata);
+    if (boundary) return boundary.layer === "evidence";
+    return isTranscriptScope(r.entry.scope);
+  }
+
+  /**
+   * LA-1: 资格层准入 —— 决定"哪一层来回答这个 query"，而非调整分数。
+   *
+   * 与 applyBoundaryWeight 的区别是本方法存在的全部理由：那个改分数（排序层），
+   * 会让来源盖过相关性（`retriever-boundary-weight.test.ts` 明确禁止这点）；
+   * 本方法只挑选候选集，层内相关性排序原封不动。
+   *
+   * durable 命中不足 `layerAdmissionMin` 时回退到全量候选池 —— 新主题在结论层
+   * 往往是空的，宁缺毋滥不能变成什么都不给。
+   */
+  private applyLayerAdmission(
+    results: RetrievalResult[],
+    trace?: TraceCollector,
+  ): RetrievalResult[] {
+    const mode = envConfig.layerAdmission();
+    if (mode === "off" || results.length === 0) return results;
+
+    const durable = results.filter(r => !this.isEvidenceLayer(r));
+    const dropped = results.length - durable.length;
+    const thin = durable.length < envConfig.layerAdmissionMin();
+
+    if (mode === "observe") {
+      logInfo(
+        `[layer-admission] observe: durable=${durable.length} evidence=${dropped} ` +
+        `total=${results.length} action=${thin ? "fallback(keep-all)" : "would-drop-evidence"}`,
+      );
+      return results;
+    }
+
+    if (thin) return results;
+
+    trace?.startStage("layer_admission", results.length);
+    trace?.endStage(durable.length, durable.map(r => r.score));
+    return durable;
+  }
+
   private applyBoundaryWeight(results: RetrievalResult[]): RetrievalResult[] {
     const weighted = results.map(r => {
       const boundary = extractBoundaryMetadata(r.entry.metadata);
@@ -1836,8 +1911,8 @@ export class MemoryRetriever {
 
     const now = Date.now();
     const decayed = results.map(r => {
-      // HP-7: Exempt core/pinned/recently-accessed from decay
-      if (isDecayExempt(r.entry.metadata, r.entry.importance)) return r;
+      // HP-7: Exempt core/pinned/recently-accessed (and procedural categories) from decay
+      if (isDecayExempt(r.entry.metadata, r.entry.importance, r.entry.category)) return r;
 
       const ts = (r.entry.timestamp && r.entry.timestamp > 0) ? r.entry.timestamp : now;
       const ageDays = (now - ts) / 86_400_000;
@@ -1854,7 +1929,7 @@ export class MemoryRetriever {
       }
 
       // Resolve tier from metadata (defaults to peripheral)
-      const tier = resolveTier(r.entry.metadata);
+      const tier = resolveTier(r.entry.metadata, r.entry.importance);
 
       // Weibull decay with tier-specific shape and floor
       const factor = weibullDecay(ageDays, halfLife, tier);
@@ -1869,14 +1944,6 @@ export class MemoryRetriever {
     return decayed.sort((a, b) => b.score - a.score);
   }
 
-  /**
-   * Blend access-frequency hotness into retrieval scores.
-   *
-   * Formula: final = score * (1 - alpha) + hotness * alpha
-   * where hotness = sigmoid(log1p(accessCount)) * exp(-decayRate * ageDays)
-   *
-   * No-op when hotnessWeight is 0 or AccessTracker is absent.
-   */
   /**
    * B-1/E-1: Evolution decay blend — factor in composite decay score
    * (time × frequency × importance) as a scoring signal.
@@ -1885,8 +1952,8 @@ export class MemoryRetriever {
   private applyEvolutionDecayBlend(results: RetrievalResult[]): RetrievalResult[] {
     const EVOLUTION_BLEND_WEIGHT = 0.10;
     return results.map(r => {
-      // HP-7: Exempt entries get max decay score (1.0) → no penalty
-      if (isDecayExempt(r.entry.metadata, r.entry.importance)) {
+      // HP-7: Exempt entries (incl. procedural categories) get max decay score (1.0) → no penalty
+      if (isDecayExempt(r.entry.metadata, r.entry.importance, r.entry.category)) {
         return {
           ...r,
           score: clamp01(r.score * (1 - EVOLUTION_BLEND_WEIGHT) + 1.0 * EVOLUTION_BLEND_WEIGHT, 0),
@@ -2087,6 +2154,15 @@ export class MemoryRetriever {
     return [...results, ...siblings].sort((a, b) => b.score - a.score);
   }
 
+  /**
+   * Blend access-frequency hotness into retrieval scores.
+   *
+   * Formula: final = score * (1 - alpha) + hotness * alpha
+   * where hotness = sigmoid(log1p(accessCount)) * exp(-decayRate * ageDays)
+   * Zero-access rows keep their incoming score; accessed rows retain this formula.
+   *
+   * No-op when hotnessWeight is 0 or AccessTracker is absent.
+   */
   private applyHotnessBlend(results: RetrievalResult[]): RetrievalResult[] {
     const raw = this.config.hotnessWeight;
     const alpha = Math.min(1, Math.max(0, Number.isFinite(raw) ? raw : 0));
@@ -2098,6 +2174,7 @@ export class MemoryRetriever {
         accessCount,
         lastAccessedAt || r.entry.timestamp,
       );
+      if (accessCount === 0) return r;
       return {
         ...r,
         score: clamp01(r.score * (1 - alpha) + hotness * alpha, 0),

package/src/retroactive-boost.ts

@@ -21,6 +21,7 @@
  */
 
 import type { MemoryStore, MemoryEntry } from "./store.js";
+import { isActiveMemory } from "./memory-evolution.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -85,12 +86,15 @@ export async function retroactiveBoost(
   }
 
   // Find related entries in the same scope
-  const candidates = await store.vectorSearch(
+  // Superseded belief-history rows come back from vectorSearch too. Boosting one is wasted
+  // — they are excluded from retrieval anyway — and it burns maxBoostPerTrigger budget that
+  // live entries should be getting.
+  const candidates = (await store.vectorSearch(
     newEntry.vector,
     config.maxBoostPerTrigger * 3, // fetch more, filter down
     config.similarityThreshold,
     [newEntry.scope],
-  );
+  )).filter((candidate) => isActiveMemory(candidate.entry.metadata));
 
   const now = Date.now();
   const minAgeMs = config.minAgeDays * 86_400_000;