recallnest 3.0.1 → 4.0.0

package/src/retriever.ts

@@ -1,14 +1,14 @@
 /**
  * Hybrid Retrieval System
- * Combines vector search + BM25 full-text search with RRF fusion
+ * Combines vector search + BM25 full-text search with weighted score fusion
  */
 
-import type { MemoryStore, MemorySearchResult } from "./store.js";
+import type { MemoryStore, MemorySearchResult, MemoryEntry } 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 { shouldSkipRetrievalFor } from "./adaptive-retrieval.js";
 import { expandQueryWithAliases } from "./aliases.js";
 import { expandQuery } from "./query-expander.js";
 import { detectLang, tokenizeFts } from "./language-hook.js";
@@ -16,7 +16,9 @@ import { type AccessTracker, computeHotnessScore, parseAccessMetadata } from "./
 import { readUtility } from "./memory-utility.js";
 import { weibullDecay, resolveTier, isDecayExempt, adjustHalfLifeForEmotion, computeArousalBoost } from "./decay-engine.js";
 import { logInfo, logWarn } from "./stderr-log.js";
-import { extractBoundaryMetadata, isDurableMemoryScope, isTranscriptScope } from "./memory-boundaries.js";
+import { matchesScopeFilter } from "./scope-policy.js";
+import type { TriggerStore, TriggerHit } from "./trigger-store.js";
+import { extractBoundaryMetadata, isDurableMemoryScope, isTranscriptScope, resolveExcludedScopes } from "./memory-boundaries.js";
 import type { TraceCollector } from "./retrieval-trace.js";
 import { extractTopicTag } from "./topic-tag.js";
 import { filterInterference } from "./rif.js";
@@ -24,7 +26,7 @@ import { FrequencyTracker } from "./frequency-tracker.js";
 import { applyConfidenceWeight } from "./confidence-tracker.js";
 import { deduplicateByVersionGroup } from "./version-manager.js";
 import { deduplicateByClusterInsight } from "./consolidation-engine.js";
