@zooique/memora 2.0.0 → 3.0.0

package/dist/agent/managers/memoryAdvisor.d.ts

@@ -1,43 +1,23 @@
 /**
- * 记忆顾问 — 健康诊断 + 关联推荐 + 冲突检测
- *
- * 从 MemoryInspector 提取 sourceHealth() + suggest() 为独立模块。
- * 两者均为纯只读分析计算，仅依赖 IMemoryStorage，不修改任何状态。
- *
- * 设计原则（延续 MemoryInspector）：
- *   - 纯只读——只读 IMemoryStorage，不修改任何状态
- *   - 同步返回——不调 LLM、不调 SQLite 写入
- *   - 无状态——所有数据从 IMemoryStorage 实时读取
- *
- * L3 冲突检测（可选增强）：
- *   - detectConflicts() 是异步方法，调用 LLM 判断记忆间语义冲突
- *   - backgroundProvider 未注入时静默跳过（向后兼容）
- *   - 仅检测不修复——冲突需要用户决策（降级哪条由用户选择）
+ * 记忆顾问 — sourceHealth()（源健康诊断）+ suggest()（关联推荐）+ detectConflicts()（L3 冲突检测）。
+ * 纯只读分析计算，仅依赖 IMemoryStorage 不修改状态；同步返回不调 LLM。
+ * L3 冲突检测：异步调 LLM 判断记忆间语义冲突，仅检测不修复（降级哪条由用户决策）。
  */
 import type { Memory } from '../../memory/types.js';
 import type { IMemoryStorage } from '../../memory/storageInterface.js';
 import type { LlmProvider } from '../../llm/provider.js';
-/** 记忆源健康状态 */
-export type SourceHealthStatus = 'healthy' | 'warning' | 'critical';
-/** 单个 source 的健康指标 */
+/** 单个 source 的事实观测指标（纯事实，不做健康等级判定） */
 export interface SourceHealthEntry {
-    /** 来源标签 */
     source: string;
     /** 记忆数量 */
     count: number;
-    /** 平均 score（0-1） */
-    avgScore: number;
-    /** 距上次访问的天数（取该 source 中最近访问的记忆） */
+    /** 距上次访问的天数（取该 source 中最近访问的记忆，冷记忆观测） */
     daysSinceLastAccess: number;
-    /** 健康状态：healthy（score≥0.5 且 7 天内有访问）/ warning（score<0.5 或 7-30 天未访问）/ critical（score<0.2 或 30 天以上未访问） */
-    status: SourceHealthStatus;
 }
-/** 记忆源健康诊断报告 */
+/** 记忆源诊断报告（纯事实观测，不设健康等级——记忆健康由 supersede/命中体现） */
 export interface SourceHealthReport {
-    /** 各 source 健康指标 */
+    /** 各 source 事实观测 */
     sources: SourceHealthEntry[];
-    /** 整体健康状态（取最差 source 的状态） */
-    overallStatus: SourceHealthStatus;
     /** 诊断时间（ISO 8601） */
     diagnosedAt: string;
 }
