recallnest 2.3.0 → 2.5.4

package/src/retriever.ts

@@ -6,7 +6,10 @@
 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";
@@ -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,
@@ -189,6 +194,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,13 +220,21 @@ 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,
@@ -227,6 +246,30 @@ export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
   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 {
+  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 +357,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 +737,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,14 +766,18 @@ 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[];
 
     // For vector-only mode, use legacy behavior
@@ -705,6 +788,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 +878,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 +899,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 +909,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 +1001,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 +1009,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 +1050,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));
+    const scored = this.applySharedScoring(anchorBoosted, query, trace);
 
-    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));
+    // Session suppression: temporarily penalize "do not disturb" memories (vector-only path)
+    const afterSuppression = this.applySessionSuppression(scored);
 
-    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;
-
-    trace?.startStage("final_limit", diversified.length);
-    const final = diversified.slice(0, limit);
-    trace?.endStage(final.length, final.map(r => r.score));
-
-    return final;
+    return this.finalizeResults(afterSuppression, {
+      shortQ,
+      minScoreOverride,
+      includeArchived,
+      limit,
+      trace,
+    });
   }
 
   private async hybridRetrieval(
@@ -1007,6 +1072,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 +1136,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 +1153,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);
+
+    return this.finalizeResults(scored, {
+      shortQ,
+      minScoreOverride,
+      includeArchived,
+      limit,
+      trace,
+    });
+  }
+
+  /**
+   * 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));
 
-    // Apply importance weighting
-    trace?.startStage("importance_weight", temporalReranked.length);
-    const importanceWeighted = this.applyImportanceWeight(temporalReranked);
-    trace?.endStage(importanceWeighted.length, importanceWeighted.map(r => r.score));
+    trace?.startStage("importance_weight", boosted.length);
+    const weighted = this.applyImportanceWeight(boosted);
+    trace?.endStage(weighted.length, weighted.map(r => r.score));
 
-    // Viewpoint confidence: penalize corrected/contradicted memories
-    trace?.startStage("confidence_weight", importanceWeighted.length);
-    const confidenceWeighted = this.applyConfidence(importanceWeighted);
+    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 +1228,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,7 +1262,6 @@ export class MemoryRetriever {
       ? hardFiltered
       : hardFiltered.filter(r => isActiveMemory(r.entry.metadata));
 
-    // Filter noise
     trace?.startStage("noise_filter", evolutionFiltered.length);
     const denoised = this.config.filterNoise
       ? filterNoise(evolutionFiltered, r => r.entry.text)
@@ -1189,6 +1293,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 +1407,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));
+            }
           }
         }
       }
@@ -1831,8 +1949,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);
             }
           }
         }

package/src/runtime-config.ts

@@ -11,6 +11,7 @@ import { AccessTracker } from "./access-tracker.js";
 import { FrequencyTracker } from "./frequency-tracker.js";
 import { createLLMClient, type LLMClient, type LLMConfig } from "./llm-client.js";
 import { logInfo } from "./stderr-log.js";
+import * as envConfig from "./env-config.js";
 
 export type RecallMode = "full" | "light" | "summary" | "off";
 
@@ -33,6 +34,12 @@ export interface LocalMemoryConfig {
   };
   sources: Record<string, { path: string; glob: string; description: string }>;
   retrieval?: Partial<RetrievalConfig>;
+  /**
+   * Opt-in cross-scope sidecar map for search_memory.
+   * Main scoped search remains isolated; callers must pass includeRelatedScopes
+   * before configured related scopes are queried and shown separately.
+   */
+  scopeRelations?: Record<string, string[]>;
   /**
    * Default depth for auto-recall injection.
    * - "full": inject complete text (default, backward compatible)
@@ -179,7 +186,7 @@ export function resolveRecallMode(config: LocalMemoryConfig, perCallOverride?: s
   if (perCallOverride && VALID_RECALL_MODES.includes(perCallOverride as RecallMode)) {
     return perCallOverride as RecallMode;
   }
-  const envMode = process.env.RECALLNEST_RECALL_MODE;
+  const envMode = envConfig.recallModeRaw();
   if (envMode && VALID_RECALL_MODES.includes(envMode as RecallMode)) {
     return envMode as RecallMode;
   }