-import { isActiveMemory, recordAccess as recordEvolutionAccess, parseEvolution, computeDecayScore } from "./memory-evolution.js";
+import { isActiveMemory, recordAccessOnMeta as recordEvolutionAccessOnMeta, parseEvolution, computeDecayScore } from "./memory-evolution.js";
 import {
   isMultiVectorEnabled,
   extractMultiVectorText,
@@ -125,6 +127,11 @@ export interface RetrievalConfig {
    * 注释不会有人定期回来读，那个条目每窗口都会被推到眼前。
    */
   utilityWeight: number;
+  /**
+   * γ：`RECALLNEST_POPULARITY_RANKING=bounded` 下链尾那一步流行度加成的上限，
+   * score × (1 + γ · h)，h ∈ [0,1]。legacy 下不读。（default: 0.2，第二步 plan §一.4）
+   */
+  popularityBonusMax: number;
   /**
    * Per-category score thresholds. When a result's category matches a key,
    * that threshold is used instead of hardMinScore. Categories not listed
@@ -173,6 +180,12 @@ export interface RetrievalContext {
    *  calls to prevent auto-recall from strengthening noise memories.
    *  Defaults to "manual" when unset (backward-compatible). */
   source?: "manual" | "auto-recall" | "cli";
+  /**
+   * Whether the trivial-query gate (shouldSkipRetrieval: greetings, command-like prefixes, short
+   * non-CJK phrases …) applies. Default: only when source is "auto-recall". Explicit searches that
+   * use source "auto-recall" just to avoid reinforcement writes pass false.
+   */
+  trivialQueryGate?: boolean;
   /** When false (default), archived records are excluded from results. */
   includeArchived?: boolean;
   /** Optional trace collector for per-stage pipeline observability. */
@@ -189,6 +202,11 @@ export interface RetrievalContext {
   validAt?: number;
   /** F3: When true, include expired memories (demoted 80%). Default: false. */
   includeExpired?: boolean;
+  /**
+   * Scopes kept out of the candidate pool (pushed down into the vector / BM25 queries). A category
+   * filter other than `events` also excludes the checkpoint-mirror scope — see resolveExcludedScopes.
+   */
+  excludeScopes?: string[];
 }
 
 export interface RetrievalResult extends MemorySearchResult {
@@ -200,6 +218,11 @@ export interface RetrievalResult extends MemorySearchResult {
     reranked?: { score: number };
     /** HP-narrative: true when this result was pulled as a narrative sibling */
     narrativeSibling?: boolean;
+    /**
+     * T-Mem 写入时预演触发器（2026-09-22）：经 trigger 到达或被 trigger 加强。
+     * text 只用于 explain（「为什么捞到」），不进 context 渲染——trigger 是入口不是证据。
+     */
+    trigger?: { score: number; cosine: number; text: string; admittedBy?: "hard" | "soft"; overlap?: number };
   };
 }
 
@@ -238,7 +261,10 @@ export const DEFAULT_CATEGORY_MIN_SCORES: Record<string, number> = {
 // 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 改回
+// 目标实测是死结（动 hotness 必伤靠 hotness 上位的记忆）。〔2026-09-25：这个死结现在有一条开关后的出路——
+// RECALLNEST_POPULARITY_RANKING=bounded 把三个流行度加成合成一步、只加不减、上限 +20%，快照上靠热度上位的
+// canary rebuild-pool 仍过（γ=0.1 时掉到第 5，所以取 0.2）；正式 shadow 之后 2026-09-25 切成默认，
+// 设 RECALLNEST_POPULARITY_RANKING=legacy 可回旧行为。见 sync-bridge AI产出/2026-09-24-recallnest-新条目排序/。〕hybrid 路径代码全保留，mode 改回
 // "hybrid" 即可切换（注：multiHopExpand 仍硬编码走 hybrid，默认 off，config.retrieval.multiHop
 // 开了会破纯 vector）。数据盲区：canary 全是语义 query，未覆盖 BM25 强项的精确关键词/token 召回
 // （变量名 / commit hash / alias-map 昵称）——待补 exact-token canary 验证。
@@ -278,6 +304,7 @@ export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
   timeDecayHalfLifeDays: 60,
   hotnessWeight: 0,
   utilityWeight: 0,
+  popularityBonusMax: 0.2,
 };
 
 /**
@@ -399,6 +426,21 @@ function applyAnchorBoost(results: RetrievalResult[], query: string): RetrievalR
   });
 }
 
+/**
+ * T-Mem triggers：hybrid 路径 rerank 之后的地板。cross-encoder 按「query 与正文像不像」打分，
+ * 而经 trigger 到达的宿主与 query 恰恰是零词面重合的——不设地板就等于把 T-Mem 自己要对抗的
+ * 相似度体制重新加回来（论文原话）。地板取 trigger 分的 0.9，只托底不抬头。
+ */
+const TRIGGER_FLOOR_FACTOR = 0.9;
+function applyTriggerFloor(results: RetrievalResult[]): RetrievalResult[] {
+  return results.map(r => {
+    const t = r.sources.trigger;
+    if (!t) return r;
+    const floor = t.score * TRIGGER_FLOOR_FACTOR;
+    return r.score >= floor ? r : { ...r, score: floor };
+  });
+}
+
 /** Multiplicative boost applied to a case on exact error-signature match. */
 const ERROR_SIGNATURE_BOOST_FACTOR = 1.5;
 
@@ -409,9 +451,18 @@ const ERROR_SIGNATURE_BOOST_FACTOR = 1.5;
  * (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.
+ *
+ * `clamp: false`（bounded 流行度下用）：不在这里截到 1——链尾的分数此时可以超过 1，
+ * 在这里截会把精确命中的 1.14 压成 1.00、排到未命中的 1.08 之后（第二步 R1 Codex C2）。
+ * 截平统一在 retrieve() 出口做。legacy 调用处不传参，行为不变。
  */
-export function applyErrorSignatureBoost(results: RetrievalResult[], query: string): RetrievalResult[] {
+export function applyErrorSignatureBoost(
+  results: RetrievalResult[],
+  query: string,
+  opts: { clamp?: boolean } = {},
+): RetrievalResult[] {
   if (!envConfig.errorSignatureBoost()) return results;
+  const clamp = opts.clamp ?? true;
   const querySignatures = extractErrorSignatures({ problem: query });
   if (querySignatures.length === 0) return results;
   const querySet = new Set(querySignatures.map(s => s.toLowerCase()));
@@ -421,7 +472,8 @@ export function applyErrorSignatureBoost(results: RetrievalResult[], query: stri
     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)) };
+    const boosted = r.score * ERROR_SIGNATURE_BOOST_FACTOR;
+    return { ...r, score: clamp ? Math.min(1, Math.max(0, boosted)) : Math.max(0, boosted) };
   });
 }
 
