@zooique/memora 2.0.0 → 3.0.0

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

@@ -1,43 +1,19 @@
 /**
- * 记忆管理器 — 统一的记忆读写入口
- *
- * 从 Agent 拆分出来，负责记忆的查询 + 写入操作。
- * 写方法以 writeXxx 前缀命名，与读方法明确区分。
- *
- * 设计原则：
- *   - 读写统一入口——writeXxx 前缀区分写操作，降低认知负荷
- *   - 同步返回——避免数据不一致（不调 LLM、不调 SQLite 异步写入）
- *   - 轻量——每层只返回前 N 条 + 总数
- *   - 静默降级——relationStore 未注入时关系方法静默 no-op（ADR-014 降级优先）
- *
- * 方法清单：
- *   - 只读查询：snapshot / search / searchHybrid / stats /
- *     getRelations / getAllRelations / getRelationPath / getRelationNeighbors /
- *     getById / getBySource / list / listDeleted / getDeletedById /
- *     sourceHealth / suggest
- *   - 写操作（writeXxx 前缀）：
- *     writeUpsert / writeDelete / writeRestore / writePurge / writePurgeExpired /
- *     writeAddRelation / writeRemoveRelation
- *   - LLM 记忆治理（异步，backgroundProvider 未注入时静默降级）：
- *     deduplicateMemories（语义去重）
+ * 记忆管理器 — 统一的记忆读写入口。
+ * 写方法 writeXxx 前缀区分写操作。同步返回避免数据不一致；每层只返回前 N 条 + 总数（轻量）。
+ * 职责边界：本类只做存储读写与查询；语义去重在 DedupManager，冲突检测/建议在 MemoryAdvisor。
  */
 import type { Memory } from '../../memory/types.js';
 import type { IMemoryStorage } from '../../memory/storageInterface.js';
-import type { IMemoryRelationStore } from '../../memory/relationStore.js';
-import type { MemoryRelation, RelationDirection, RelationPath, RelationNeighbor } from '../../memory/types.js';
-import type { IVectorStore } from '../../memory/vectorStore.js';
 import type { MessageHistory } from '../../agent/messageHistory.js';
 import type { AgentLoop } from '../../agent/loop.js';
-import type { MemoryAdvisor, SourceHealthReport, SuggestOptions, SuggestHit, ConflictReport } from '../../agent/managers/memoryAdvisor.js';
-import type { LlmProvider } from '../../llm/provider.js';
-export type { SourceHealthStatus, SourceHealthEntry, SourceHealthReport, SuggestOptions, SuggestHit, } from '../../agent/managers/memoryAdvisor.js';
-/** 记忆快照 */
+/** 记忆快照（3 层：工作 / Bootstrap / 归档） */
 export interface MemorySnapshot {
     /** 第 1 层：工作记忆（messages 数组） */
     working: WorkingMemorySnapshot;
-    /** 第 2 层：Bootstrap 记忆（永驻 + 领域） */
+    /** 第 2 层：Bootstrap 记忆 */
     bootstrap: BootstrapSnapshot;
-    /** 第 3 层：归档洞察（insight 记忆） */
+    /** 第 3 层：归档记忆（round-summary） */
     archive: ArchiveSnapshot;
 }
 /** 第 1 层：工作记忆快照 */
@@ -58,43 +34,37 @@ export interface BootstrapSnapshot {
         source: string;
         name: string;
         contentPreview: string;
-        /** 权重（0-1） */
-        score: number;
     }>;
 }
