recallnest 2.3.0 → 2.6.0

package/src/retriever.ts

@@ -6,12 +6,15 @@
 import type { MemoryStore, MemorySearchResult } from "./store.js";
 import type { Embedder } from "./embedder.js";
 import { filterNoise } from "./noise-filter.js";
+import * as envConfig from "./env-config.js";
+import { extractErrorSignatures } from "./error-signature.js";
 import { shouldSkipRetrieval } from "./adaptive-retrieval.js";
+import { expandQueryWithAliases } from "./aliases.js";
 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";
@@ -30,6 +33,7 @@ import {
   tokenize,
 } from "./multi-vector.js";
 import { parseTemporalQuery, matchesTemporalConstraint, type TemporalConstraint } from "./temporal-parser.js";
+import { parseSourceIds } from "./kg-store.js";
 import type { KGStore } from "./kg-store.js";
 import { isKGModeEnabled } from "./kg-extractor.js";
 import { detectEntities } from "./query-entity-detector.js";
@@ -41,6 +45,7 @@ import { parseNarrative, isNarrativeModeEnabled } from "./narrative-schema.js";
 import type { EmotionMetadata } from "./memory-schema.js";
 import { detectEmotion } from "./emotion-detector.js";
 import { shouldReconstruct, reconstruct as runReconstruction } from "./context-reconstructor.js";