@@ -741,6 +793,7 @@ export class MemoryRetriever {
   private frequencyTracker?: FrequencyTracker;
   private auditLogger?: AuditLogger;
   private llmClient?: ReconstructionLLMClient;
+  private triggerStore?: TriggerStore;
   /**
    * Session-scoped suppression list (dopamine-inspired "do not disturb").
    * IDs in this set get a score penalty during retrieval but are NOT deleted.
@@ -764,6 +817,11 @@ export class MemoryRetriever {
     this.kgStore = kgStore;
   }
 
+  /** T-Mem triggers（2026-09-22）：挂上侧表后，检索多一条「经 trigger 到达」的入口。 */
+  setTriggerStore(triggerStore: TriggerStore): void {
+    this.triggerStore = triggerStore;
+  }
+
   /** P0.2: Attach a FrequencyTracker for hit-count based boosting. */
   setFrequencyTracker(tracker: FrequencyTracker): void {
     this.frequencyTracker = tracker;
@@ -810,9 +868,12 @@ export class MemoryRetriever {
   async retrieve(context: RetrievalContext): Promise<RetrievalResultSet> {
     const { query: rawQuery, limit, scopeFilter, category, includeArchived, trace, graph } = context;
     const safeLimit = clampInt(limit, 1, 20);
+    const excluded = resolveExcludedScopes(context);
+    const excludeScopes = excluded.length > 0 ? excluded : undefined;
 
-    // Adaptive retrieval: skip trivial queries to save embedding API calls
-    if (shouldSkipRetrieval(rawQuery)) {
+    // Adaptive retrieval: skip trivial queries to save embedding API calls — auto-recall only;
+    // explicit queries skip just empty / whitespace (see shouldSkipRetrievalFor).
+    if (shouldSkipRetrievalFor(context)) {
       return [];
     }
 
@@ -834,19 +895,19 @@ export class MemoryRetriever {
 
     // 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);
+      results = await this.vectorOnlyRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, undefined, excludeScopes);
     } else {
-      // Hybrid retrieval with vector + BM25 + RRF fusion (+ optional PPR graph)
-      results = await this.hybridRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, graph);
+      // Hybrid retrieval with vector + BM25 weighted score fusion (+ optional PPR graph)
+      results = await this.hybridRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, graph, undefined, excludeScopes);
     }
 
     // 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);
+        results = await this.vectorOnlyRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, 0, excludeScopes);
       } else {
-        results = await this.hybridRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, graph, 0);
+        results = await this.hybridRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, graph, 0, excludeScopes);
       }
     }
 
@@ -859,7 +920,7 @@ export class MemoryRetriever {
     // 字符串匹配，是 embedding 本质，跟语言无关）。普通词（mem0/recallnest/GitHub）不触发，日常
     // 语义召回不受影响。
     if (hasExactToken(rawQuery)) {
-      results = await this.supplementExactTokenWithBm25(query, results, safeLimit, scopeFilter, category, includeArchived);
+      results = await this.supplementExactTokenWithBm25(query, results, safeLimit, scopeFilter, category, includeArchived, excludeScopes);
     }
 
     // LME-2: Multi-hop retrieval — extract entities from first-pass results,
@@ -886,6 +947,14 @@ export class MemoryRetriever {
       });
     }
 