-/** 第 3 层：归档记忆快照（insight + profile + work-projection） */
+/** 第 3 层：归档记忆快照（round-summary） */
 export interface ArchiveSnapshot {
-    /** 归档记忆总数（insight + profile + work-projection） */
     archiveCount: number;
-    /** 关系边总数（ADR-014，relationStore 未注入时为 0） */
-    relationCount: number;
     currentSession: string;
     /** 当前会话全名（含日期前缀） */
     currentSessionName: string;
     hint: string;
     /** 归档记忆来源分布 */
     stats: {
-        insight: number;
-        profile: number;
-        'work-projection': number;
+        'round-summary': number;
     };
 }
 /** Agent 记忆搜索结果（cli 友好的扁平结构） */
 export interface AgentSearchHit {
-    /** 记忆唯一标识（${source}:${name} 格式，供 showMemory/deleteMemory 等操作使用） */
+    /** 记忆唯一标识（${source}:${name} 格式） */
     id: string;
-    /** 记忆名称 */
     name: string;
     /** 来源标签 */
     source: string;
-    /** 权重（0-1） */
-    score: number;
     /** 内容预览（截断到 120 字符） */
     contentPreview: string;
-    /** 语义相似度（0-1，仅 searchHybrid 返回，纯关键词搜索时无此字段） */
-    similarity?: number;
-    /** 创建时间（ISO 8601，供 UI 层时间筛选/排序使用） */
+    /** 创建时间（ISO 8601，供 UI 时间筛选） */
     createdAt?: string;
+    /** 最近使用时间（ISO 8601，工具命中即 touch 刷新，§3.3/§5.2 事实字段：LLM 按此定「最近使用优先」） */
+    accessedAt?: string;
+    /** 溯源（round-summary 命中项）：会话标识（YYYY-MM-DD-sessionName，trace_summary 参数直通） */
+    sessionId?: string;
+    /** 溯源（round-summary 命中项）：轮次 ID（trace_summary 参数直通），LLM 零解析直用 */
+    roundId?: string;
 }
 /** 记忆库统计数据 */
 export interface AgentStats {
@@ -102,386 +72,82 @@ export interface AgentStats {
     bySource: Record<string, number>;
     /** 记忆总数 */
     total: number;
-    /** 关系边总数（ADR-014，relationStore 未注入时为 0） */
-    relationCount: number;
-}
-/** 名称高度相似的候选记忆对（待 LLM 判断语义等价性） */
-export interface DedupPair {
-    /** 记忆 A（score 较高，作为保留候选） */
-    a: Memory;
-    /** 记忆 B（score 较低，作为降级候选） */
-    b: Memory;
-    /** 名称归一化相似度（0-1，越小越相似） */
-    nameSimilarity: number;
-}
-/** LLM 对单对记忆的语义等价判断结果 */
-export interface DedupVerdict {
-    /** 是否语义等价（true → 降级低分记忆） */
-    isDuplicate: boolean;
-    /** 合并后的内容（isDuplicate=true 时提供，保留更完整的信息） */
-    mergedContent?: string;
-    /** LLM 判断理由（便于审计和调试） */
-    reason: string;
-}
-/** 降级记忆的审计详情（DedupReport.verdicts 元素，供 UI 展示"为什么降级"） */
-export interface DedupVerdictSummary {
-    /** 被降级的记忆 ID（与 demotedIds 元素一一对应） */
-    demotedId: string;
-    /** LLM 判断理由（便于用户审计降级是否合理） */
-    reason: string;
-    /** 合并后的完整内容（便于用户验证合并质量；未提供 mergedContent 时省略，渲染器负责截断展示） */
-    mergedContent?: string;
-}
-/** 语义去重报告（deduplicateMemories 返回值） */
-export interface DedupReport {
-    /** 扫描的候选记忆总数 */
-    scannedCount: number;
-    /** 发现的名称相似对数 */
-    pairCount: number;
-    /** LLM 判定为语义等价并执行降级的对数 */
-    deduplicatedCount: number;
-    /** 被降级的记忆 ID 列表（score 降至 DEDUP_LOW_SCORE，未物理删除） */
-    demotedIds: string[];
-    /** 降级审计详情（与 demotedIds 一一对应，供 UI 展示 reason + mergedContentPreview） */
-    verdicts?: DedupVerdictSummary[];
-    /** 跳过原因（LLM 不可用 / 无候选对 / LLM 失败降级） */
-    skippedReason?: string;
 }
 export declare class MemoryInspector {
     private readonly index;
     private readonly loop;
     private readonly history;
-    /** 向量存储（可选，提供时 searchHybrid 启用语义搜索） */
-    private vectorStore;
-    /** 关系存储（可选，ADR-014 侧车，未注入时关系方法静默降级） */
-    private readonly relationStore;
-    /** 记忆顾问（sourceHealth + suggest 委托） */
-    private readonly advisor;
-    /** 后台 LLM Provider（可选，用于语义去重等异步治理任务，未注入时降级跳过） */
-    private readonly backgroundProvider;
-    /**
-     * @param index - 记忆存储（用于读写操作）
-     * @param loop - AgentLoop（用于获取工作记忆）
-     * @param history - MessageHistory（用于获取当前会话信息）
-     * @param advisor - 记忆顾问（组合根一致性，由 assembler.ts 显式注入，必填）
-     * @param relationStore - 关系存储侧车（可选，ADR-014，未注入时关系方法降级返回空/no-op）
-     * @param backgroundProvider - 后台 LLM Provider（可选，用于语义去重，未注入时降级跳过）
-     */
-    constructor(index: IMemoryStorage, loop: AgentLoop, history: MessageHistory, advisor: MemoryAdvisor, relationStore?: IMemoryRelationStore | null, backgroundProvider?: LlmProvider | null);
-    /**
-     * 注入向量存储（由 Agent 在初始化后调用，解决构造时序）
-     */
-    setVectorStore(vs: IVectorStore | null): void;
     /**
-     * 列出回收站中的软删除记忆（只读查询）
-     *
-     * @param limit 返回数量上限（默认 50）
-     * @returns 软删除记忆列表（按 deletedAt 降序）
+     * 构造记忆管理器。sourceHealth/suggest 由 Agent 门面直连 MemoryAdvisor，本类不持有 advisor（消除 3 层代理）。
      */
+    constructor(index: IMemoryStorage, loop: AgentLoop, history: MessageHistory);
+    /** 列出回收站软删除记忆。limit<=0 或 undefined 表示不设上限，否则返回最近 N 条（默认 undefined=全部）。 */
     listDeleted(limit?: number): Memory[];
-    /**
-     * 按 ID 获取单条软删除记忆（只读查询）
-     *
-     * 用于 restore/purge 操作前的存在性校验，避免 listDeleted 默认 50 上限
-     * 导致回收站超量时操作失效。
-     *
-     * @param id 记忆唯一标识
-     * @returns 软删除记忆，不存在或未软删除时返回 null
-     */
+    /** 按 ID 获取软删除记忆（用于 restore/purge 前存在性校验，单条精确查询免全量扫描） */
     getDeletedById(id: string): Memory | null;
-    /**
-     * 按 ID 获取单条活跃记忆（已软删除的返回 null）
-     *
-     * @param id 记忆唯一标识
-     * @returns 记忆对象，不存在或已软删除时返回 null
-     */
+    /** 按 ID 获取单条活跃记忆（已软删除的返回 null） */
     getById(id: string): Memory | null;
-    /**
-     * 按来源标签获取记忆列表
-     *
-     * @param source 来源标签（如 'persona'、'rule'、'insight'）
-     * @returns 该来源的所有记忆
-     */
+    /** 按来源标签获取记忆列表（如 'persona'、'rule'、'round-summary'） */
     getBySource(source: string): Memory[];
     /**
-     * 列出所有记忆（用于宿主项目的记忆管理面板）
-     *
-     * 与 search() 不同，本方法允许空查询，返回按 score 降序排列的记忆列表。
-     * search() 拒绝空查询是为了防止"静默全量返回"的误用；
-     * list() 则是显式声明"我要列出所有记忆"的意图。
-     *
-     * @param limit 返回数量上限（默认 50）
-     * @returns 记忆列表（按 score 降序）
+     * 列出活跃记忆（供宿主记忆管理面板），按 accessedAt 降序。
+     * search() 拒绝空查询防"静默全量返回"误用；list() 是显式声明列举——但**默认仍带 50 条上限**
+     * （安全默认，与 listDeleted 的 undefined=全部 语义刻意不同）。需要全量的调用方须
+     * 显式传入上限（如 stats().total），否则静默截断。
      */
     list(limit?: number): Memory[];
-    /**
-     * 统一查看记忆快照（3 层）
-     *
-     * 简化为 3 层（工作记忆 / Bootstrap / 归档记忆）。
-     *
-     * 设计原则：
-     * - **纯只读**——不动任何组件状态
-     * - **同步返回**——避免数据不一致（不调 LLM、不调 SQLite）
-     * - **轻量**——每层只返回前 N 条 + 总数
-     */
+    /** 统一查看记忆快照（3 层）：纯只读、同步返回、每层只返回前 N 条 + 总数。 */
     snapshot(): MemorySnapshot;
     /**
-     * 搜索记忆（关键词 + FTS5 索引）
-     *
-     * 返回 CLI 友好的扁平结构（已处理内容截断）
+     * @deprecated 本同步通道已退役，功能由 `searchByKeyword()` 承担（后者含
+     * superseded 过滤 / excludeRoundIds 互斥 / accessedAt + 溯源揭示）。当前无生产/宿主消费方，
+     * 勿新增调用。
+     * 搜索记忆（关键词 + FTS5 索引），返回 CLI 友好扁平结构（已截断）。
      */
     search(query: string, limit?: number): AgentSearchHit[];
     /**
-     * 混合搜索记忆（语义 + 关键词双通道）
-     *
-     * 当 VectorStore 可用时，启用语义搜索通道，补强关键词召回的语义缺口。
-     * 向量搜索失败时静默降级到纯关键词（降级优先原则）。
+     * 搜索记忆（纯关键词单通道，无向量通道、无融合排序）。
      *
-     * 融合排序算法已提取到 hybridMerge.ts，与 recall() 共享同一实现，
-     * 避免跨模块常量依赖。
+     * 边界声明（分层分轨）：searchByKeyword 是「记忆搜索工具」，不是召回管线——不应用 L1/L2 分层、
+     * 不进池策略（preference 无条件进池 / intent 排除）、不做 cap 内分配（capTokens / minSemanticShare）。
+     * 分层分轨原属「召回编排」`recall()`；**现行实现中已无任何召回编排**，
+     * 搜索工具只暴露过滤后的结果，供宿主/上层按需自取（见 memory-as-summary §4.5 边界标注）。
      *
-     * @returns 混合排序后的搜索结果（含相似度分数）
-     */
-    searchHybrid(query: string, limit?: number): Promise<AgentSearchHit[]>;
-    /**
-     * 记忆库统计
+     * 无语义（向量）通道：embedding 写端缺失导致语义通道在生产从未生效，
+     * 属于「宣称能力零消费」的僵尸；且主流 agent（Anthropic Memory tool / Claude Code / Librarian Pattern）
+     * 已实证「LLM 消费者 + 小语料」下纯关键词足用——LLM 会自主改述重试（工具描述已提示）。向量语义检索
+     * 的 cache 形态方案记入探索期文档候选，等真实「关键词搜不到」复现再按缓存重算形态补回。
      *
-     * 返回记忆来源分布、数据库大小等关键指标。
-     * 优化：使用 getAllSources() 一次查询替代多次 countBySource + 全量 search，
-     * 复杂度从 O(n*knownSources + n) 降为 O(distinctSources)。
+     * @param excludeRoundIds 排除的轮次 ID 集合（可选）：这些轮次的 round-summary 已被装配期载入正文，
+     *                       不重复返回（工具召回与装配期正文互斥，§5.1）；缺省不过滤。
      */
+    searchByKeyword(query: string, limit?: number, excludeRoundIds?: ReadonlySet<string>): Promise<AgentSearchHit[]>;
+    /** 记忆库统计：用 getAllSources() 一次查询来源分布（含宿主自定义标签），避免逐 source 多次 count */
     stats(): AgentStats;
-    /**
-     * 查询指定记忆的关系边
-     *
-     * ADR-014 侧车模型：关系数据独立于 Memory 7 字段基元，存储在 IMemoryRelationStore。
-     * relationStore 未注入时返回空数组（向后兼容）。
-     *
-     * @param memoryId - 记忆 ID
-     * @param direction - 方向过滤：'outgoing'（出边）/ 'incoming'（入边）/ 'both'（双向，默认）
-     * @returns 关系边数组，按 createdAt 降序
-     */
-    getRelations(memoryId: string, direction?: RelationDirection): MemoryRelation[];
-    /**
-     * 查询全部关系边
-     *
-     * 用于宿主 UI 渲染拓扑可视化（阶段 2.4）。
-     * relationStore 未注入时返回空数组（向后兼容）。
-     *
-     * @returns 全部关系边数组
-     */
-    getAllRelations(): MemoryRelation[];
-    /**
-     * 记忆关系路径追溯（ADR-014 扩展，Phase 5.1）
-     *
-     * 从指定记忆出发，沿关系边追溯来源或去向，返回完整路径。
-     * 用于宿主 UI 展示记忆的演化脉络（如 insight-a → refines → insight-b → follows → insight-c）。
-     *
-     * 防环设计：使用 visited Set 记录已访问节点，防止环导致无限递归。
-     * 深度限制：maxDepth 控制最大追溯步数，防止路径过长。
-     *
-     * relationStore 未注入时返回仅含起点节点的数组（向后兼容，ADR-014 降级优先）。
-     *
-     * @param memoryId - 起点记忆 ID
-     * @param maxDepth - 最大追溯深度（默认 5，防止路径过长）
-     * @param direction - 追溯方向：'incoming'（追溯来源，默认）/ 'outgoing'（追溯去向） / 'both'
-     * @returns 路径节点列表，按 depth 升序（起点在前）
-     */
-    getRelationPath(memoryId: string, maxDepth?: number, direction?: RelationDirection): RelationPath[];
-    /**
-     * 记忆关系邻居查询（ADR-014 扩展，Phase 5.2）
-     *
-     * 返回与指定记忆直接关联的记忆列表，含关系类型和方向。
-     * 用于宿主 UI 展示某记忆的直接关联记忆（如冲突记忆、支持记忆、后续记忆等）。
-     *
-     * relationStore 未注入时返回空数组（向后兼容，ADR-014 降级优先）。
-     *
-     * @param memoryId - 基准记忆 ID
-     * @param limit - 返回数量上限（默认 10，防止过多邻居导致 UI 拥挤）
-     * @returns 邻居记忆列表，含关系类型/权重/方向
-     */
-    getRelationNeighbors(memoryId: string, limit?: number): RelationNeighbor[];
-    /**
-     * 统计关系边总数
-     *
-     * 用于 stats() 和 snapshot() 的 relationCount 字段。
-     * relationStore 未注入时返回 0（向后兼容）。
-     */
-    private countRelations;
-    /**
-     * 记忆源健康诊断（委托给 MemoryAdvisor）
-     *
-     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态）。
-     * 实现已迁移至 MemoryAdvisor，此处保留委托以维持 API 契约。
-     */
-    sourceHealth(): SourceHealthReport;
-    /**
-     * 关联推荐（委托给 MemoryAdvisor）
-     *
-     * 基于 score + 时效性 + source 多样性推荐记忆。
-     * 实现已迁移至 MemoryAdvisor，此处保留委托以维持 API 契约。
-     *
-     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
-     * @param options - 推荐选项
-     */
-    suggest(query?: string, options?: SuggestOptions): SuggestHit[];
-    /**
-     * L3 冲突检测（委托给 MemoryAdvisor.detectConflicts）
-     *
-     * 同 source 内配对，调用 LLM 判断语义冲突，仅检测不修复（需用户决策）。
-     * backgroundProvider 未注入时由 advisor 内部静默跳过（返回 skippedReason 报告）。
-     *
-     * 委托方法存在理由：agent.ts 仅持有 memoryInspector 引用，不直接持有 memoryAdvisor，
-     * 通过此转发保持"inspector 是读写 + 治理统一入口"语义。
-     *
-     * @param signal 可选的 AbortSignal
-     * @returns 冲突报告（扫描数 / 冲突数 / 冲突详情列表 / 跳过原因）
-     */
-    detectConflicts(signal?: AbortSignal): Promise<ConflictReport>;
-    /**
-     * 插入或更新记忆
-     *
-     * @param memory 完整记忆对象
-     */
+    /** 插入或更新记忆 */
     writeUpsert(memory: Memory): void;
-    /**
-     * 提升记忆的 score（L2 采纳反哺内核）
-     *
-     * 用户在补全模块采纳某条候选后，通过 IPC 调用此方法反哺到内核 Memory.score。
-     * 与 recall.ts 的 boostScore 路径语义一致（"越常用越重要"），但触发源不同：
-     *   - recall.ts boostScore：召回时触发（被动）
-     *   - writeBoost：用户主动采纳时触发（主动）
-     *
-     * 设计原则：
-     *   - 复用现有 upsert 路径，不新增存储层接口
-     *   - score 上限 1.0（与 recall.ts SCORE_CEILING 一致）
-     *   - 同步更新 accessedAt，避免被衰减机制误降级
-     *   - 记忆不存在时静默返回 false（补全候选可能来自对话历史，无对应记忆）
-     *
-     * @param id 记忆唯一标识（${source}:${name} 格式）
-     * @param increment score 提升量（默认 0.05，与 recall.ts BOOST_INCREMENT 一致）
-     * @returns 是否成功提升（记忆不存在时返回 false）
-     */
-    writeBoost(id: string, increment?: number): boolean;
-    /**
-     * 软删除记忆（写入 deletedAt）
-     *
-     * @param id 记忆唯一标识（${source}:${name} 格式）
-     */
+    /** 软删除记忆（写入 deletedAt） */
     writeDelete(id: string): void;
     /**
-     * 恢复软删除的记忆（清除 deletedAt）
+     * 随问答闭环删除的摘要记忆软删：Round 引用归 0 被物理删除后联动。
      *
-     * @param id 记忆唯一标识
+     * 软删即脱钩：命中 roundId 的 round-summary 清空溯源（sessionName/roundId）后再软删——
+     * 原会话/轮已不存在（物理回收），溯源悬空无意义；恢复后即为「无需溯源的独立记忆」。
+     * metadata 不在存储契约的保证范围内，故不用标记位，直接清顶层溯源字段最简。
+     * 治理页单条软删（writeDelete）不清溯源：误删恢复仍保留关联。
+     *
+     * @param roundIds 被物理删除（引用归 0）的 Round ID 集合
+     * @returns 软删的摘要数量（0 = 无可联动记忆）
      */
+    softDeleteRoundSummaries(roundIds: string[]): number;
+    /** 恢复软删除记忆（清除 deletedAt） */
     writeRestore(id: string): void;
     /**
-     * 物理删除记忆（不可恢复，用于回收站彻底删除）
-     *
-     * @param id 记忆唯一标识
+     * 物理删除记忆（不可恢复）。IMemoryStorage.purge 为同步 void（无返回值、无异步弧），
+     * 宿主经 IPC 同步消费——无 fire-and-forget/catch 可言，注释按事实陈述。
      */
     writePurge(id: string): void;
-    /**
-     * 清理过期的软删除记忆
-     *
-     * 物理删除所有 deletedAt 早于 before 的记忆。
-     * 由宿主项目的定时器调用（默认 30 天保留期）。
-     *
-     * @param before 时间阈值，deletedAt 早于此值的记忆将被物理删除
-     * @returns 被清理的记忆数量
-     */
+    /** 清理 deletedAt 早于 before 的软删除记忆（宿主定时器调用，默认 30 天保留期） */
     writePurgeExpired(before: Date): number;
-    /**
-     * 添加记忆关系（透传 relationStore）
-     *
-     * 用于宿主 UI 手动创建关系（关系图右键菜单 → 连线 → 创建关系）。
-     * relationStore 未注入时静默降级（不阻塞）。
-     *
-     * @param relation 关系边数据
-     */
-    writeAddRelation(relation: MemoryRelation): void;
-    /**
-     * 删除记忆关系（透传 relationStore）
-     *
-     * 用于宿主 UI 手动删除关系（关系图右键菜单 → 编辑关系 → 删除）。
-     * relationStore 未注入时静默降级（不阻塞）。
-     *
-     * @param sourceId 关系起点
-     * @param targetId 关系终点
-     * @param type 关系类型
-     */
-    writeRemoveRelation(sourceId: string, targetId: string, type: string): void;
-    /**
-     * 语义去重：扫描名称高度相似的记忆对，调用 LLM 判断语义等价性
-     *
-     * 流程：
-     *   1. 从 insight/profile/work-projection 加载候选记忆（上限 50 条）
-     *   2. 按名称归一化 Levenshtein 距离筛选相似对（上限 10 对）
-     *   3. 对每对调用 LLM 判断语义等价性（结构化 JSON 输出）
-     *   4. 等价则降级低分记忆（score → 0.1，不物理删除，保留可恢复性）
-     *   5. 返回去重报告
-     *
-     * 安全设计：
-     *   - 不物理删除——仅降级 score，用户可通过宿主 UI 手动恢复
-     *   - LLM 失败降级——返回已处理的报告，不阻塞调用方
-     *   - 异步执行——不阻塞主对话热路径（由宿主定时任务或用户手动触发）
-     *   - backgroundProvider 未注入时静默跳过（返回 skippedReason）
-     *
-     * @param signal 可选的 AbortSignal（取消正在进行的 LLM 判断）
-     * @returns 去重报告
-     */
-    deduplicateMemories(signal?: AbortSignal): Promise<DedupReport>;
-    /**
-     * 筛选名称高度相似的候选记忆对
-     *
-     * 判定规则（满足任一即视为名称相似）：
-     *   1. 归一化 Levenshtein 距离 ≤ 0.3（如 "用户偏好" vs "用户偏爱"）
-     *   2. 一个名称包含另一个（如 "用户偏好" vs "用户偏好设置"）
-     *
-     * 去重设计：
-     *   - 已配对的记忆不再参与后续配对（避免 A-B-C 三元组产生 A-B + A-C + B-C 三对）
-     *   - 候选对按相似度升序排列（越相似越优先），取前 10 对
-     *
-     * @param candidates 候选记忆列表（已按 score 降序）
-     * @returns 名称相似的记忆对列表（a.score ≥ b.score）
-     */
-    private findNameOverlapPairs;
-    /**
-     * 计算两个名称的归一化相似度（0-1，越小越相似）
-     *
-     * 综合两种规则取较小值：
-     *   1. 归一化 Levenshtein 距离 = distance / max(len_a, len_b)
-     *   2. 包含关系：若一个名称包含另一个，相似度 = 0（完全相似）
-     *
-     * @param nameA 名称 A
-     * @param nameB 名称 B
-     * @returns 相似度（0=完全相似，1=完全不同）
-     */
-    private static computeNameSimilarity;
-    /**
-     * 调用 LLM 判断单对记忆的语义等价性
-     *
-     * 使用结构化 JSON 输出（isDuplicate + mergedContent + reason），
-     * 参照 SessionArchiver.generateSummary 的 parseLlmJson 模式。
-     *
-     * LLM 失败时抛出异常（由 deduplicateMemories 捕获并降级跳过此对）。
-     *
-     * @param pair 候选记忆对
-     * @param signal 可选的 AbortSignal
-     * @returns LLM 判断结果
-     */
-    private judgeDuplicate;
-    /**
-     * 降级重复记忆（score → DEDUP_LOW_SCORE，可选合并内容）
-     *
-     * 安全设计：
-     *   - 不物理删除，仅降低 score，保留可恢复性
-     *   - 若提供 mergedContent，更新保留记忆（a）的 content 为合并后内容
-     *   - 通过 upsert 覆盖原记忆（保持 id/source/name/createdAt 不变）
-     *
-     * @param memory 待降级的记忆（低分方）
-     * @param mergedContent 可选的合并后内容（更新到保留方，由调用方负责）
-     */
-    private demoteMemory;
 }
 //# sourceMappingURL=memoryInspector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"memoryInspector.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryInspector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memoryInspector.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryInspector.ts"],"names":[],"mappings":"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"}