+import { recordReconstructionUsage as runUsageShadow } from "./usage-tracker.js";
 import type {
   ReconstructionLLMClient,
   ReconstructionOutput,
@@ -102,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;
@@ -189,6 +195,12 @@ export interface RetrievalResult extends MemorySearchResult {
  */
 export type RetrievalResultSet = RetrievalResult[] & {
   reconstruction?: ReconstructionOutput;
+  /**
+   * P-omitted: 因 limit 上限被截断、未返回的达标结果数（提高 limit 可见）。
+   * 仅统计 finalizeResults 的 limit 截断，不含质量过滤（min-score/noise/MMR）丢弃——
+   * 那些提高 limit 也拿不到，报告出来反而误导调用方。
+   */
+  omitted?: { count: number; reason: "limit" };
 };
 
 // ============================================================================
@@ -209,24 +221,73 @@ export const DEFAULT_CATEGORY_MIN_SCORES: Record<string, number> = {
   patterns: 0.45,
 };
 
+// P1.2（2026-06-25）：默认 vector-only。canary eval 实测个人记忆库 vector 召回质量全面优于
+// hybrid（robustness 带 scope WITH 6/12 + 不带 scope WITHOUT 10/12，完胜 hybrid 的 3/9；BM25 在
+// 高度同质的个人记忆里是净噪声，会把 vector 本应 top 的目标如 dbcb317a 挤掉）。改频率层救低频
+// 目标实测是死结（动 hotness 必伤靠 hotness 上位的记忆）。hybrid 路径代码全保留，mode 改回
+// "hybrid" 即可切换（注：multiHopExpand 仍硬编码走 hybrid，默认 off，config.retrieval.multiHop
+// 开了会破纯 vector）。数据盲区：canary 全是语义 query，未覆盖 BM25 强项的精确关键词/token 召回
+// （变量名 / commit hash / alias-map 昵称）——待补 exact-token canary 验证。
 export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
-  mode: "hybrid",
+  mode: "vector",
   vectorWeight: 0.7,
   bm25Weight: 0.3,
   minScore: 0.3,
   rerank: "cross-encoder",
-  candidatePoolSize: 20,
+  candidatePoolSize: 30,
+  sourceDiversity: 1,
   recencyHalfLifeDays: 14,
   recencyWeight: 0.10,
   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,
 };
 
+/**
+ * P1.2+: 检测 query 是否含「精确 token」——大写常量 / commit hash / 文件名 / snake/camelCase /
+ * 低元音 ID（如 rwmjhb）。这类 token vectorOnly 抓不到（embedding 做语义相似非精确匹配，跟语言
+ * 无关：实测纯/中文/中英混 query 都漏靠 token 区分的目标），需 BM25 兜底。刻意避开元音正常的普通词
+ * （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 等普通缩写/驼峰误触发）
+    if (/^[A-Z][A-Z0-9]*_[A-Z0-9_]+$/.test(t)) return true;                   // DEDUP_HARD_THRESHOLD
+    // snake_case 标识符（含下划线）
+    if (/^[a-z][a-z0-9]*_[a-z0-9_]+$/i.test(t)) return true;                  // capture_engine
+    // 文件名（基名 + 代码扩展名）
+    if (/^[\w./-]+\.(ts|tsx|js|jsx|py|md|sh|json|sql|go|rs|java|cpp|yml|yaml|toml)$/i.test(t)) return true;  // capture-heuristic.ts
+    // hex commit hash（7-40，含数字+字母，纯 hex）
+    if (/^[0-9a-f]{7,40}$/i.test(t) && /[0-9]/.test(t) && /[a-f]/i.test(t)) return true;  // dd12fb5
+    // 注：camelCase（GitHub/TypeScript）与低元音 ID（rwmjhb/pytest/nginx）两条宽规则已移除——
+    // 前者误伤日常技术 query 引回 BM25 噪声；rwmjhb 类纯小写 ID 即便触发，fts 中英混分词也召回不到
+    // （根因在 tokenizer，是独立 backlog），靠中英一起 query 的中文锚点已能补回。
+  }
+  return false;
+}
+
 // ============================================================================
 // Utility Functions
 // ============================================================================
@@ -314,6 +375,32 @@ function applyAnchorBoost(results: RetrievalResult[], query: string): RetrievalR
   });
 }
 
+/** Multiplicative boost applied to a case on exact error-signature match. */
+const ERROR_SIGNATURE_BOOST_FACTOR = 1.5;
+
+/**
+ * A1 (P3-A): error-signature exact-match boost. When RECALLNEST_ERROR_SIGNATURE_BOOST
+ * is on, case memories whose metadata.error_signature overlaps the query's extracted
+ * signatures get a strong multiplicative boost ("上次一模一样的报错"精确召回). Flag off
+ * (default) returns the input unchanged — bit-identical, so the pure-move eval baseline holds.
+ * Only affects category="cases"; read and query side share extractErrorSignatures so the
+ * signatures compare apples-to-apples.
+ */
+export function applyErrorSignatureBoost(results: RetrievalResult[], query: string): RetrievalResult[] {
+  if (!envConfig.errorSignatureBoost()) return results;
+  const querySignatures = extractErrorSignatures({ problem: query });
+  if (querySignatures.length === 0) return results;
+  const querySet = new Set(querySignatures.map(s => s.toLowerCase()));
+  return results.map(r => {
+    if (r.entry.category !== "cases") return r;
+    const sigs = parseMetadata(r.entry.metadata).error_signature;
+    if (!Array.isArray(sigs) || sigs.length === 0) return r;
+    const hit = sigs.some(s => typeof s === "string" && querySet.has(s.toLowerCase()));
+    if (!hit) return r;
+    return { ...r, score: Math.min(1, Math.max(0, r.score * ERROR_SIGNATURE_BOOST_FACTOR)) };
+  });
+}
+
 /**
  * Emotion scoring stage: boost memories matching query emotional tone.
  * No-op when query is neutral or memory lacks emotion data.
@@ -668,6 +755,16 @@ export class MemoryRetriever {
     this.llmClient = client;
   }
 
+  /**
+   * Shadow-record which memories a reconstruction actually cited via [src:ID].
+   * 影子统计：写 metadata.usage（injection-vs-use 双计数），第一阶段不参与 ranking/forget。
+   * best-effort：不传 scope（影子写入不做权限过滤，避免跨 scope 扩展候选触发越权 throw）；
+   * 内部 allSettled 不抛错，绝不阻断主检索/resume 流程。
+   */
+  async recordReconstructionUsage(citedIds: string[]): Promise<void> {
+    await runUsageShadow(this.store, citedIds);
+  }
+
   /** Suppress a memory ID for the current session (score × 0.3). */
   suppressForSession(id: string): void {
     this.sessionSuppressed.add(id);
@@ -687,16 +784,30 @@ export class MemoryRetriever {
   }
 
   async retrieve(context: RetrievalContext): Promise<RetrievalResultSet> {
-    const { query, limit, scopeFilter, category, includeArchived, trace, graph } = context;
+    const { query: rawQuery, limit, scopeFilter, category, includeArchived, trace, graph } = context;
     const safeLimit = clampInt(limit, 1, 20);
 
     // Adaptive retrieval: skip trivial queries to save embedding API calls
-    if (shouldSkipRetrieval(query)) {
+    if (shouldSkipRetrieval(rawQuery)) {
       return [];
     }
 
+    // Step 2: alias expansion — append canonical entity tokens for matching colloquial phrases.
+    // 不改原 query，仅追加，保留 vector embedding 原意；BM25 拿到更多锚点。
+    const query = expandQueryWithAliases(rawQuery);
+
     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);
@@ -705,6 +816,28 @@ export class MemoryRetriever {
       results = await this.hybridRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, graph);
     }
 
+    // 0-hit fallback: minScore filter 把所有候选过滤光时，放宽阈值（=0）重试一次。
+    // 只在原 path 0 hit 触发；正常召回不受影响。
+    if (results.length === 0) {
+      if (this.config.mode === "vector" || !this.store.hasFtsSupport) {
+        results = await this.vectorOnlyRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, 0);
+      } else {
+        results = await this.hybridRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, graph, 0);
+      }
+    }
+
+    // P-omitted: 快照 finalize 阶段因 limit 截断的达标结果数（提高 limit 可见）。
+    // 必须在后续 validity/topicTag filter（以及 BM25 补偿等换数组操作）丢失 ResultSet 属性之前读取。
+    let omittedByLimit = (results as RetrievalResultSet).omitted?.count ?? 0;
+
+    // P1.2+: exact-token BM25 补偿——query 含精确 token（大写常量/commit hash/.ts 文件名/camelCase/
+    // 低元音 ID 如 rwmjhb）时，vector 漏掉的精确命中用 BM25 补回（vectorOnly 做语义相似、不做精确
+    // 字符串匹配，是 embedding 本质，跟语言无关）。普通词（mem0/recallnest/GitHub）不触发，日常
+    // 语义召回不受影响。
+    if (hasExactToken(rawQuery)) {
+      results = await this.supplementExactTokenWithBm25(query, results, safeLimit, scopeFilter, category, includeArchived);
+    }
+
     // LME-2: Multi-hop retrieval — extract entities from first-pass results,
     // run focused follow-up queries, merge to improve cross-session coverage.
     const useMultiHop = context.multiHop ?? this.config.multiHop ?? false;