+    // 第二步（bounded 流行度）：检索器内部一律按原值排序，出口才截到 1——下游阈值与显示仍在 [0,1]。
+    // 必须在 BM25 补偿 / multiHop / topicTag / 有效期过滤之后：multiHopExpand 会按分数重排再截取，
+    // 截早了首轮 1.08 与跟进 1.14 都成 1.0、留下的是首轮那条（第二步 R3 Codex N2）。
+    // 也必须在下面挂 omitted / reconstruction 之前：那两个属性是之后才挂上的，这里 map 不会丢（R1 Agy A3）。
+    if (envConfig.popularityRanking() === "bounded" && results.length > 0) {
+      results = results.map(r => (r.score > 1 ? { ...r, score: 1 } : r));
+    }
+
     // P0.2: Record frequency hits for returned results (manual queries only)
     // Moved after topicTag filter so filtered-out entries are not reinforced.
     if (this.frequencyTracker && results.length > 0 && context.source !== "auto-recall") {
@@ -894,14 +963,15 @@ export class MemoryRetriever {
 
     // A-3: Record evolution access counts (async, non-blocking)
     // Moved after topicTag filter so filtered-out entries are not reinforced.
-    if (results.length > 0 && context.source !== "auto-recall" && this.store.update) {
+    // 2026-09-24：一批行在写锁内读最新元数据再加计数（patchMetadataBatch，一次提交）。原先拿检索时读到的元数据
+    // 整行 update 回去，检索与写回之间别的进程写下的状态（对账下架、dream 合并、GC 归档）会被旧值盖掉。
+    if (results.length > 0 && context.source !== "auto-recall" && typeof this.store.patchMetadataBatch === "function") {
+      const ids = results.map((r) => r.entry.id);
       Promise.resolve().then(async () => {
-        for (const r of results) {
-          try {
-            const updated = recordEvolutionAccess(r.entry.metadata);
-            await this.store.update!(r.entry.id, { metadata: updated });
-          } catch (err) { console.error("[recallnest] Evolution access tracking failed:", err instanceof Error ? err.message : String(err)); }
-        }
+        try {
+          const now = Date.now();
+          await this.store.patchMetadataBatch(ids.map((id) => ({ id, patchFn: (meta) => recordEvolutionAccessOnMeta(meta, now) })));
+        } catch (err) { console.error("[recallnest] Evolution access tracking failed:", err instanceof Error ? err.message : String(err)); }
       });
     }
 
@@ -989,10 +1059,11 @@ export class MemoryRetriever {
     scopeFilter?: string[],
     category?: string,
     includeArchived?: boolean,
+    excludeScopes?: string[],
   ): 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 bm25 = await this.runBM25Search(ftsQuery, Math.max(limit, 5), scopeFilter, category, includeArchived, excludeScopes);
     const vecIds = new Set(vectorResults.map(r => r.entry.id));
     const supplements = bm25
       .filter(b => !vecIds.has(b.entry.id))
@@ -1038,6 +1109,8 @@ export class MemoryRetriever {
         context.includeArchived,
         undefined, // no trace for follow-up
         context.graph,
+        undefined,
+        resolveExcludedScopes(context).length > 0 ? resolveExcludedScopes(context) : undefined,
       ).catch(() => [] as RetrievalResult[]),
     );
     const followUpResults = await Promise.all(followUpPromises);
@@ -1062,6 +1135,74 @@ export class MemoryRetriever {
       .slice(0, context.limit);
   }
 
+  /**
+   * T-Mem 写入时预演触发器召回（2026-09-22，借自腾讯 T-Mem / EMNLP 2026）。
+   *
+   * 用 query 向量搜 memory_triggers 侧表，命中的 trigger 把宿主拉进候选池：
+   * - 宿主已在候选里 → 分数取 max(原分, trigger 分)，并记 sources.trigger；
+   * - 宿主不在候选里 → 按 id 取回主表行，以 trigger 分入池（T-Mem 的「union 进候选、绕过相似度闸门」）。
+   * 之后照常走 applySharedScoring / finalizeResults——trigger 只决定「能不能到达」，不另起一套分。
+   * 硬闸 RECALLNEST_TRIGGER_GATE（余弦）防噪；侧表缺失或查询失败一律 fail-open 回原候选。
+   * category / archived / scope 三道过滤与主路径同款，trigger 不能越权。
+   */
+  private async applyTriggerRecall(
+    candidates: RetrievalResult[],
+    queryVector: number[],
+    queryText: string,
+    scopeFilter?: string[],
+    category?: string,
+    includeArchived?: boolean,
+    trace?: TraceCollector,
+  ): Promise<RetrievalResult[]> {
+    if (!this.triggerStore || !envConfig.triggerRecall()) return candidates;
+    trace?.startStage("trigger_recall", candidates.length);
+    let hits: TriggerHit[] = [];
+    try {
+      hits = await this.triggerStore.search(queryVector, envConfig.triggerTopK(), scopeFilter, {
+        minCosine: envConfig.triggerGate(),
+        softCosine: envConfig.triggerSoftGate(),
+        minOverlap: envConfig.triggerMinOverlap(),
+        minQueryTokens: envConfig.triggerSoftMinQueryTokens(),
+        queryText,
+      });
+    } catch (err) {
+      logWarn("trigger recall failed, continuing without it:", err);
+    }
+    if (hits.length === 0) {
+      trace?.endStage(candidates.length, candidates.map(r => r.score));
+      return candidates;
+    }
+    const byId = new Map(candidates.map((r, i) => [r.entry.id, i]));
+    const out = [...candidates];
+    for (const hit of hits) {
+      const triggerSource = { score: hit.score, cosine: hit.cosine, text: hit.text, admittedBy: hit.admittedBy, overlap: hit.overlap };
+      const idx = byId.get(hit.memoryId);
+      if (idx !== undefined) {
+        const existing = out[idx];
+        out[idx] = {
+          ...existing,
+          score: Math.max(existing.score, hit.score),
+          sources: { ...existing.sources, trigger: triggerSource },
+        };
+        continue;
+      }
+      let entry: MemoryEntry | null = null;
+      try {
+        entry = await this.store.getById(hit.memoryId);
+      } catch (err) {
+        logWarn(`trigger host lookup failed for ${hit.memoryId}:`, err);
+      }
+      if (!entry) continue;
+      if (!matchesScopeFilter(entry.scope, scopeFilter)) continue;
+      if (category && entry.category !== category) continue;
+      if (!includeArchived && parseMetadata(entry.metadata).archived === true) continue;
+      out.push({ entry, score: hit.score, sources: { trigger: triggerSource } });
+      byId.set(entry.id, out.length - 1);
+    }
+    trace?.endStage(out.length, out.map(r => r.score));
+    return out;
+  }
+
   private async vectorOnlyRetrieval(
     query: string,
     limit: number,
@@ -1070,6 +1211,7 @@ export class MemoryRetriever {
     includeArchived?: boolean,
     trace?: TraceCollector,
     minScoreOverride?: number,
+    excludeScopes?: string[],
   ): Promise<RetrievalResult[]> {
     // Temporal reasoning for vector-only mode
     const temporal = parseTemporalQuery(query);
@@ -1090,7 +1232,7 @@ export class MemoryRetriever {
     // 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);
+    const results = await this.store.vectorSearch(queryVector, fetchLimit, vectorMinScore, scopeFilter, undefined, excludeScopes);
     trace?.endStage(results.length, results.map(r => r.score));
 
     // Filter by category if specified
@@ -1118,7 +1260,10 @@ export class MemoryRetriever {
     // P0.1: Anchor boost for vector-only path
     const anchorBoosted = applyAnchorBoost(mapped, searchQuery);
 
-    const scored = this.applySharedScoring(anchorBoosted, query, trace);
+    // T-Mem triggers：联想入口在这里并入候选（相似度那一步之后、打分链之前）
+    const withTriggers = await this.applyTriggerRecall(anchorBoosted, queryVector, searchQuery, scopeFilter, category, includeArchived, trace);
+
+    const scored = this.applySharedScoring(withTriggers, query, trace);
 
     // Session suppression: temporarily penalize "do not disturb" memories (vector-only path)
     const afterSuppression = this.applySessionSuppression(scored);
@@ -1141,6 +1286,7 @@ export class MemoryRetriever {
     trace?: TraceCollector,
     graph?: boolean,
     minScoreOverride?: number,
+    excludeScopes?: string[],
   ): Promise<RetrievalResult[]> {
     // Adaptive pool: widen candidate pool for aggregation queries ("how many", "all the")
     const multiplier = (this.config.adaptivePoolMultiplier ?? 1) > 1 && isAggregationQuery(query)
@@ -1170,8 +1316,8 @@ export class MemoryRetriever {
 
     trace?.startStage("vector_search", 0);
     const [vectorResults, bm25Results, pprResults] = await Promise.all([
-      this.runVectorSearch(queryVector, candidatePoolSize, scopeFilter, category, includeArchived),
-      this.runBM25Search(ftsQuery, candidatePoolSize, scopeFilter, category, includeArchived),
+      this.runVectorSearch(queryVector, candidatePoolSize, scopeFilter, category, includeArchived, excludeScopes),
+      this.runBM25Search(ftsQuery, candidatePoolSize, scopeFilter, category, includeArchived, excludeScopes),
       pprPromise,
     ]);
     trace?.endStage(vectorResults.length, vectorResults.map(r => r.score));
@@ -1181,6 +1327,7 @@ export class MemoryRetriever {
 
     // Fuse results using weighted score fusion (async: validates BM25-only entries exist in store)
     const shortQ = isShortQuery(searchQuery);
+    // Stage name "rrf_fusion" is historical and kept for log compatibility; fuseResults() does weighted score fusion, not RRF.
     trace?.startStage("rrf_fusion", vectorResults.length + bm25Results.length + pprResults.length);
     const fusedResults = await this.fuseResults(vectorResults, bm25Results, pprResults, shortQ);
     trace?.endStage(fusedResults.length, fusedResults.map(r => r.score));
@@ -1202,8 +1349,11 @@ export class MemoryRetriever {
     const anchorBoosted = applyAnchorBoost(multiVecBlended, searchQuery);
     trace?.endStage(anchorBoosted.length, anchorBoosted.map(r => r.score));
 
+    // T-Mem triggers：联想入口并入候选，在 min_score / rerank 之前
+    const withTriggers = await this.applyTriggerRecall(anchorBoosted, queryVector, searchQuery, scopeFilter, category, includeArchived, trace);
+
     // Apply minimum score threshold
-    trace?.startStage("min_score_filter", anchorBoosted.length);
+    trace?.startStage("min_score_filter", withTriggers.length);
     // P0.1: Lower minScore for short queries to widen the candidate pool;
     // minScoreOverride 用于 retrieve() 顶层的 0-hit fallback retry。
     const effectiveMinScore = minScoreOverride !== undefined
@@ -1211,7 +1361,7 @@ export class MemoryRetriever {
       : (isShortQuery(searchQuery)
           ? this.config.minScore * SHORT_QUERY_MIN_SCORE_FACTOR
           : this.config.minScore);
-    const filtered = anchorBoosted.filter(r => r.score >= effectiveMinScore);
+    const filtered = withTriggers.filter(r => r.score >= effectiveMinScore);
     trace?.endStage(filtered.length, filtered.map(r => r.score));
 
     // Rerank if enabled
@@ -1221,7 +1371,10 @@ export class MemoryRetriever {
       : filtered;
     trace?.endStage(reranked.length, reranked.map(r => r.score));
 
-    const scored = this.applySharedScoring(reranked, query, trace);
+    // T-Mem triggers：rerank 是相似度打分，经 trigger 到达的宿主要托底
+    const triggerFloored = applyTriggerFloor(reranked);
+
+    const scored = this.applySharedScoring(triggerFloored, query, trace, TRIGGER_FLOOR_FACTOR);
 
     return this.finalizeResults(scored, {
       shortQ,
@@ -1238,11 +1391,69 @@ export class MemoryRetriever {
    * `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.
+   *
+   * `triggerPathBase`：开关 2 下「trigger 那一路」以 trigger 分的多少倍为底——vector 路径 1；
+   * hybrid 路径传 TRIGGER_FLOOR_FACTOR，与 applyTriggerFloor 给 rerank 之后托的底同口径。
    */
   private applySharedScoring(
     results: RetrievalResult[],
     query: string,
     trace?: TraceCollector,
+    triggerPathBase = 1,
+  ): RetrievalResult[] {
+    const assetWeighted = this.applyPreLengthStages(results, query, trace);
+
+    trace?.startStage("length_norm", assetWeighted.length);
+    const normalized = this.applyLengthNormalization(assetWeighted);
+    // 开关 2（2026-09-25 起默认开；设 false 时原样）：trigger 那一路不做长度归一，与正文那一路取大
+    const lengthNormalized = envConfig.triggerLengthExempt()
+      ? this.applyTriggerPathFloor(normalized, results, query, triggerPathBase)
+      : normalized;
+    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);
+
+    if (envConfig.popularityRanking() === "bounded") {
+      // 流行度只进排序、只加不减、有上限、只读一个计数器、只施加一次（第二步 plan §零.1）：
+      // 下面 legacy 的访问计数加成、热度混合、频次加成三环都不跑。这一环与错误指纹加成都不截平，
+      // 分数可以超过 1——检索器内部按原值排序，retrieve() 出口才截到 1。
+      trace?.startStage("popularity_bonus", evolutionBlended.length);
+      const bonused = this.applyPopularityBonus(evolutionBlended);
+      trace?.endStage(bonused.length, bonused.map(r => r.score));
+      return applyErrorSignatureBoost(bonused, query, { clamp: false });
+    }
+
+    // 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));
+
+    // A1 error-signature 精确匹配 boost（flag 门控，默认 off → no-op、bit-identical）
+    return applyErrorSignatureBoost(frequencyBoosted, query);
+  }
+
+  /**
+   * 长度归一之前的 7 个环节（新近度 → importance → utility → confidence → emotion → boundary →
+   * 资产类型），从 applySharedScoring 原样挪出来，顺序与 trace 调用逐字不变。单独成方法是为了
+   * 开关 2 能让「trigger 那一路」走完全相同的前置环节（applyTriggerPathFloor，不带 trace）。
+   */
+  private applyPreLengthStages(
+    results: RetrievalResult[],
+    query: string,
+    trace?: TraceCollector,
   ): RetrievalResult[] {
     trace?.startStage("recency_boost", results.length);
     const boosted = this.applyRecencyBoost(results);
@@ -1278,32 +1489,59 @@ export class MemoryRetriever {
     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));
+    return assetWeighted;
+  }
 
-    // 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));
+  /**
+   * 开关 2（RECALLNEST_TRIGGER_LENGTH_EXEMPT）：trigger 那一路不做长度归一。
+   *
+   * 带 sources.trigger 的条目另算「只靠 trigger 这一路会是多少分」：以 trigger 分 × base 为底，
+   * 不带 trace 走一遍与正文完全相同的前置环节，不做长度归一；长度归一后的分数取两路较大。
+   * 它的相关度来自那句短 trigger、不来自正文，所以不该按正文长度打折。
+   *
+   * 不用「长度系数取 max(原系数, trigger 分 / 并入后分数)」（第二步 v2 的写法）：长度归一之前有
+   * 新近度加法，终分 ≈ (B + r)·M·T/B，向量分 B 变大时反而下降（R3 Codex 实测 0.79→0.81 终分降），
+   * 而且得往 sources 记占比、从 API 原样漏出去。两路各自对向量分、trigger 分单调，取大仍单调。
+   */
+  private applyTriggerPathFloor(
+    normalized: RetrievalResult[],
+    original: RetrievalResult[],
+    query: string,
+    base: number,
+  ): RetrievalResult[] {
+    const twins: RetrievalResult[] = [];
+    for (const r of original) {
+      const t = r.sources.trigger;
+      if (t) twins.push({ ...r, score: t.score * base });
+    }
+    if (twins.length === 0) return normalized;
+    const triggerPath = new Map(this.applyPreLengthStages(twins, query).map(r => [r.entry.id, r.score]));
+    return normalized
+      .map(r => {
+        const floor = triggerPath.get(r.entry.id);
+        return floor !== undefined && floor > r.score ? { ...r, score: floor } : r;
+      })
+      .sort((a, b) => b.score - a.score);
+  }
 
-    // A1 error-signature 精确匹配 boost（flag 门控，默认 off → no-op、bit-identical）
-    return applyErrorSignatureBoost(frequencyBoosted, query);
+  /**
+   * bounded 流行度（第二步 plan §零.1）：score × (1 + γ·h)，h = min(1, log2(1 + evolution.accessCount) / 5)。
+   * 只读 evolution.accessCount——每次 manual 检索的每条返回都 +1、写锁内读改写、库内持久；
+   * 频次台账（跨进程丢更新）与顶层 accessCount 都不读。零访问 h = 0 原样放行，只加不减，不截平。
+   * # simplified: 31 次封顶的对数饱和、不看时间；要按「最近常用」加权再换成带衰减的计数（§一.4）
+   */
+  private applyPopularityBonus(results: RetrievalResult[]): RetrievalResult[] {
+    const raw = this.config.popularityBonusMax;
+    const gamma = Math.max(0, Number.isFinite(raw) ? raw : 0);
+    if (gamma <= 0) return results;
+    return results.map(r => {
+      const n: unknown = parseEvolution(r.entry.metadata, r.entry.timestamp).accessCount;
+      // parseEvolution 不校验类型：元数据里的计数若是字符串 / 负数 / 非有限数，一律按零访问。
+      // 这一环不截平，NaN 会一路漏到出口（legacy 那几环有 clamp01 的非有限兜底，这里没有；第二步实现互审 Codex 实测 "broken" → NaN%）
+      if (typeof n !== "number" || !Number.isFinite(n) || n <= 0) return r;
+      const h = Math.min(1, Math.log2(1 + n) / 5);
+      return { ...r, score: r.score * (1 + gamma * h) };
+    });
   }
 
   /**
@@ -1390,10 +1628,11 @@ export class MemoryRetriever {
     scopeFilter?: string[],
     category?: string,
     includeArchived?: boolean,
+    excludeScopes?: string[],
   ): Promise<Array<MemorySearchResult & { rank: number }>> {
     let results: MemorySearchResult[];
     try {
-      results = await this.store.vectorSearch(queryVector, limit, 0.1, scopeFilter);
+      results = await this.store.vectorSearch(queryVector, limit, 0.1, scopeFilter, undefined, excludeScopes);
     } catch (err) {
       // Fail-open: log warning and continue with empty results (backport from v1.0.30)
       logWarn("vectorSearch failed, continuing with empty results:", err);
@@ -1422,8 +1661,9 @@ export class MemoryRetriever {
     scopeFilter?: string[],
     category?: string,
     includeArchived?: boolean,
+    excludeScopes?: string[],
   ): Promise<Array<MemorySearchResult & { rank: number }>> {
-    const results = await this.store.bm25Search(query, limit, scopeFilter);
+    const results = await this.store.bm25Search(query, limit, scopeFilter, excludeScopes);
 
     // Filter by category if specified
     const afterCategory = category

package/src/retroactive-boost.ts

@@ -142,12 +142,13 @@ export async function retroactiveBoost(
       meta.tier = "working";
     }
 
-    await store.update(entry.id, {
+    const boosted = await store.update(entry.id, {
       importance: newImportance,
       metadata: JSON.stringify(meta),
     }, [newEntry.scope]);
 
-    boostedIds.push(entry.id);
+    // update() 返回 null = 这一行在检索之后被删掉了，没有提权成，不计入
+    if (boosted) boostedIds.push(entry.id);
   }
 
   return {

package/src/runtime-config.ts

@@ -6,6 +6,7 @@ import { metaDir } from "./compat.js";
 import { MemoryStore, validateStoragePath } from "./store.js";
 import { createEmbedder, getVectorDimensions, type EmbeddingConfig } from "./embedder.js";
 import { createRetriever, type RetrievalConfig, DEFAULT_RETRIEVAL_CONFIG } from "./retriever.js";
+import { TriggerStore } from "./trigger-store.js";
 import { applyRetrievalProfile } from "./retrieval-profiles.js";
 import { AccessTracker } from "./access-tracker.js";
 import { createAuditLogger } from "./audit-log.js";
@@ -182,6 +183,10 @@ export function createComponents(config: LocalMemoryConfig, profileName?: string
   const { profile, config: retrieverConfig } = applyRetrievalProfile(baseRetrievalConfig, profileName);
   const retriever = createRetriever(store, embedder, retrieverConfig);
 
+  // T-Mem triggers（2026-09-22）：侧表与主表同库同 dim；挂到 retriever 后检索多一条联想入口
+  const triggerStore = new TriggerStore({ dbPath, vectorDim: embedder.dimensions });
+  retriever.setTriggerStore(triggerStore);
+
   // Attach access tracker for reinforcement-based decay
   const accessTracker = new AccessTracker(store);
   accessTracker.registerExitFlush();
@@ -220,7 +225,7 @@ export function createComponents(config: LocalMemoryConfig, profileName?: string
     }
   }
 
-  return { store, embedder, retriever, profile, accessTracker, frequencyTracker, llm };
+  return { store, embedder, retriever, profile, accessTracker, frequencyTracker, llm, triggerStore };
 }
 
 export function createStoreOnly(config: LocalMemoryConfig): MemoryStore {