recallnest 2.6.1 → 3.0.1

package/src/retriever.ts

@@ -13,6 +13,7 @@ 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 { 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";
@@ -39,7 +40,7 @@ import { isKGModeEnabled } from "./kg-extractor.js";
 import { detectEntities } from "./query-entity-detector.js";
 import { buildGraph, pprTraverse } from "./ppr-traversal.js";
 import { logInfo } from "./stderr-log.js";
-import type { AuditLogger } from "./audit-log.js";
+import { AUDIT_RETRIEVED_CAP, type AuditLogger } from "./audit-log.js";
 import { parseEmotion, isEmotionScoringEnabled } from "./memory-schema.js";
 import { parseNarrative, isNarrativeModeEnabled } from "./narrative-schema.js";
 import type { EmotionMetadata } from "./memory-schema.js";
@@ -111,6 +112,19 @@ export interface RetrievalConfig {
    * 0 = disabled (default), 0.15 = recommended.
    */
   hotnessWeight: number;
+  /**
+   * Utility weight — 价值回溯（memory-utility.ts）算出的效用值对最终分的影响强度。
+   * Formula: score *= 1 + utilityWeight * utility，utility ∈ [-0.8, 0.8]。
+   * 与 hotness/frequency 的区别在信号来源：那两个数「被读过多少次」，
+   * 这个数「被用到的那些任务成没成」——前者是热度，后者是因果贡献。
+   * 没有 utility 的条目分数原样不动（bonus-only 冷启动，不惩罚没数据的）。
+   *
+   * 0 = disabled（默认）。**默认关是有意的影子期**：目前生产库里带 join key 的
+   * observation 从 0 开始积累，样本不足时开启只会放大噪声。
+   * 升级条件写在 open-loops「MemOS 价值回溯」条目里，不在这行注释里——
+   * 注释不会有人定期回来读，那个条目每窗口都会被推到眼前。
+   */
+  utilityWeight: number;
   /**
    * Per-category score thresholds. When a result's category matches a key,
    * that threshold is used instead of hardMinScore. Categories not listed
@@ -234,6 +248,15 @@ export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
   bm25Weight: 0.3,
   minScore: 0.3,
   rerank: "cross-encoder",
+  // ⚠️ 2026-08-23 查实：**这里超过 20 的部分从来没生效过**。两条候选腿最终都落到
+  // store.ts 的 `clampInt(limit, 1, 20)`（vectorSearch:588 / bm25Search:643），
+  // 路径是 retriever.ts:1109 算出 ceil(candidatePoolSize × multiplier) →
+  // runVectorSearch/runBM25Search(:1341/:1373) → store.*Search(limit) → 被压成 20。
+  // 那个 clamp 从初始提交 c10607a（2026-03-03）就在，而 07-16 调参（9374a4f）只改了本文件、
+  // 没碰 store.ts —— 所以这个 30 从落地当天就是空转。retrieval-profiles.ts 的 24/26/28 同理。
+  // **不要顺手去改那个 clamp**：动它等于扩候选池，而扩池方案已于 2026-08-22 跑 shadow 后被
+  // 实测否决（RecallNest memory:pivot `rejected-recall-widen-candidate-pool`，主犯认定订正为
+  // applyLayerAdmission 79.4% 而非 hard_min 13.5%）。要推翻它得先拿出那条否决记录要求的新证据。
   candidatePoolSize: 30,
   sourceDiversity: 1,
   recencyHalfLifeDays: 14,
@@ -254,6 +277,7 @@ export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
   hardMinScore: 0.35,
   timeDecayHalfLifeDays: 60,
   hotnessWeight: 0,
+  utilityWeight: 0,
 };
 
 /**
@@ -894,12 +918,28 @@ export class MemoryRetriever {
 
     // F-1: Audit log — record retrieve operation (non-blocking, silent on failure)
     try {
-      this.auditLogger?.log({
-        operation: "retrieve",
-        scope: context.scopeFilter?.[0],
-        actor: context.source || "manual",
-        details: `query="${context.query.slice(0, 80)}" hits=${results.length}`,
-      });
+      if (this.auditLogger) {
+        const retrieved = results.slice(0, AUDIT_RETRIEVED_CAP).map((r) => {
+          const evo = parseEvolution(r.entry.metadata, r.entry.timestamp);
+          const boundary = extractBoundaryMetadata(r.entry.metadata);
+          return {
+            id: r.entry.id.slice(0, 8),
+            rev: evo.version,
+            st: evo.status,
+            ...(boundary?.layer ? { ly: boundary.layer } : {}),
+            ...(boundary?.authority ? { au: boundary.authority } : {}),
+          };
+        });
+        this.auditLogger.log({
+          operation: "retrieve",
+          scope: context.scopeFilter?.[0],
+          actor: context.source || "manual",
+          details: `query="${context.query.slice(0, 80)}" hits=${results.length}`,
+          ...(retrieved.length > 0 ? { retrieved } : {}),
+          // Only when the list is short of the truth — a truncated list must look truncated.
+          ...(results.length > retrieved.length ? { retrievedTotal: results.length } : {}),
+        });
+      }
     } catch {
       // Audit must never block retrieval
     }
@@ -1212,8 +1252,14 @@ export class MemoryRetriever {
     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);
+    // 价值回溯：紧跟 importance 之后，因为两者回答的是同一类问题（这条本身有多值得），
+    // 只是 importance 说的是「存的时候认为多重要」，utility 说的是「用起来结果怎么样」。
+    trace?.startStage("utility_weight", weighted.length);
+    const utilityWeighted = this.applyUtilityWeight(weighted);
+    trace?.endStage(utilityWeighted.length, utilityWeighted.map(r => r.score));
+
+    trace?.startStage("confidence_weight", utilityWeighted.length);
+    const confidenceWeighted = this.applyConfidence(utilityWeighted);
     trace?.endStage(confidenceWeighted.length, confidenceWeighted.map(r => r.score));
 
     let afterEmotionVector = confidenceWeighted;
@@ -2163,6 +2209,33 @@ export class MemoryRetriever {
    *
    * No-op when hotnessWeight is 0 or AccessTracker is absent.
    */
+  /**
+   * 价值回溯加权：被用在成功任务里的记忆上浮，被用在失败任务里的下沉。
+   *
+   * 这是 utility 唯一的消费点——它**只喂排序**，不进 tier、不进 decay 豁免、
+   * 更不写回 importance（那一列是阈值语义，≥0.95 会触发永久免衰减，
+   * 详见 memory-utility.ts 抬头的三条理由）。
+   *
+   * No-op when utilityWeight is 0（默认）或条目没有 utility。
+   */
+  private applyUtilityWeight(results: RetrievalResult[]): RetrievalResult[] {
+    const raw = this.config.utilityWeight;
+    const weight = Math.min(1, Math.max(0, Number.isFinite(raw) ? raw : 0));
+    if (weight <= 0) return results;
+
+    const weighted = results.map((r) => {
+      const utility = readUtility(r.entry.metadata);
+      if (utility === null) return r; // 没数据 ≠ 中性差评，原样放行
+      const factor = 1 + weight * utility;
+      return {
+        ...r,
+        score: clamp01(r.score * factor, 0),
+      };
+    });
+
+    return weighted.sort((a, b) => b.score - a.score);
+  }
+
   private applyHotnessBlend(results: RetrievalResult[]): RetrievalResult[] {
     const raw = this.config.hotnessWeight;
     const alpha = Math.min(1, Math.max(0, Number.isFinite(raw) ? raw : 0));

package/src/runtime-config.ts

@@ -27,6 +27,11 @@ export interface LocalMemoryConfig {
     dimensions?: number;
     taskQuery?: string;
     taskPassage?: string;
+    /**
+     * Per-request timeout (ms) for the embedding client. Omit to keep the SDK default
+     * (600s in openai v7); `RECALLNEST_EMBEDDING_TIMEOUT_MS` overrides this.
+     */
+    timeoutMs?: number;
   };
   llm?: {
     apiKey: string;
@@ -156,6 +161,10 @@ export function createComponents(config: LocalMemoryConfig, profileName?: string
     dimensions: config.embedding.dimensions,
     taskQuery: config.embedding.taskQuery,
     taskPassage: config.embedding.taskPassage,
+    // Env wins over config.json so a single deployment can bound its embed calls
+    // without editing the shared file. Both unset → no `timeout` reaches the SDK,
+    // which is the behavior every release through v3.0.0 had.
+    timeoutMs: envConfig.embeddingTimeoutMs() ?? config.embedding.timeoutMs,
   };
 
   const embedder = createEmbedder(embeddingConfig);

package/src/scope-policy.ts

@@ -38,8 +38,29 @@ export function resolveSessionScope(sessionId?: string): string | undefined {
   return normalized ? `session:${normalized}` : undefined;
 }
 
-export function matchesScopeFilter(rowScope: string, scopeFilter?: string[]): boolean {
+/**
+ * scope 过滤的匹配模式（2026-08-16 加，互审 C1/K3 双方独立命中）。
+ *
+ * - `family`（默认，历史行为）：**由 scope 字符串里有没有冒号隐式决定** —— 含冒号走精确，
+ *   不含冒号走前缀。`search_memory` 等靠它做 `project` → `project:*` 的家族匹配。
+ * - `exact`：调用方明说"我给的就是一个具体 scope 名"，一律精确匹配。
+ *
+ * 为什么要显式模式：隐式规则在调用方**拿真实 scope 名当参数**时会失效——真实 scope 名
+ * 里恰好没有冒号（`memory` / `cc` / `global`），于是被当成 family selector。
+ * 实测后果：weekly `dream --scope memory` 借前缀把 `memory:pivot`（手写提炼层）
+ * 一起卷进同一轮聚类，14 条 insight 的来源横跨两个 scope（2026-08-16 查库坐实）。
+ * 修法不是改默认语义（会伤 search_memory），是让 dream 这类"喂具体 scope 名"的
+ * 入口显式声明 exact。
+ */
+export type ScopeMatchMode = "exact" | "family";
+
+export function matchesScopeFilter(
+  rowScope: string,
+  scopeFilter?: string[],
+  mode: ScopeMatchMode = "family",
+): boolean {
   if (!scopeFilter || scopeFilter.length === 0) return true;
+  if (mode === "exact") return scopeFilter.some((scope) => rowScope === scope);
   return scopeFilter.some((scope) => scope.includes(":") ? rowScope === scope : rowScope.startsWith(scope));
 }
 

package/src/session-engine.ts

@@ -8,6 +8,14 @@ import {
 } from "./session-schema.js";
 import { buildIdempotentRecordId } from "./idempotency.js";
 
+/** 当 summary 里每一句都被 repo-state 规则滤掉时的兜底文案（单一来源，勿再字面重复）。 */
+export const FALLBACK_SUMMARY = "Checkpoint captured current task state without repo-state details.";
+
+/** summary 是否已退化成兜底文案——即「本来写了东西，但整段被清洗空了」。 */
+export function isFallbackSummary(summary: string | null | undefined): boolean {
+  return (summary ?? "").trim() === FALLBACK_SUMMARY;
+}
+
 const REPO_STATE_PATTERN = /\bgit status\b|未提交|staged|uncommitted|已修改文件|modified files?|untracked|新增文件|dirty repo|dirty worktree/iu;
 const SENTENCE_SPLIT_PATTERN = /(?:\r?\n)+|(?<=[。！？!?;；])\s+/u;
 const CHECKPOINT_SANITIZABLE_FIELDS = ["summary", "task", "decisions", "openLoops", "nextActions"] as const;
@@ -51,7 +59,7 @@ function sanitizeCheckpointSummary(summary: string): SanitizedStringResult {
     .map(normalizeCheckpointText)
     .filter(Boolean);
   const kept = parts.filter((part) => !hasRepoStateText(part));
-  const value = kept[0] ? kept.join(" ") : "Checkpoint captured current task state without repo-state details.";
+  const value = kept[0] ? kept.join(" ") : FALLBACK_SUMMARY;
   return {
     value,
     changed: kept.length !== parts.length,
@@ -146,13 +154,12 @@ export function buildSessionCheckpointResult(rawInput: unknown): SessionCheckpoi
     resolvedScope: resolveCheckpointScope(sanitizedInput),
   });
 
-  const FALLBACK_SUMMARY = "Checkpoint captured current task state without repo-state details.";
-  const isFallbackSummary = record.summary === FALLBACK_SUMMARY;
+  const summaryIsFallback = isFallbackSummary(record.summary);
   const hasStructuredContent =
     record.decisions.length > 0 ||
     record.openLoops.length > 0 ||
     record.nextActions.length > 0;
-  const quality: CheckpointQuality = isFallbackSummary && !hasStructuredContent ? "minimal" : "rich";
+  const quality: CheckpointQuality = summaryIsFallback && !hasStructuredContent ? "minimal" : "rich";
 
   return {
     record,

package/src/session-output.ts

@@ -1,5 +1,7 @@
 import type { ResumeContextResponse, SessionCheckpointRecord } from "./session-schema.js";
 import { cleanText } from "./context-composer-text.js";
+import { formatIsoAgeLabel } from "./age-label.js";
+import { isFallbackSummary } from "./session-engine.js";
 
 function listBlock(label: string, items: string[]): string[] {
   if (items.length === 0) return [];
@@ -11,7 +13,14 @@ function listBlock(label: string, items: string[]): string[] {
 
 export function formatCheckpointRecallSummary(record: SessionCheckpointRecord): string {
   const parts: string[] = [];
-  const baseSummary = record.summary.trim();
+  const rawSummary = record.summary.trim();
+  // summary 整段被 repo-state 清洗规则滤空时会退化成兜底文案，headline 就只剩一句无信息的
+  // 套话。此时改用第一条实质内容顶上，并保留标记，让读者能分辨「本来就没写」和「被洗掉了」。
+  const substitute = isFallbackSummary(rawSummary)
+    ? [...record.decisions, ...record.nextActions, ...record.openLoops]
+        .find((item) => item.trim().length > 0) ?? ""
+    : "";
+  const baseSummary = substitute ? `[summary sanitized] ${substitute}` : rawSummary;
   if (baseSummary) {
     parts.push(baseSummary);
   }
@@ -32,7 +41,7 @@ export function formatCheckpointSaved(record: SessionCheckpointRecord): string {
     `Checkpoint ${record.checkpointId.slice(0, 8)}`,
     `Session: ${record.sessionId}`,
     `Scope: ${record.resolvedScope}`,
-    `Updated: ${record.updatedAt}`,
+    `Updated: ${record.updatedAt} (${formatIsoAgeLabel(record.updatedAt)})`,
     `Summary: ${record.summary}`,
     ...listBlock("Decisions", record.decisions),
     ...listBlock("Open loops", record.openLoops),
@@ -48,7 +57,7 @@ export function formatCheckpointSummary(record: SessionCheckpointRecord | null):
     `Latest checkpoint`,
     `Session: ${record.sessionId}`,
     `Scope: ${record.resolvedScope}`,
-    `Updated: ${record.updatedAt}`,
+    `Updated: ${record.updatedAt} (${formatIsoAgeLabel(record.updatedAt)})`,
     `Summary: ${record.summary}`,
   ];
   if (record.nextActions.length > 0) {
@@ -123,7 +132,7 @@ export function formatResumeContext(response: ResumeContextResponse): string {
     if (response.latestCheckpoint.resolvedScope) {
       lines.push(`Scope: ${response.latestCheckpoint.resolvedScope}`);
     }
-    lines.push(`Updated: ${response.latestCheckpoint.updatedAt}`);
+    lines.push(`Updated: ${response.latestCheckpoint.updatedAt} (${formatIsoAgeLabel(response.latestCheckpoint.updatedAt)})`);
     lines.push(`Summary: ${response.latestCheckpoint.summary}`);
   }
 

package/src/session-store.ts

@@ -4,12 +4,11 @@ import { basename, join, resolve } from "node:path";
 import { metaDir } from "./compat.js";
 import type { SessionCheckpointRecord } from "./session-schema.js";
 import { SessionCheckpointRecordSchema } from "./session-schema.js";
-import { normalizeCheckpointScope, type CheckpointQuality } from "./session-engine.js";
+import { isFallbackSummary, normalizeCheckpointScope, type CheckpointQuality } from "./session-engine.js";
 
-const FALLBACK_SUMMARY = "Checkpoint captured current task state without repo-state details.";
 
 export function classifyCheckpointQuality(record: SessionCheckpointRecord): CheckpointQuality {
-  const isFallback = record.summary === FALLBACK_SUMMARY;
+  const isFallback = isFallbackSummary(record.summary);
   const hasContent = record.decisions.length > 0 || record.openLoops.length > 0 || record.nextActions.length > 0;
   return isFallback && !hasContent ? "minimal" : "rich";
 }

package/src/skill-promotion.ts

@@ -30,6 +30,39 @@ export interface PromotionCandidate {
   verification?: VerifyResult;
   /** Read-signal evidence aggregated from source entries（Artel 读驱动升华：被真实读过的候选提权）。 */
   readEvidence?: { totalAccess: number; distinctReaders: number };
+  /** 这个候选覆盖了几个不同来源（episode）。1 = 同一次经历的重复，不是跨任务规律。 */
+  distinctSources?: number;
+}
+
+/**
+ * 被跨来源判据拒掉的簇 —— 「同一个坑踩了 N 次」。
+ *
+ * 这不是待晋升的规律，是反模式证据：`judgeDistinctSources` 判 `rejected` 时原本只
+ * `rejectedSingleSource++` 然后 continue，信号变成一个数字后消失（同文件下方注释
+ * 早就写着"走 failure-burst 反模式那条路"，而那条路一直不存在）。
+ *
+ * 字段借自 MemTensor/memmy-agent 的 `Memory/src/service/evolution/negative-experience-pipeline.ts`
+ * （其 `NegativeExperienceSource` 枚举里字面就有 `tool_failure_burst`）。
+ * **有意只借它列的证据字段**：memmy 那份 schema 还有 `preference`（该怎么做）与
+ * `verification`（怎么确认没再犯），但那两格要的是判断不是统计 —— 扫描器编出来的
+ * 「该怎么做」比没有更糟。它们列在 `needsJudgement` 里等人或 LLM 填。
+ */
+export interface AntiPatternCandidate {
+  /** 目前只有一条来路；留成联合类型是为了将来接别的信号（如工具连续失败）时不改调用方。 */
+  source: "single_source_burst";
+  /** 撞上它的场景 —— 取簇种子的首行，和 candidates 的 suggestedName 同款提取。 */
+  trigger: string;
+  /** 反模式描述 —— 簇内多条的共性摘要。 */
+  antiPattern: string;
+  /** 同一个坑重复了几次。 */
+  occurrences: number;
+  /** 实际覆盖几个不同来源（判 rejected 说明它 < minDistinctSources）。 */
+  distinctSources: number;
+  /** 0-1。同一来源里重复越多越强，但不因此就变成"规律"。 */
+  evidenceStrength: number;
+  sourceEntries: Array<{ id: string; text: string }>;
+  /** 扫描器有意不填的字段，等判断补上。写死成数组是为了让调用方能机械检查。 */
+  needsJudgement: ReadonlyArray<"preference" | "verification">;
 }
 
 export interface PromotionScanResult {
@@ -40,6 +73,16 @@ export interface PromotionScanResult {
   truncatedCases: number;
   /** 向量回填失败(库中无向量)而被跳过的条目数。 */
   vectorlessSkipped: number;
+  /** No-silent-caps 披露:条数够、但来源不够(同一个坑重复)而被拒的簇数。 */
+  rejectedSingleSource: number;
+  /** No-silent-caps 披露:拿不到来源指针、跨来源判据弃权放行的簇数。 */
+  abstainedUnknownSource: number;
+  /**
+   * P4 反模式出口:被判 rejected 的簇的**内容**,不只是计数。
+   * 注意与 abstainedUnknownSource 的区别 —— 弃权的簇不进这里:
+   * 不知道来源就不能指控它是「同一个坑踩三次」。
+   */
+  antiPatterns?: AntiPatternCandidate[];
 }
 
 export interface PromotionConfig {
@@ -58,6 +101,19 @@ export interface PromotionConfig {
   /** pattern_to_skill 通道最多探测的 structured patterns 数(每个一次 vectorSearch,
    *  default: 1000,按 recency 优先)。 */
   maxPatternProbes: number;
+  /**
+   * 一个簇要来自几个**不同来源**才算规律(default: 2)。
+   *
+   * 借鉴 MemOS 的 L1→L2 判据:它数的是「几个不同 episode」,而这里原本数的是
+   * 「几条相似 case」——差的是维度不是数字。**同一个坑踩三次**在旧口径下是 3 条
+   * 相似 case、会被识别成一条规律;在 MemOS 那儿是 1 个 episode 重复,够不上 L2。
+   * 而反复撞同一个坑本该走 failure-burst 生成「Avoid」反模式,跟「这类子任务该怎么做」
+   * 是相反的两种东西,现在它们混在同一条通道里。
+   *
+   * 审计原文的要害:「两个完全不同的任务遇到同类子问题,才诱导出一条可迁移 L2」——
+   * 最小值是 2,但要害在「跨任务」不在「2」。设 1 = 关闭该判据(旧行为,对照用)。
+   */
+  minDistinctSources: number;
 }
 
 const DEFAULT_CONFIG: PromotionConfig = {
@@ -68,6 +124,7 @@ const DEFAULT_CONFIG: PromotionConfig = {
   maxBucketSize: 2_000,
   pageSize: 1_000,
   maxPatternProbes: 1_000,
+  minDistinctSources: 2,
 };
 
 // ---------------------------------------------------------------------------
@@ -268,6 +325,98 @@ export function greedyCluster(
   return clusters;
 }
 
+// ---------------------------------------------------------------------------
+// Source identity (MemOS-style episode counting)
+// ---------------------------------------------------------------------------
+
+/**
+ * 一条记录来自「哪一次」——跨来源去重的 key。
+ *
+ * 三级取值，越靠前越可靠：
+ *   1. `metadata.evidenceMemories` —— dream 合成产物指向的簇内真实源（synthesis-contract
+ *      2026-08-23 起写入，已验证互不重复且无悬空）。同一批源出来的两条派生物
+ *      签名相同 → 算一个来源，不是两个。
+ *   2. `tags` 里的 `src:<sessionId 前 8 位>` —— shared-behaviors §5.3 要求 pivot 写入必带。
+ *      2026-08-23 实测：`memory:pivot` 池 1699 条覆盖率 99.8%，其中 cases 260 条 100% 覆盖。
+ *      ⚠️ 但全库只有 2.3%、`category=cases` 全库仅 1.2% —— **这个判据只在 pivot 池成立**，
+ *      别拿去当全库口径。
+ *   3. 兜底 `day:<scope>:<YYYY-MM-DD>` —— 没有来源指针时退到「同一天同一 scope 算一次」。
+ *      粗，但比把同一次经历数成 N 次强。
+ */
+export function extractSourceKey(entry: Pick<MemoryEntry, "metadata" | "scope" | "timestamp">): string {
+  let meta: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(entry.metadata || "{}");
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      meta = parsed as Record<string, unknown>;
+    }
+  } catch { /* fall through to day bucket */ }
+
+  const evidence = meta.evidenceMemories;
+  if (Array.isArray(evidence) && evidence.length > 0) {
+    const ids = evidence.filter((v): v is string => typeof v === "string").sort();
+    if (ids.length > 0) return `ev:${ids.join("|")}`;
+  }
+
+  if (Array.isArray(meta.tags)) {
+    const src = meta.tags.find((t): t is string => typeof t === "string" && t.startsWith("src:"));
+    if (src) return src;
+  }
+
+  const day = Number.isFinite(entry.timestamp) && entry.timestamp > 0
+    ? new Date(entry.timestamp).toISOString().slice(0, 10)
+    : "unknown";
+  return `${UNKNOWN_SOURCE_PREFIX}${entry.scope}:${day}`;
+}
+
+/** 兜底 key 的前缀。带这个前缀 = 我们其实不知道它来自哪一次。 */
+export const UNKNOWN_SOURCE_PREFIX = "day:";
+
+/** 一组记录覆盖了几个不同来源。1 = 全部来自同一次经历。 */
+export function countDistinctSources(
+  entries: ReadonlyArray<Pick<MemoryEntry, "metadata" | "scope" | "timestamp">>,
+): number {
+  return new Set(entries.map(extractSourceKey)).size;
+}
+
+export type SourceVerdict =
+  | { status: "ok"; distinctSources: number }
+  | { status: "rejected"; distinctSources: number }
+  /** 没有可信的来源指针 —— 不知道就不判，放行。 */
+  | { status: "abstained" };
+
+/**
+ * 判一个簇是否来自足够多的不同经历。**带弃权路径**。
+ *
+ * 为什么要弃权而不是一律判：兜底 key 是「同 scope 同一天算一次」，而一天内解决三个
+ * 不同问题写三条 case 是完全正常的——那是 3 个 episode，兜底会把它们并成 1 个，
+ * 于是一条真规律被当成「同一个坑踩三次」拒掉。**误伤的代价比漏判高**：漏判只是
+ * 维持现状（旧行为），误伤是把本来能升华的东西堵死，而且堵得无声无息。
+ *
+ * 所以判据只在**拿得到真来源指针**时生效。实际效果就是它只在 `memory:pivot` 池成立
+ * （2026-08-23 实测该池 cases 100% 带 `src:`，而全库 cases 只有 1.2%）——
+ * 这恰好是本方案的适用范围，不是巧合：§5.3 要求 pivot 写入必带来源指针，
+ * 那条规矩本来就是为了让「回原文核对」成为可能，跨来源计数是它的另一个消费者。
+ */
+export function judgeDistinctSources(
+  entries: ReadonlyArray<Pick<MemoryEntry, "metadata" | "scope" | "timestamp">>,
+  minDistinctSources: number,
+): SourceVerdict {
+  if (minDistinctSources <= 1) {
+    return { status: "ok", distinctSources: countDistinctSources(entries) };
+  }
+  const keys = entries.map(extractSourceKey);
+  const known = keys.filter((k) => !k.startsWith(UNKNOWN_SOURCE_PREFIX));
+  if (known.length === 0) return { status: "abstained" };
+
+  // 有真指针的按真指针数；没指针的每条各算一次未知来源——不能让「不知道」
+  // 白白顶上一个来源，也不能因为混了几条没指针的就整簇弃权。
+  const distinctSources = new Set(keys).size;
+  return distinctSources >= minDistinctSources
+    ? { status: "ok", distinctSources }
+    : { status: "rejected", distinctSources };
+}
+
 // ---------------------------------------------------------------------------
 // Read evidence (Artel-style read-driven promotion)
 // ---------------------------------------------------------------------------
@@ -348,6 +497,9 @@ export async function scanForPromotions(
     scannedPatterns: patterns.length,
     truncatedCases: 0,
     vectorlessSkipped: 0,
+    rejectedSingleSource: 0,
+    abstainedUnknownSource: 0,
+    antiPatterns: [],
   };
 
   // 2. Cluster cases bucket-by-bucket (topicTag, untagged fallback)。
@@ -378,6 +530,29 @@ export async function scanForPromotions(
         if (cluster.members.length < cfg.minCaseOccurrences) continue;
         if (caseCandidates >= cfg.maxCandidates) break;
 
+        // 跨来源判据：条数够不代表是规律。同一次经历重复 N 条走的是 failure-burst
+        // 反模式那条路，不是「这类子任务该怎么做」这条。拿不到来源指针时弃权放行。
+        const sourceVerdict = judgeDistinctSources(cluster.members, cfg.minDistinctSources);
+        if (sourceVerdict.status === "rejected") {
+          result.rejectedSingleSource++;
+          // P4:不晋升,但也不让它无声消失 —— 同一个坑重复本身就是要记的东西。
+          // 仍然 continue,晋升判据分毫未动。
+          result.antiPatterns.push({
+            source: "single_source_burst",
+            trigger: extractName(cluster.seed.text),
+            antiPattern: summarizeCluster(cluster.members),
+            occurrences: cluster.members.length,
+            distinctSources: sourceVerdict.distinctSources,
+            // Bayesian smoothing,与 candidates 的 confidence 同款,饱和于 1。
+            evidenceStrength: cluster.members.length / (cluster.members.length + 2),
+            sourceEntries: cluster.members.map(m => ({ id: m.id, text: m.text })),
+            needsJudgement: ["preference", "verification"],
+          });
+          continue;
+        }
+        if (sourceVerdict.status === "abstained") result.abstainedUnknownSource++;
+        const distinctSources = sourceVerdict.status === "ok" ? sourceVerdict.distinctSources : undefined;
+
         // Compute average intra-cluster similarity for scoring
         const avgSim = computeAverageIntraClusterSimilarity(cluster.members);
 
@@ -397,6 +572,7 @@ export async function scanForPromotions(
             caseReadEvidence.distinctReaders,
           ),
           readEvidence: caseReadEvidence,
+          distinctSources,
         });
       }
     }
@@ -433,6 +609,16 @@ export async function scanForPromotions(
 
     if (similarCases.length < 2) continue;
 
+    // 同一判据也管 pattern→skill：MemOS 的 L2/L3→Skill 门就是「N 个独立 episode」。
+    // 支撑证据全来自同一次经历时，这条 skill 学的是那一次，不是那一类。
+    const patternVerdict = judgeDistinctSources(similarCases.map(h => h.entry), cfg.minDistinctSources);
+    if (patternVerdict.status === "rejected") {
+      result.rejectedSingleSource++;
+      continue;
+    }
+    if (patternVerdict.status === "abstained") result.abstainedUnknownSource++;
+    const patternDistinctSources = patternVerdict.status === "ok" ? patternVerdict.distinctSources : undefined;
+
     // A2: zero-LLM verifier — pattern 当 draft，supporting cases 当 evidence。
     // steps 传 [] 不是漏传：pattern.text 已含完整 Steps 块，resonance 用整段文本即可；
     // extractSteps(pattern.text) 仅用于下面的 suggestedImplementation 字段。
@@ -462,6 +648,7 @@ export async function scanForPromotions(
       ),
       verification,
       readEvidence: patternReadEvidence,
+      distinctSources: patternDistinctSources,
     });
   }
 
@@ -495,6 +682,33 @@ export function formatPromotionResult(result: PromotionScanResult): string {
   if (result.vectorlessSkipped > 0) {
     lines.push(`⚠️ ${result.vectorlessSkipped} entries skipped (no vector in store).`);
   }
+  if (result.abstainedUnknownSource > 0) {
+    lines.push(
+      `ℹ️ ${result.abstainedUnknownSource} cluster(s) 没有可信来源指针，跨来源判据已弃权放行`
+      + `（这些 scope 里的条目没带 src: tag，判了就是瞎判）。`,
+    );
+  }
+  if (result.rejectedSingleSource > 0) {
+    lines.push(
+      `⚠️ ${result.rejectedSingleSource} cluster(s) had enough entries but too few distinct sources`
+      + ` — 同一次经历的重复不算规律（不晋升，改走下面的反模式清单）。`,
+    );
+  }
+
+  // P4:被拒的簇在这里落地。只显示计数等于让信号消失在一个数字里 ——
+  // 消费者看到的是这段文本,不是 result 对象。
+  // `?.` 不是防御性编程的装饰:PromotionScanResult 是导出接口,旧调用方构造的对象
+  // 没有这个字段,运行时会是 undefined(TS 编译期拦不住外部构造)。
+  if (result.antiPatterns?.length) {
+    lines.push(`\n🔁 ${result.antiPatterns.length} anti-pattern(s) — 同一个坑重复出现，不是规律但要记：\n`);
+    for (const [i, ap] of result.antiPatterns.entries()) {
+      lines.push(`### A${i + 1}. ${ap.trigger}`);
+      lines.push(`重复 ${ap.occurrences} 次，来自 ${ap.distinctSources} 个来源（证据强度 ${(ap.evidenceStrength * 100).toFixed(0)}%）`);
+      lines.push(`共性: ${ap.antiPattern}`);
+      lines.push(`待补判断: ${ap.needsJudgement.join(" / ")} — 扫描器只出证据，「该怎么做」和「怎么确认没再犯」要人或 LLM 填。`);
+      lines.push("");
+    }
+  }
 
   if (result.candidates.length === 0) {
     lines.push("No promotion candidates found.");
@@ -507,7 +721,10 @@ export function formatPromotionResult(result: PromotionScanResult): string {
     lines.push(`### ${i + 1}. [${c.type}] ${c.suggestedName}`);
     lines.push(`Confidence: ${(c.confidence * 100).toFixed(1)}%`);
     lines.push(`Description: ${c.suggestedDescription}`);
-    lines.push(`Sources: ${c.sourceEntries.length} entries`);
+    lines.push(
+      `Sources: ${c.sourceEntries.length} entries`
+      + (c.distinctSources !== undefined ? ` from ${c.distinctSources} distinct source(s)` : ""),
+    );
     if (c.readEvidence) {
       lines.push(`Read evidence: ${c.readEvidence.totalAccess} total reads, ${c.readEvidence.distinctReaders} distinct reader(s)`);
     }