@@ -773,7 +906,11 @@ export class MemoryRetriever {
 
     // Phase 4: Constructive retrieval — first-class reconstruction (no metadata hack)
     const resultSet = results as RetrievalResultSet;
-    const constructiveFlag = process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL === "true";
+    // P-omitted: 把快照的 limit 截断数挂回最终 resultSet（validity filter 已丢原数组属性）。
+    if (omittedByLimit > 0) {
+      resultSet.omitted = { count: omittedByLimit, reason: "limit" };
+    }
+    const constructiveFlag = envConfig.constructiveRetrieval();
     if (shouldReconstruct({
       flagEnabled: constructiveFlag,
       callerOptIn: context.reconstruct === true,
@@ -790,6 +927,8 @@ export class MemoryRetriever {
           expansionDeps,
         );
         resultSet.reconstruction = reconstruction;
+        // Shadow usage：记录被 reconstruction 真正引用的记忆（use 信号），不动 ranking/forget。
+        await this.recordReconstructionUsage(reconstruction.sources.map(s => s.id));
       } catch {
         // Silent degradation — return raw results
       }
@@ -798,6 +937,36 @@ export class MemoryRetriever {
     return resultSet;
   }
 
+  /**
+   * P1.2+: exact-token BM25 补偿。vectorOnly 主路径后，若 query 含精确 token，用 BM25 精确匹配把
+   * vector 漏掉的命中补回。hasFtsSupport 在 vectorOnly 触发 store init 后为真；fake store 为假时跳过。
+   * bm25 精确命中提到结果前（exact-token 意图=精确优先），vector 语义结果跟后，去重后 slice limit。
+   */
+  private async supplementExactTokenWithBm25(
+    query: string,
+    vectorResults: RetrievalResult[],
+    limit: number,
+    scopeFilter?: string[],
+    category?: string,
+    includeArchived?: boolean,
+  ): Promise<RetrievalResult[]> {
+    if (!this.store.hasFtsSupport) return vectorResults;
+    const ftsQuery = tokenizeFts(expandQuery(query), detectLang(query));
+    const bm25 = await this.runBM25Search(ftsQuery, Math.max(limit, 5), scopeFilter, category, includeArchived);
+    const vecIds = new Set(vectorResults.map(r => r.entry.id));
+    const supplements = bm25
+      .filter(b => !vecIds.has(b.entry.id))
+      .filter(b => isActiveMemory(b.entry.metadata))   // 排掉 superseded/archived/consolidated（补偿绕过了 finalize 的尾部过滤，这里补回 active 校验）
+      .slice(0, 3)
+      .map(b => ({
+        entry: b.entry,
+        score: b.score,
+        sources: { bm25: { score: b.score, rank: b.rank } },
+      } as RetrievalResult));
+    if (supplements.length === 0) return vectorResults;
+    return [...supplements, ...vectorResults].slice(0, limit);
+  }
+
   /**
    * LME-2: Multi-hop expansion — extract entities from first-pass results,
    * run entity-focused follow-up queries, merge with original results.
@@ -860,6 +1029,7 @@ export class MemoryRetriever {
     category?: string,
     includeArchived?: boolean,
     trace?: TraceCollector,
+    minScoreOverride?: number,
   ): Promise<RetrievalResult[]> {
     // Temporal reasoning for vector-only mode
     const temporal = parseTemporalQuery(query);
@@ -867,12 +1037,20 @@ export class MemoryRetriever {
 
     trace?.startStage("vector_search", 0);
     const queryVector = await this.embedder.embedQuery(searchQuery);
-    // P0.1: Lower minScore for short queries
+    // P0.1: Lower minScore for short queries; minScoreOverride 用于 0-hit fallback retry
     const shortQ = isShortQuery(searchQuery);
-    const vectorMinScore = shortQ
-      ? this.config.minScore * SHORT_QUERY_MIN_SCORE_FACTOR
-      : this.config.minScore;
-    const results = await this.store.vectorSearch(queryVector, limit, vectorMinScore, scopeFilter);
+    const vectorMinScore = minScoreOverride !== undefined
+      ? minScoreOverride
+      : (shortQ
+          ? this.config.minScore * SHORT_QUERY_MIN_SCORE_FACTOR
+          : this.config.minScore);
+    // P-omitted: over-fetch a wider candidate pool so finalizeResults can detect limit-capped
+    // omissions. Previously fetched exactly `limit`, so vector-only omitted was always 0
+    // (hybrid already over-fetches candidatePoolSize). Cost is minimal — ANN with a larger K
+    // plus a few more local scoring passes, no extra API; P1.2's vector-only savings come from
+    // skipping hybrid BM25/fusion/rerank, not from fetch size.
+    const fetchLimit = Math.max(limit, this.config.candidatePoolSize ?? limit);
+    const results = await this.store.vectorSearch(queryVector, fetchLimit, vectorMinScore, scopeFilter);
     trace?.endStage(results.length, results.map(r => r.score));
 
     // Filter by category if specified
@@ -900,103 +1078,18 @@ export class MemoryRetriever {
     // P0.1: Anchor boost for vector-only path
     const anchorBoosted = applyAnchorBoost(mapped, searchQuery);
 
-    trace?.startStage("recency_boost", anchorBoosted.length);
-    const boosted = this.applyRecencyBoost(anchorBoosted);
-    trace?.endStage(boosted.length, boosted.map(r => r.score));
-
-    trace?.startStage("importance_weight", boosted.length);
-    const weighted = this.applyImportanceWeight(boosted);
-    trace?.endStage(weighted.length, weighted.map(r => r.score));
-
-    trace?.startStage("confidence_weight", weighted.length);
-    const confidenceWeighted = this.applyConfidence(weighted);
-    trace?.endStage(confidenceWeighted.length, confidenceWeighted.map(r => r.score));
-
-    let afterEmotionVector = confidenceWeighted;
-    if (isEmotionScoringEnabled()) {
-      const queryEmotion = detectEmotion(query);
-      const adapted = confidenceWeighted.map(r => ({ ...r, metadata: r.entry.metadata ?? "{}" }));
-      const emotioned = applyEmotionWeight(adapted, queryEmotion);
-      afterEmotionVector = confidenceWeighted.map((r, i) => ({ ...r, score: emotioned[i]?.score ?? r.score }));
-    }
-
-    trace?.startStage("boundary_weight", afterEmotionVector.length);
-    const boundaryWeighted = this.applyBoundaryWeight(afterEmotionVector);
-    trace?.endStage(boundaryWeighted.length, boundaryWeighted.map(r => r.score));
-
-    trace?.startStage("asset_type_weight", boundaryWeighted.length);
-    const assetWeighted = this.applyAssetTypeWeight(boundaryWeighted);
-    trace?.endStage(assetWeighted.length, assetWeighted.map(r => r.score));
-
-    trace?.startStage("length_norm", assetWeighted.length);
-    const lengthNormalized = this.applyLengthNormalization(assetWeighted);
-    trace?.endStage(lengthNormalized.length, lengthNormalized.map(r => r.score));
-
-    trace?.startStage("time_decay", lengthNormalized.length);
-    const timeDecayed = this.applyTimeDecay(lengthNormalized);
-    trace?.endStage(timeDecayed.length, timeDecayed.map(r => r.score));
-
-    // B-1/E-1: Evolution decay blend — boost memories with high composite decay score
-    const evolutionBlended = this.applyEvolutionDecayBlend(timeDecayed);
-
-    // E-1: Access count boost — memories retrieved more often get a score nudge
-    const accessBoosted = this.applyAccessCountBoost(evolutionBlended);
-
-    // Hotness blend: boost frequently + recently accessed memories
-    trace?.startStage("hotness_blend", accessBoosted.length);
-    const hotnessBlended = this.applyHotnessBlend(accessBoosted);
-    trace?.endStage(hotnessBlended.length, hotnessBlended.map(r => r.score));
-
-    // P0.2: Frequency boost — repeatedly retrieved memories score higher
-    trace?.startStage("frequency_boost", hotnessBlended.length);
-    const frequencyBoosted = this.applyFrequencyBoost(hotnessBlended);
-    trace?.endStage(frequencyBoosted.length, frequencyBoosted.map(r => r.score));
-
-    // Session suppression: temporarily penalize "do not disturb" memories
-    const afterSuppression = this.applySessionSuppression(frequencyBoosted);
-    const rescored = [...afterSuppression].sort((a, b) => b.score - a.score);
-
-    trace?.startStage("hard_min_score", rescored.length);
-    const hardFiltered = rescored.filter(r => r.score >= this.minScoreFor(r.entry.category, shortQ));
-    trace?.endStage(hardFiltered.length, hardFiltered.map(r => r.score));
-
-    // Evolution status filter: exclude superseded/archived/consolidated memories
-    const evolutionFiltered = includeArchived
-      ? hardFiltered
-      : hardFiltered.filter(r => isActiveMemory(r.entry.metadata));
-
-    trace?.startStage("noise_filter", evolutionFiltered.length);
-    const denoised = this.config.filterNoise
-      ? filterNoise(evolutionFiltered, r => r.entry.text)
-      : evolutionFiltered;
-    trace?.endStage(denoised.length, denoised.map(r => r.score));
-
-    // RIF: demote near-duplicate weak results to improve diversity
-    const afterRif = this.config.enableRIF
-      ? filterInterference(denoised, this.config.rifThreshold ?? 0.85, this.config.rifScoreRatio ?? 0.80)
-      : denoised;
-
-    // MMR deduplication: avoid top-k filled with near-identical memories
-    trace?.startStage("mmr_diversity", afterRif.length);
-    const deduplicated = this.applyMMRDiversity(afterRif);
-    trace?.endStage(deduplicated.length, deduplicated.map(r => r.score));
-
-    // Tier 3.3: Version group dedup — keep only the top-ranked version per group
-    const versionDeduped = deduplicateByVersionGroup(deduplicated);
-
-    // LC-P2: Cluster insight dedup — prefer cluster summary over individual source memories
-    const clusterDeduped = deduplicateByClusterInsight(versionDeduped);
-
-    // Source diversity: round-robin across scopes for multi-session coverage
-    const diversified = (this.config.sourceDiversity ?? 0) > 0
-      ? applySourceDiversity(clusterDeduped, limit)
-      : clusterDeduped;
+    const scored = this.applySharedScoring(anchorBoosted, query, trace);
 
-    trace?.startStage("final_limit", diversified.length);
-    const final = diversified.slice(0, limit);
-    trace?.endStage(final.length, final.map(r => r.score));
+    // Session suppression: temporarily penalize "do not disturb" memories (vector-only path)
+    const afterSuppression = this.applySessionSuppression(scored);
 
-    return final;
+    return this.finalizeResults(afterSuppression, {
+      shortQ,
+      minScoreOverride,
+      includeArchived,
+      limit,
+      trace,
+    });
   }
 
   private async hybridRetrieval(
@@ -1007,6 +1100,7 @@ export class MemoryRetriever {
     includeArchived?: boolean,
     trace?: TraceCollector,
     graph?: boolean,
+    minScoreOverride?: number,
   ): Promise<RetrievalResult[]> {
     // Adaptive pool: widen candidate pool for aggregation queries ("how many", "all the")
     const multiplier = (this.config.adaptivePoolMultiplier ?? 1) > 1 && isAggregationQuery(query)
@@ -1070,10 +1164,13 @@ export class MemoryRetriever {
 
     // Apply minimum score threshold
     trace?.startStage("min_score_filter", anchorBoosted.length);
-    // P0.1: Lower minScore for short queries to widen the candidate pool
-    const effectiveMinScore = isShortQuery(searchQuery)
-      ? this.config.minScore * SHORT_QUERY_MIN_SCORE_FACTOR
-      : this.config.minScore;
+    // P0.1: Lower minScore for short queries to widen the candidate pool;
+    // minScoreOverride 用于 retrieve() 顶层的 0-hit fallback retry。
+    const effectiveMinScore = minScoreOverride !== undefined
+      ? minScoreOverride
+      : (isShortQuery(searchQuery)
+          ? this.config.minScore * SHORT_QUERY_MIN_SCORE_FACTOR
+          : this.config.minScore);
     const filtered = anchorBoosted.filter(r => r.score >= effectiveMinScore);
     trace?.endStage(filtered.length, filtered.map(r => r.score));
 
@@ -1084,46 +1181,61 @@ export class MemoryRetriever {
       : filtered;
     trace?.endStage(reranked.length, reranked.map(r => r.score));
 
-    // Apply temporal re-ranking (recency boost)
-    trace?.startStage("recency_boost", reranked.length);
-    const temporalReranked = this.applyRecencyBoost(reranked);
-    trace?.endStage(temporalReranked.length, temporalReranked.map(r => r.score));
+    const scored = this.applySharedScoring(reranked, query, trace);
 
-    // Apply importance weighting
-    trace?.startStage("importance_weight", temporalReranked.length);
-    const importanceWeighted = this.applyImportanceWeight(temporalReranked);
-    trace?.endStage(importanceWeighted.length, importanceWeighted.map(r => r.score));
+    return this.finalizeResults(scored, {
+      shortQ,
+      minScoreOverride,
+      includeArchived,
+      limit,
+      trace,
+    });
+  }
 
-    // Viewpoint confidence: penalize corrected/contradicted memories
-    trace?.startStage("confidence_weight", importanceWeighted.length);
-    const confidenceWeighted = this.applyConfidence(importanceWeighted);
+  /**
+   * Shared scoring pipeline — the 12 stages identical across the vector-only and
+   * hybrid paths. Order is load-bearing (Codex §3.6 "顺序即语义"); do not reorder.
+   * `query` feeds the emotion stage; `trace` carries per-stage trace spans.
+   * Path-specific stages stay in the caller: anchor / min_score / rerank / multi-vector
+   * blend run BEFORE this; vector-only session suppression runs AFTER this.
+   */
+  private applySharedScoring(
+    results: RetrievalResult[],
+    query: string,
+    trace?: TraceCollector,
+  ): RetrievalResult[] {
+    trace?.startStage("recency_boost", results.length);
+    const boosted = this.applyRecencyBoost(results);
+    trace?.endStage(boosted.length, boosted.map(r => r.score));
+
+    trace?.startStage("importance_weight", boosted.length);
+    const weighted = this.applyImportanceWeight(boosted);
+    trace?.endStage(weighted.length, weighted.map(r => r.score));
+
+    trace?.startStage("confidence_weight", weighted.length);
+    const confidenceWeighted = this.applyConfidence(weighted);
     trace?.endStage(confidenceWeighted.length, confidenceWeighted.map(r => r.score));
 
-    // Emotion scoring: boost memories matching query emotional tone
-    let afterEmotion = confidenceWeighted;
+    let afterEmotionVector = confidenceWeighted;
     if (isEmotionScoringEnabled()) {
       const queryEmotion = detectEmotion(query);
       const adapted = confidenceWeighted.map(r => ({ ...r, metadata: r.entry.metadata ?? "{}" }));
       const emotioned = applyEmotionWeight(adapted, queryEmotion);
-      afterEmotion = confidenceWeighted.map((r, i) => ({ ...r, score: emotioned[i]?.score ?? r.score }));
+      afterEmotionVector = confidenceWeighted.map((r, i) => ({ ...r, score: emotioned[i]?.score ?? r.score }));
     }
 
-    // Prefer higher-authority durable memories over raw evidence when scores are close.
-    trace?.startStage("boundary_weight", afterEmotion.length);
-    const boundaryWeighted = this.applyBoundaryWeight(afterEmotion);
+    trace?.startStage("boundary_weight", afterEmotionVector.length);
+    const boundaryWeighted = this.applyBoundaryWeight(afterEmotionVector);
     trace?.endStage(boundaryWeighted.length, boundaryWeighted.map(r => r.score));
 
-    // Separate pinned assets from synthesized briefs.
     trace?.startStage("asset_type_weight", boundaryWeighted.length);
     const assetWeighted = this.applyAssetTypeWeight(boundaryWeighted);
     trace?.endStage(assetWeighted.length, assetWeighted.map(r => r.score));
 
-    // Apply length normalization (penalize long entries dominating via keyword density)
     trace?.startStage("length_norm", assetWeighted.length);
     const lengthNormalized = this.applyLengthNormalization(assetWeighted);
     trace?.endStage(lengthNormalized.length, lengthNormalized.map(r => r.score));
 
-    // Apply time decay (penalize stale entries)
     trace?.startStage("time_decay", lengthNormalized.length);
     const timeDecayed = this.applyTimeDecay(lengthNormalized);
     trace?.endStage(timeDecayed.length, timeDecayed.map(r => r.score));
@@ -1144,12 +1256,33 @@ export class MemoryRetriever {
     const frequencyBoosted = this.applyFrequencyBoost(hotnessBlended);
     trace?.endStage(frequencyBoosted.length, frequencyBoosted.map(r => r.score));
 
-    // Hard minimum score cutoff (post all scoring stages)
-    // P0.1: lower thresholds for short queries (shortQ declared earlier for fuseResults)
-    const rescored = [...frequencyBoosted].sort((a, b) => b.score - a.score);
+    // A1 error-signature 精确匹配 boost（flag 门控，默认 off → no-op、bit-identical）
+    return applyErrorSignatureBoost(frequencyBoosted, query);
+  }
+
+  /**
+   * Shared finalization tail — identical across both paths: sort → hard min →
+   * evolution-status filter → noise → RIF → MMR → version/cluster dedup →
+   * source diversity → limit. `shortQ` must be the value derived from the
+   * path's searchQuery (do not recompute from the raw query here).
+   */
+  private finalizeResults(
+    results: RetrievalResult[],
+    opts: {
+      shortQ: boolean;
+      minScoreOverride?: number;
+      includeArchived?: boolean;
+      limit: number;
+      trace?: TraceCollector;
+    },
+  ): RetrievalResult[] {
+    const { shortQ, minScoreOverride, includeArchived, limit, trace } = opts;
+    const rescored = [...results].sort((a, b) => b.score - a.score);
 
     trace?.startStage("hard_min_score", rescored.length);
-    const hardFiltered = rescored.filter(r => r.score >= this.minScoreFor(r.entry.category, shortQ));
+    const hardFiltered = minScoreOverride !== undefined
+      ? rescored
+      : rescored.filter(r => r.score >= this.minScoreFor(r.entry.category, shortQ));
     trace?.endStage(hardFiltered.length, hardFiltered.map(r => r.score));
 
     // Evolution status filter: exclude superseded/archived/consolidated memories
@@ -1157,11 +1290,14 @@ export class MemoryRetriever {
       ? hardFiltered
       : hardFiltered.filter(r => isActiveMemory(r.entry.metadata));
 
-    // Filter noise
-    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
@@ -1189,6 +1325,16 @@ export class MemoryRetriever {
     const final = diversified.slice(0, limit);
     trace?.endStage(final.length, final.map(r => r.score));
 
+    // P-omitted: 从 source-diversity 之前的候选池(clusterDeduped)算 limit 截断数。
+    // 若启用 sourceDiversity，applySourceDiversity 会先把 diversified 压到 limit，
+    // 用 diversified.length 会让 omitted 恒为 0（Codex 复审 P3-1，与 vector-only 同类）。
+    // 注意：clusterDeduped 仍可能含将被 retrieve 层 validity filter 过滤的 expired 项，
+    // 故 omitted 是“上界估计”，输出层用 "up to N" 措辞反映（P3-2）。
+    const omittedByLimit = Math.max(0, clusterDeduped.length - final.length);
+    if (omittedByLimit > 0) {
+      (final as RetrievalResultSet).omitted = { count: omittedByLimit, reason: "limit" };
+    }
+
     return final;
   }
 
@@ -1293,9 +1439,13 @@ export class MemoryRetriever {
           const objectScore = entityScoreMap.get(triple.object) ?? 0;
           const tripleScore = Math.max(subjectScore, objectScore) * triple.confidence;
 
-          if (tripleScore > 0 && triple.source_memory_id) {
-            const existing = memoryScoreMap.get(triple.source_memory_id) ?? 0;
-            memoryScoreMap.set(triple.source_memory_id, Math.max(existing, tripleScore));
+          if (tripleScore > 0) {
+            // All contributing memories share the fact's score — not just the
+            // first contributor (multi-source triples after mention counting)
+            for (const mid of parseSourceIds(triple.source_memory_ids, triple.source_memory_id)) {
+              const existing = memoryScoreMap.get(mid) ?? 0;
+              memoryScoreMap.set(mid, Math.max(existing, tripleScore));
+            }
           }
         }
       }
@@ -1648,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);
@@ -1718,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;
@@ -1736,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);
@@ -1751,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.
@@ -1767,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),
@@ -1831,8 +2016,10 @@ export class MemoryRetriever {
         const existingIds = new Set(results.map(r => r.entry.id));
         for (const n of neighborhood) {
           for (const t of n.triples) {
-            if (t.source_memory_id && !existingIds.has(t.source_memory_id)) {
-              sourceIds.add(t.source_memory_id);
+            // Expand through ALL contributing memories of each fact, not just
+            // the first contributor (multi-source triples after mention counting)
+            for (const mid of parseSourceIds(t.source_memory_ids, t.source_memory_id)) {
+              if (!existingIds.has(mid)) sourceIds.add(mid);
             }
           }
         }
@@ -1967,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));
@@ -1978,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),