@@ -45,20 +25,17 @@ export interface SourceHealthReport {
 export interface SuggestOptions {
     /** 返回数量上限（默认 5） */
     limit?: number;
-    /** 排除的 source 标签（默认排除 persona、rule、skill） */
+    /** 排除的 source 标签（默认空数组——设定记忆已归角色包，不再参与召回排除） */
     excludeSources?: string[];
-    /** 时效性权重（0-1，默认 0.3）：越高越偏好最近访问的记忆 */
-    recencyWeight?: number;
 }
 /** 关联推荐结果 */
 export interface SuggestHit {
     /** 记忆唯一标识（source:name 格式） */
     id: string;
-    /** 记忆名称 */
     name: string;
     /** 来源标签 */
     source: string;
-    /** 推荐分数（0-1，由 score + recency 综合计算） */
+    /** 推荐分数（0-1，score 退役后为纯时效 recency） */
     relevance: number;
     /** 内容预览（截断到 120 字符） */
     contentPreview: string;
@@ -67,13 +44,11 @@ export interface SuggestHit {
 }
 /** 单对记忆的冲突判断结果 */
 export interface ConflictVerdict {
-    /** 记忆 A */
     memoryA: Memory;
-    /** 记忆 B */
     memoryB: Memory;
     /** 是否存在语义冲突（true → 需用户决策降级哪条） */
     hasConflict: boolean;
-    /** 冲突描述（hasConflict=true 时提供，说明冲突点） */
+    /** 冲突描述（hasConflict=true 时提供冲突点） */
     conflictDescription?: string;
     /** LLM 建议保留的记忆（'a' / 'b' / 'both'，仅供参考） */
     recommendation?: 'a' | 'b' | 'both';
@@ -90,108 +65,40 @@ export interface ConflictReport {
     conflictCount: number;
     /** 冲突详情列表（供宿主 UI 展示和用户决策） */
     conflicts: ConflictVerdict[];
-    /** 跳过原因（LLM 不可用 / 无候选对 / LLM 失败降级） */
+    /** 跳过原因（LLM 不可用 / 无候选对） */
     skippedReason?: string;
 }
-/**
- * 记忆顾问
- *
- * 从 MemoryInspector 拆分，负责基于记忆数据的分析计算：
- *   - sourceHealth()：记忆源健康诊断（数量、score、新鲜度）
- *   - suggest()：关联推荐（基于 score + 时效性 + 多样性）
- *   - detectConflicts()：语义冲突检测（L3，可选，backgroundProvider 注入后启用）
- *
- * 与 MemoryInspector 的分工：
- *   - MemoryInspector：直接数据查询（snapshot/search/stats/relations + 写操作代理）
- *   - MemoryAdvisor：分析计算（健康诊断 + 推荐排序 + 冲突检测）
- */
+/** 记忆顾问：与 MemoryInspector 分工（Inspector 直接数据查询，Advisor 分析计算：健康诊断 + 推荐排序 + 冲突检测） */
 export declare class MemoryAdvisor {
     private readonly index;
     /** 后台 LLM Provider（可选，用于 L3 冲突检测，未注入时跳过） */
     private readonly backgroundProvider;
+    /** 治理源列表（默认 GOVERNANCE_SOURCES；空治理源时推荐/冲突检测空转，测试可显式注入） */
+    private readonly sources;
+    constructor(index: IMemoryStorage, backgroundProvider?: LlmProvider | null, sources?: readonly string[]);
     /**
-     * @param index - 记忆存储（只读访问，用于健康诊断和推荐计算）
-     * @param backgroundProvider - 后台 LLM Provider（可选，用于 L3 冲突检测，未注入时跳过）
-     */
-    constructor(index: IMemoryStorage, backgroundProvider?: LlmProvider | null);
-    /**
-     * 记忆源健康诊断
-     *
-     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态），
-     * 帮助宿主项目判断是否需要触发衰减、清理或补充。
-     *
-     * 健康状态判定：
-     * - healthy：avgScore ≥ 0.5 且 7 天内有访问
-     * - warning：avgScore < 0.5 或 7-30 天未访问
-     * - critical：avgScore < 0.2 或 30 天以上未访问
-     *
-     * 纯只读、同步、不调 LLM，与 stats() 互补（stats 只有数量，本方法有质量指标）。
-     * 使用 getAllSources() 发现所有 source 标签，替代全量 search。
+     * 记忆源健康诊断：逐 source 计算记忆数量 / 最近访问天数（纯事实观测）。
+     * 不设健康等级：记忆健康由 supersede（写时取代）/ 命中体现，
+     * 无需榜单级 status 判定（daysSinceLastAccess 作冷记忆观测）。
+     * 纯只读同步不调 LLM，用 getAllSources() 发现所有 source 标签（替代全量 search）。
      */
     sourceHealth(): SourceHealthReport;
     /**
-     * 关联推荐：基于已有记忆数据，推荐你可能感兴趣的记忆
-     *
-     * 不调 LLM，纯计算。综合 score（权重）+ accessedAt（时效性）+ source 多样性，
-     * 返回"与你当前关注点相关但尚未直接搜索到"的记忆。
-     *
-     * 适用场景：
-     * - 用户搜索后，展示"你可能还想看"
-     * - 对话开始时，展示"最近你可能关心的记忆"
-     * - 宿主程序构建个性化推荐面板
-     *
-     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
-     * @param options - 推荐选项
+     * 关联推荐：不调 LLM 纯计算，综合 accessedAt（时效）+ source 多样性，
+     * 返回"相关但尚未直接搜索到"的记忆。query 提供时结合搜索命中推荐，省略时基于最近使用。
+     * relevance 为纯时效（recency）
      */
     suggest(query?: string, options?: SuggestOptions): SuggestHit[];
     /**
-     * 语义冲突检测：扫描同 source 的记忆对，调用 LLM 判断是否存在语义冲突
-     *
-     * 流程：
-     *   1. 从 insight/profile/work-projection 加载候选记忆（每个 source 取 top 10 条）
-     *   2. 同 source 内两两配对，取前 10 对
-     *   3. 对每对调用 LLM 判断是否存在语义冲突
-     *   4. 返回冲突报告（仅检测，不修复——冲突需要用户决策）
-     *
-     * 安全设计：
-     *   - 仅检测不修复——不自动降级任何记忆，返回冲突详情供用户决策
-     *   - LLM 失败降级——返回已处理的报告，不阻塞调用方
-     *   - 单对 LLM 失败不阻塞后续检测
-     *   - backgroundProvider 未注入时静默跳过（向后兼容）
-     *
-     * 使用场景：
-     *   - 宿主定时任务定期检测（如每天一次）
-     *   - 用户手动触发（记忆管理面板的"检测冲突"按钮）
-     *   - 健康诊断报告的补充（sourceHealth 显示数量，本方法显示质量冲突）
-     *
-     * @param signal 可选的 AbortSignal（取消正在进行的 LLM 判断）
-     * @returns 冲突检测报告
+     * 语义冲突检测：加载候选（每 source top 10）→ 同 source 两两配对（前 10 对）→ LLM 判断冲突。
+     * 仅检测不修复（不自动降级，冲突需用户决策）；LLM 失败不阻塞；provider 未注入静默跳过。
      */
     detectConflicts(signal?: AbortSignal): Promise<ConflictReport>;
-    /**
-     * 筛选同 source 内的候选冲突对
-     *
-     * 策略：
-     *   - 按 source 分组，同 source 内两两配对
-     *   - 限制每个 source 的配对数，避免 O(n²) 爆炸
-     *   - 总候选对数上限 10 对
-     *
-     * @param candidates 候选记忆列表（已按 source 分组混合）
-     * @returns 同 source 候选对列表
-     */
+    /** 筛选同 source 内候选冲突对：按 source 分组两两配对，限制每 source 配对数避免 O(n²) 爆炸，总上限 10 对 */
     private findConflictCandidates;
     /**
-     * 调用 LLM 判断单对记忆是否存在语义冲突
-     *
-     * 使用结构化 JSON 输出（hasConflict + conflictDescription + recommendation + reason），
-     * 参照 SessionArchiver.generateSummary 的 parseLlmJson 模式。
-     *
-     * LLM 失败时抛出异常（由 detectConflicts 捕获并降级跳过此对）。
-     *
-     * @param memoryA 记忆 A
-     * @param memoryB 记忆 B
-     * @param signal 可选的 AbortSignal
-     * @returns LLM 判断结果
+     * 调用 LLM 判断两条记忆是否冲突：结构化 JSON 输出（hasConflict+conflictDescription+recommendation+reason）。
+     * 流式累积/解析/异常封装委托 llmJudgeHelper.judgeWithLlm；失败抛 MemoraError 由调用方捕获跳过。
      */
     private judgeConflict;
 }

package/dist/agent/managers/memoryAdvisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memoryAdvisor.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryAdvisor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memoryAdvisor.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryAdvisor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAKnE,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,mBAAmB,CAAC;AA6B9D,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,qBAAqB;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,aAAa;AACb,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,aAAa;AACb,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,kBAAkB;AAClB,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,cAAc,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;IACpC,eAAe;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,gBAAgB;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,kFAAkF;AAClF,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAGzB,KAAK,EAAE,cAAc,EACtC,kBAAkB,GAAE,WAAW,GAAG,IAAW,EAC7C,OAAO,GAAE,SAAS,MAAM,EAAuB;IAQjD;;;;;OAKG;IACH,YAAY,IAAI,kBAAkB;IAsClC;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,UAAU,EAAE;IA6EnE;;;OAGG;IACG,eAAe,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IAwEpE,2EAA2E;IAC3E,OAAO,CAAC,sBAAsB;IA+B9B;;;OAGG;YACW,aAAa;CAiC5B"}

package/dist/agent/managers/memoryAdvisor.js

@@ -1,156 +1,92 @@
-import { SOURCE_LABELS } from '../../memory/types.js';
-import { ONE_DAY_MS } from '../../memory/recall.js';
-import { nowIso } from '../../utils/time.js';
-// parseLlmJson 用于解析 LLM 冲突判断结果
-import { byScoreDesc } from '../../utils/array.js';
-import { parseLlmJson } from '../../utils/json.js';
+import { nowIso, ONE_DAY_MS } from '../../utils/time.js';
+import { roundTo } from '../../utils/math.js';
+// 召回排除默认值 SSOT 共享（设定记忆已归角色包，默认不排除）
+import { DEFAULT_RECALL_EXCLUDE_SOURCES } from '../../utils/recallDefaults.js';
+// LLM judge 高阶函数（流式累积 + parseLlmJson + configError 封装）
+import { judgeWithLlm } from '../../agent/managers/llmJudgeHelper.js';
+import { byAccessedDesc } from '../../utils/array.js';
 import { truncate } from '../../utils/strings.js';
 import { logger } from '../../logging/logger.js';
+// 治理源列表 SSOT（设定记忆已归角色包）
+import { GOVERNANCE_SOURCES } from '../../memory/governance.js';
 // ─── 常量 ────────────────────────────────────────────────
 /** 关联推荐：每个 source 采样 top-N 条 */
 const SUGGEST_TOP_PER_SOURCE = 3;
-/** 关联推荐：时效性衰减窗口（天），超过此天数归零 */
+/** 关联推荐：时效性窗口（天），超过此天数 relevance 归零（score 退役后纯时效排序） */
 const SUGGEST_RECENCY_WINDOW_DAYS = 30;
-/** 推荐结果内容预览字符数（与 MemoryInspector.SEARCH_PREVIEW_LEN 一致，独立维护以便各模块独立演进） */
+/** 推荐内容预览字符数 */
 const ADVISOR_PREVIEW_LEN = 120;
-/** source 健康度阈值（低于此值或超期触发 critical/warning） */
-const SOURCE_HEALTH_THRESHOLDS = {
-    /** 平均 score 低于此值 → critical */
-    CRITICAL_SCORE: 0.2,
-    /** 平均 score 低于此值 → warning */
-    WARNING_SCORE: 0.5,
-    /** 超过此天数未访问 → critical */
-    CRITICAL_DAYS: 30,
-    /** 超过此天数未访问 → warning */
-    WARNING_DAYS: 7,
-};
 // ─── L3 冲突检测常量 ────────────────────────────────────
-/** 参与冲突检测的 source 标签 */
-const CONFLICT_SOURCES = [SOURCE_LABELS.INSIGHT, SOURCE_LABELS.PROFILE, SOURCE_LABELS.WORK_PROJECTION];
-/** 单个 source 内参与配对的记忆条数上限（控制 O(n²) 配对规模） */
+/** 单个 source 内参与配对的条数上限（控制 O(n²) 配对规模） */
 const CONFLICT_CANDIDATES_PER_SOURCE = 10;
 /** 单次 LLM 冲突判断的候选对数上限 */
 const CONFLICT_PAIR_LIMIT = 10;
 /** LLM 冲突判断超时（ms） */
 const CONFLICT_TIMEOUT_MS = 15_000;
-/** 候选记忆内容预览长度（截断后送入 LLM） */
+/** 候选内容预览长度（送入 LLM 前截断） */
 const CONFLICT_CONTENT_PREVIEW_LEN = 200;
 // ─── 类 ──────────────────────────────────────────────────
-/**
- * 记忆顾问
- *
- * 从 MemoryInspector 拆分，负责基于记忆数据的分析计算：
- *   - sourceHealth()：记忆源健康诊断（数量、score、新鲜度）
- *   - suggest()：关联推荐（基于 score + 时效性 + 多样性）
- *   - detectConflicts()：语义冲突检测（L3，可选，backgroundProvider 注入后启用）
- *
- * 与 MemoryInspector 的分工：
- *   - MemoryInspector：直接数据查询（snapshot/search/stats/relations + 写操作代理）
- *   - MemoryAdvisor：分析计算（健康诊断 + 推荐排序 + 冲突检测）
- */
+/** 记忆顾问：与 MemoryInspector 分工（Inspector 直接数据查询，Advisor 分析计算：健康诊断 + 推荐排序 + 冲突检测） */
 export class MemoryAdvisor {
     index;
     /** 后台 LLM Provider（可选，用于 L3 冲突检测，未注入时跳过） */
     backgroundProvider;
-    /**
-     * @param index - 记忆存储（只读访问，用于健康诊断和推荐计算）
-     * @param backgroundProvider - 后台 LLM Provider（可选，用于 L3 冲突检测，未注入时跳过）
-     */
-    constructor(index, backgroundProvider = null) {
+    /** 治理源列表（默认 GOVERNANCE_SOURCES；空治理源时推荐/冲突检测空转，测试可显式注入） */
+    sources;
+    constructor(index, backgroundProvider = null, sources = GOVERNANCE_SOURCES) {
         this.index = index;
         this.backgroundProvider = backgroundProvider;
+        this.sources = sources;
     }
     // ─── 源健康诊断 ─────────────────────────────────────────
     /**
-     * 记忆源健康诊断
-     *
-     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态），
-     * 帮助宿主项目判断是否需要触发衰减、清理或补充。
-     *
-     * 健康状态判定：
-     * - healthy：avgScore ≥ 0.5 且 7 天内有访问
-     * - warning：avgScore < 0.5 或 7-30 天未访问
-     * - critical：avgScore < 0.2 或 30 天以上未访问
-     *
-     * 纯只读、同步、不调 LLM，与 stats() 互补（stats 只有数量，本方法有质量指标）。
-     * 使用 getAllSources() 发现所有 source 标签，替代全量 search。
+     * 记忆源健康诊断：逐 source 计算记忆数量 / 最近访问天数（纯事实观测）。
+     * 不设健康等级：记忆健康由 supersede（写时取代）/ 命中体现，
+     * 无需榜单级 status 判定（daysSinceLastAccess 作冷记忆观测）。
+     * 纯只读同步不调 LLM，用 getAllSources() 发现所有 source 标签（替代全量 search）。
      */
     sourceHealth() {
-        const now = Date.now();
-        // 使用 getAllSources() 获取所有有数据的 source 标签
+        // 获取所有有数据的 source 标签
         const sourceMap = this.index.getAllSources();
         const sourceSet = new Set();
         for (const [source, count] of sourceMap) {
             if (count > 0)
                 sourceSet.add(source);
         }
-        // 逐 source 计算健康指标
         const entries = [];
         for (const source of sourceSet) {
             const memories = this.index.getBySource(source);
             const count = memories.length;
-            // 平均 score
-            const avgScore = count > 0
-                ? memories.reduce((sum, m) => sum + m.score, 0) / count
-                : 0;
-            // 最近访问时间（取该 source 中最新的 accessedAt）
+            // 最近访问时间（取该 source 中最新 accessedAt）
             const latestAccess = memories
                 .map((m) => new Date(m.accessedAt).getTime())
                 .filter((t) => !isNaN(t))
                 .sort((a, b) => b - a)[0] ?? 0;
-            const daysSinceLastAccess = latestAccess > 0
-                ? (now - latestAccess) / ONE_DAY_MS
-                : Infinity;
-            // 健康状态判定
-            let status;
-            if (avgScore < SOURCE_HEALTH_THRESHOLDS.CRITICAL_SCORE || daysSinceLastAccess > SOURCE_HEALTH_THRESHOLDS.CRITICAL_DAYS) {
-                status = 'critical';
-            }
-            else if (avgScore < SOURCE_HEALTH_THRESHOLDS.WARNING_SCORE || daysSinceLastAccess > SOURCE_HEALTH_THRESHOLDS.WARNING_DAYS) {
-                status = 'warning';
-            }
-            else {
-                status = 'healthy';
-            }
+            const daysSinceLastAccess = latestAccess > 0 ? (Date.now() - latestAccess) / ONE_DAY_MS : Infinity;
             entries.push({
                 source,
                 count,
-                avgScore: Math.round(avgScore * 1000) / 1000,
-                daysSinceLastAccess: Math.round(daysSinceLastAccess * 10) / 10,
-                status,
+                daysSinceLastAccess: roundTo(daysSinceLastAccess, 1),
             });
         }
-        // 整体状态取最差 source
-        const statusPriority = { healthy: 0, warning: 1, critical: 2 };
-        const overallStatus = entries.reduce((worst, e) => statusPriority[e.status] > statusPriority[worst] ? e.status : worst, 'healthy');
         return {
-            sources: entries.sort((a, b) => statusPriority[b.status] - statusPriority[a.status]),
-            overallStatus,
+            // 按 source 名稳定排序（保证输出可预期；无关健康等级）
+            sources: entries.sort((a, b) => a.source.localeCompare(b.source)),
             diagnosedAt: nowIso(),
         };
     }
     // ─── 关联推荐 ─────────────────────────────────────────
     /**
-     * 关联推荐：基于已有记忆数据，推荐你可能感兴趣的记忆
-     *
-     * 不调 LLM，纯计算。综合 score（权重）+ accessedAt（时效性）+ source 多样性，
-     * 返回"与你当前关注点相关但尚未直接搜索到"的记忆。
-     *
-     * 适用场景：
-     * - 用户搜索后，展示"你可能还想看"
-     * - 对话开始时，展示"最近你可能关心的记忆"
-     * - 宿主程序构建个性化推荐面板
-     *
-     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
-     * @param options - 推荐选项
+     * 关联推荐：不调 LLM 纯计算，综合 accessedAt（时效）+ source 多样性，
+     * 返回"相关但尚未直接搜索到"的记忆。query 提供时结合搜索命中推荐，省略时基于最近使用。
+     * relevance 为纯时效（recency）
      */
     suggest(query, options = {}) {
-        const { limit = 5, excludeSources = [SOURCE_LABELS.PERSONA, SOURCE_LABELS.RULE, SOURCE_LABELS.SKILL], recencyWeight = 0.3, } = options;
-        const scoreWeight = 1 - recencyWeight;
+        const { limit = 5, excludeSources = [...DEFAULT_RECALL_EXCLUDE_SOURCES] } = options;
         const now = Date.now();
         // 收集候选记忆
         const candidates = new Map();
-        // 如果有 query，先搜索直接匹配的记忆（标记为 searchHit）
+        // 有 query 时先搜直接命中（标记 searchHit）
         if (query && query.trim()) {
             const directHits = this.index.search(query, limit * 3);
             for (const m of directHits) {
@@ -159,14 +95,13 @@ export class MemoryAdvisor {
                 }
             }
         }
-        // 补充：按 source 分组采样，确保来源多样性
-        const knownSources = [SOURCE_LABELS.INSIGHT, SOURCE_LABELS.PROFILE, SOURCE_LABELS.WORK_PROJECTION];
-        for (const source of knownSources) {
+        // 按 source 分组采样，确保来源多样性
+        for (const source of this.sources) {
             const count = this.index.countBySource(source);
             if (count > 0 && !excludeSources.includes(source)) {
                 const memories = this.index.getBySource(source);
-                // 取 score 最高的前 N 条
-                const top = memories.sort(byScoreDesc).slice(0, SUGGEST_TOP_PER_SOURCE);
+                // 取最近使用的前 N 条（score 退役后按 accessedAt 降序）
+                const top = memories.sort(byAccessedDesc).slice(0, SUGGEST_TOP_PER_SOURCE);
                 for (const m of top) {
                     if (!candidates.has(m.id)) {
                         candidates.set(m.id, { memory: m, searchHit: false });
@@ -176,16 +111,14 @@ export class MemoryAdvisor {
         }
         if (candidates.size === 0)
             return [];
-        // 计算综合推荐分数
         const scored = [];
         for (const { memory, searchHit } of candidates.values()) {
-            // 时效性分：窗口内线性衰减，超过窗口归零
+            // 时效性分：窗口内线性衰减，超过窗口归零；score 退役后 relevance 即纯时效
             const accessedAt = new Date(memory.accessedAt);
             const daysSinceAccess = isNaN(accessedAt.getTime())
                 ? SUGGEST_RECENCY_WINDOW_DAYS
                 : (now - accessedAt.getTime()) / ONE_DAY_MS;
-            const recency = Math.max(0, 1 - daysSinceAccess / SUGGEST_RECENCY_WINDOW_DAYS);
-            const relevance = memory.score * scoreWeight + recency * recencyWeight;
+            const relevance = Math.max(0, 1 - daysSinceAccess / SUGGEST_RECENCY_WINDOW_DAYS);
             // 生成推荐理由
             let reason;
             if (searchHit) {
@@ -194,9 +127,6 @@ export class MemoryAdvisor {
             else if (daysSinceAccess < 1) {
                 reason = '最近访问';
             }
-            else if (memory.score >= 0.8) {
-                reason = '高频记忆';
-            }
             else {
                 reason = `${memory.source} 推荐`;
             }
@@ -212,37 +142,18 @@ export class MemoryAdvisor {
             id: memory.id,
             name: memory.name,
             source: memory.source,
-            relevance: Math.round(relevance * 100) / 100,
+            relevance: roundTo(relevance, 2),
             contentPreview: truncate(memory.content, ADVISOR_PREVIEW_LEN),
             reason,
         }));
     }
     // ─── L3 语义冲突检测（可选，backgroundProvider 注入后启用） ───
     /**
-     * 语义冲突检测：扫描同 source 的记忆对，调用 LLM 判断是否存在语义冲突
-     *
-     * 流程：
-     *   1. 从 insight/profile/work-projection 加载候选记忆（每个 source 取 top 10 条）
-     *   2. 同 source 内两两配对，取前 10 对
-     *   3. 对每对调用 LLM 判断是否存在语义冲突
-     *   4. 返回冲突报告（仅检测，不修复——冲突需要用户决策）
-     *
-     * 安全设计：
-     *   - 仅检测不修复——不自动降级任何记忆，返回冲突详情供用户决策
-     *   - LLM 失败降级——返回已处理的报告，不阻塞调用方
-     *   - 单对 LLM 失败不阻塞后续检测
-     *   - backgroundProvider 未注入时静默跳过（向后兼容）
-     *
-     * 使用场景：
-     *   - 宿主定时任务定期检测（如每天一次）
-     *   - 用户手动触发（记忆管理面板的"检测冲突"按钮）
-     *   - 健康诊断报告的补充（sourceHealth 显示数量，本方法显示质量冲突）
-     *
-     * @param signal 可选的 AbortSignal（取消正在进行的 LLM 判断）
-     * @returns 冲突检测报告
+     * 语义冲突检测：加载候选（每 source top 10）→ 同 source 两两配对（前 10 对）→ LLM 判断冲突。
+     * 仅检测不修复（不自动降级，冲突需用户决策）；LLM 失败不阻塞；provider 未注入静默跳过。
      */
     async detectConflicts(signal) {
-        // backgroundProvider 未注入时静默降级（向后兼容）
+        // provider 未注入时静默降级
         if (!this.backgroundProvider) {
             return {
                 scannedCount: 0,
@@ -252,12 +163,11 @@ export class MemoryAdvisor {
                 skippedReason: 'backgroundProvider 未注入',
             };
         }
-        // ── 步骤 1：加载候选记忆（每个 source 取 top 10 条，按 score 降序） ──
         const candidates = [];
-        for (const source of CONFLICT_SOURCES) {
+        for (const source of this.sources) {
             const memories = this.index.getBySource(source);
-            // 按 score 降序取 top N
-            const top = memories.sort(byScoreDesc).slice(0, CONFLICT_CANDIDATES_PER_SOURCE);
+            // 按 accessedAt 降序取 top N（score 退役后按最近使用采样）
+            const top = memories.sort(byAccessedDesc).slice(0, CONFLICT_CANDIDATES_PER_SOURCE);
             candidates.push(...top);
         }
         if (candidates.length < 2) {
@@ -269,7 +179,7 @@ export class MemoryAdvisor {
                 skippedReason: '候选记忆不足（少于 2 条）',
             };
         }
-        // ── 步骤 2：同 source 内两两配对，取前 10 对 ──
+        // 同 source 内两两配对
         const pairs = this.findConflictCandidates(candidates);
         if (pairs.length === 0) {
             return {
@@ -280,7 +190,7 @@ export class MemoryAdvisor {
                 skippedReason: '无同 source 候选对',
             };
         }
-        // ── 步骤 3：逐对调用 LLM 判断冲突 ──
+        // 逐对调用 LLM 判断冲突
         const conflicts = [];
         for (const pair of pairs) {
             try {
@@ -302,17 +212,7 @@ export class MemoryAdvisor {
             conflicts,
         };
     }
-    /**
-     * 筛选同 source 内的候选冲突对
-     *
-     * 策略：
-     *   - 按 source 分组，同 source 内两两配对
-     *   - 限制每个 source 的配对数，避免 O(n²) 爆炸
-     *   - 总候选对数上限 10 对
-     *
-     * @param candidates 候选记忆列表（已按 source 分组混合）
-     * @returns 同 source 候选对列表
-     */
+    /** 筛选同 source 内候选冲突对：按 source 分组两两配对，限制每 source 配对数避免 O(n²) 爆炸，总上限 10 对 */
     findConflictCandidates(candidates) {
         // 按 source 分组
         const bySource = new Map();
@@ -343,36 +243,12 @@ export class MemoryAdvisor {
         return pairs.slice(0, CONFLICT_PAIR_LIMIT);
     }
     /**
-     * 调用 LLM 判断单对记忆是否存在语义冲突
-     *
-     * 使用结构化 JSON 输出（hasConflict + conflictDescription + recommendation + reason），
-     * 参照 SessionArchiver.generateSummary 的 parseLlmJson 模式。
-     *
-     * LLM 失败时抛出异常（由 detectConflicts 捕获并降级跳过此对）。
-     *
-     * @param memoryA 记忆 A
-     * @param memoryB 记忆 B
-     * @param signal 可选的 AbortSignal
-     * @returns LLM 判断结果
+     * 调用 LLM 判断两条记忆是否冲突：结构化 JSON 输出（hasConflict+conflictDescription+recommendation+reason）。
+     * 流式累积/解析/异常封装委托 llmJudgeHelper.judgeWithLlm；失败抛 MemoraError 由调用方捕获跳过。
      */
     async judgeConflict(memoryA, memoryB, signal) {
         const messages = buildConflictMessages(memoryA, memoryB);
-        let llmResponse = '';
-        // 流式累积模式（与 TextPolishManager / SessionArchiver 一致）
-        for await (const chunk of this.backgroundProvider.chat(messages, {
-            maxTokens: 300,
-            temperature: 0,
-            timeoutMs: CONFLICT_TIMEOUT_MS,
-            signal,
-        })) {
-            if (chunk.content)
-                llmResponse += chunk.content;
-        }
-        // 解析 LLM 响应（JSON 格式）
-        const parsed = parseLlmJson(llmResponse.trim());
-        if (!parsed) {
-            throw new Error('LLM 冲突判断返回非法 JSON');
-        }
+        const parsed = await judgeWithLlm(this.backgroundProvider, messages, { maxTokens: 300, timeoutMs: CONFLICT_TIMEOUT_MS, signal }, 'LLM 冲突判断返回非法 JSON');
         // 校验 recommendation 字段（允许 'a' / 'b' / 'both'，其他值忽略）
         const recRaw = parsed.recommendation;
         const recommendation = recRaw === 'a' || recRaw === 'b' || recRaw === 'both' ? recRaw : undefined;
@@ -386,20 +262,8 @@ export class MemoryAdvisor {
         };
     }
 }
-// ─── L3 冲突检测 Prompt 模板（模块级函数，与 buildDedupMessages 同模式） ───
-/**
- * 构建冲突判断的 LLM 消息
- *
- * 设计要点：
- *   - system 消息定义判断规则（冲突 = 两条记忆表达互相矛盾的信息）
- *   - user 消息携带两条记忆的内容预览（截断到 200 字符）
- *   - 要求输出结构化 JSON（hasConflict + conflictDescription + recommendation + reason）
- *   - few-shot 示例降低 LLM 误判率
- *
- * @param memoryA 记忆 A
- * @param memoryB 记忆 B
- * @returns system + user 消息数组
- */
+// ─── L3 冲突检测 Prompt 模板（模块级函数） ───
+/** 构建冲突判断的 LLM 消息：system 定义冲突规则 + user 携带两条记忆内容预览，few-shot 降误判率 */
 function buildConflictMessages(memoryA, memoryB) {
     const contentA = memoryA.content.length > CONFLICT_CONTENT_PREVIEW_LEN
         ? truncate(memoryA.content, CONFLICT_CONTENT_PREVIEW_LEN, '…[截断]')
@@ -439,13 +303,13 @@ function buildConflictMessages(memoryA, memoryB) {
             role: 'user',
             content: `请判断以下两条记忆是否存在语义冲突：
 
-记忆 A（score: ${memoryA.score}）：
+记忆 A：
 - 名称：${memoryA.name}
 - 来源：${memoryA.source}
 - 创建时间：${memoryA.createdAt}
 - 内容：${contentA}
 
-记忆 B（score: ${memoryB.score}）：
+记忆 B：
 - 名称：${memoryB.name}
 - 来源：${memoryB.source}
 - 创建时间：${memoryB.createdAt}