@zooique/memora 2.0.0 → 3.0.0

package/dist/agent/managers/memoryInspector.js

@@ -1,16 +1,6 @@
 import { SOURCE_LABELS } from '../../memory/types.js';
-import { byScoreDesc } from '../../utils/array.js';
 import { configError } from '../../utils/errors.js';
-import { nowIso } from '../../utils/time.js';
 import { truncate } from '../../utils/strings.js';
-import { logger } from '../../logging/logger.js';
-// 双通道融合排序算法 + 常量从 hybridMerge 导入（不再绕道 recall.ts）
-// 消除"agent 模块依赖 memory/recall.ts 内部常量"的分层违规
-import { hybridMerge, RECALL_LIMIT_MULTIPLIER, } from '../../memory/hybridMerge.js';
-// parseLlmJson 用于解析 LLM 去重判断结果（与 SessionArchiver 同模式）
-import { parseLlmJson } from '../../utils/json.js';
-// levenshtein 用于名称相似度计算（复用 sourceValidation 中的实现，避免重复造轮子）
-import { levenshtein } from '../../memory/sourceValidation.js';
 // ─── 常量 ────────────────────────────────────────────────
 /** 工作记忆预览条数（最近 N 条） */
 const WORKING_PREVIEW = 5;
@@ -18,143 +8,57 @@ const WORKING_PREVIEW = 5;
 const CONTENT_PREVIEW_LEN = 80;
 /** 搜索结果内容预览字符数（比快照层略长，便于用户判断相关性） */
 const SEARCH_PREVIEW_LEN = 120;
-// ─── L2 采纳反哺常量 ────────────────────────────────────
-/** 采纳反哺的 score 提升量（与 recall.ts 的 BOOST_INCREMENT 一致，保持"越常用越重要"语义统一） */
-const ADOPTION_BOOST_INCREMENT = 0.05;
-/** score 上限（与 recall.ts 的 SCORE_CEILING 一致，防止 boost 超过 1.0） */
-const SCORE_CEILING = 1.0;
-// ─── L1 语义去重常量 ────────────────────────────────────
-/** 参与去重扫描的 source 标签（与衰减范围一致，不扫描配置型记忆） */
-const DEDUP_SOURCES = [SOURCE_LABELS.INSIGHT, SOURCE_LABELS.PROFILE, SOURCE_LABELS.WORK_PROJECTION];
-/** 单次去重扫描的候选记忆条数上限（控制内存和 LLM 调用量） */
-const DEDUP_CANDIDATE_LIMIT = 50;
-/** 单次 LLM 判断的候选对数上限（每对约 200 tokens，10 对 ≈ 2000 tokens） */
-const DEDUP_PAIR_LIMIT = 10;
-/** 名称相似度阈值（归一化 Levenshtein 距离 ≤ 此值视为名称高度相似，进入 LLM 判断） */
-const DEDUP_NAME_SIMILARITY_THRESHOLD = 0.3;
-/** LLM 去重判断超时（ms），与 TextPolishManager 一致 */
-const DEDUP_TIMEOUT_MS = 15_000;
-/** 被判定为重复的记忆降级到此 score（接近 0 但保留可恢复性，不物理删除） */
-const DEDUP_LOW_SCORE = 0.1;
-/** 候选记忆内容预览长度（截断后送入 LLM，控制 token 消耗） */
-const DEDUP_CONTENT_PREVIEW_LEN = 200;
 // ─── 类 ──────────────────────────────────────────────────
 export class MemoryInspector {
     index;
     loop;
     history;
-    /** 向量存储（可选，提供时 searchHybrid 启用语义搜索） */
-    vectorStore = null;
-    /** 关系存储（可选，ADR-014 侧车，未注入时关系方法静默降级） */
-    relationStore;
-    /** 记忆顾问（sourceHealth + suggest 委托） */
-    advisor;
-    /** 后台 LLM Provider（可选，用于语义去重等异步治理任务，未注入时降级跳过） */
-    backgroundProvider;
     /**
-     * @param index - 记忆存储（用于读写操作）
-     * @param loop - AgentLoop（用于获取工作记忆）
-     * @param history - MessageHistory（用于获取当前会话信息）
-     * @param advisor - 记忆顾问（组合根一致性，由 assembler.ts 显式注入，必填）
-     * @param relationStore - 关系存储侧车（可选，ADR-014，未注入时关系方法降级返回空/no-op）
-     * @param backgroundProvider - 后台 LLM Provider（可选，用于语义去重，未注入时降级跳过）
+     * 构造记忆管理器。sourceHealth/suggest 由 Agent 门面直连 MemoryAdvisor，本类不持有 advisor（消除 3 层代理）。
      */
-    constructor(index, loop, history, advisor, relationStore = null, backgroundProvider = null) {
+    constructor(index, loop, history) {
         this.index = index;
         this.loop = loop;
         this.history = history;
-        // 组合根一致性——advisor 由 assembler.ts 显式注入（必填，不再内部创建）
-        this.advisor = advisor;
-        this.relationStore = relationStore;
-        this.backgroundProvider = backgroundProvider;
-    }
-    /**
-     * 注入向量存储（由 Agent 在初始化后调用，解决构造时序）
-     */
-    setVectorStore(vs) {
-        this.vectorStore = vs;
     }
     // ─── 只读查询（IMemoryStorage 透传） ───────────────────
-    // 写操作以 writeXxx 前缀命名，集中在本类末尾的"写操作"section。
-    /**
-     * 列出回收站中的软删除记忆（只读查询）
-     *
-     * @param limit 返回数量上限（默认 50）
-     * @returns 软删除记忆列表（按 deletedAt 降序）
-     */
-    listDeleted(limit = 50) {
+    /** 列出回收站软删除记忆。limit<=0 或 undefined 表示不设上限，否则返回最近 N 条（默认 undefined=全部）。 */
+    listDeleted(limit) {
         return this.index.listDeleted(limit);
     }
-    /**
-     * 按 ID 获取单条软删除记忆（只读查询）
-     *
-     * 用于 restore/purge 操作前的存在性校验，避免 listDeleted 默认 50 上限
-     * 导致回收站超量时操作失效。
-     *
-     * @param id 记忆唯一标识
-     * @returns 软删除记忆，不存在或未软删除时返回 null
-     */
+    /** 按 ID 获取软删除记忆（用于 restore/purge 前存在性校验，单条精确查询免全量扫描） */
     getDeletedById(id) {
         return this.index.getDeletedById(id);
     }
-    /**
-     * 按 ID 获取单条活跃记忆（已软删除的返回 null）
-     *
-     * @param id 记忆唯一标识
-     * @returns 记忆对象，不存在或已软删除时返回 null
-     */
+    /** 按 ID 获取单条活跃记忆（已软删除的返回 null） */
     getById(id) {
         return this.index.getById(id);
     }
-    /**
-     * 按来源标签获取记忆列表
-     *
-     * @param source 来源标签（如 'persona'、'rule'、'insight'）
-     * @returns 该来源的所有记忆
-     */
+    /** 按来源标签获取记忆列表（如 'persona'、'rule'、'round-summary'） */
     getBySource(source) {
         return this.index.getBySource(source);
     }
     /**
-     * 列出所有记忆（用于宿主项目的记忆管理面板）
-     *
-     * 与 search() 不同，本方法允许空查询，返回按 score 降序排列的记忆列表。
-     * search() 拒绝空查询是为了防止"静默全量返回"的误用；
-     * list() 则是显式声明"我要列出所有记忆"的意图。
-     *
-     * @param limit 返回数量上限（默认 50）
-     * @returns 记忆列表（按 score 降序）
+     * 列出活跃记忆（供宿主记忆管理面板），按 accessedAt 降序。
+     * search() 拒绝空查询防"静默全量返回"误用；list() 是显式声明列举——但**默认仍带 50 条上限**
+     * （安全默认，与 listDeleted 的 undefined=全部 语义刻意不同）。需要全量的调用方须
+     * 显式传入上限（如 stats().total），否则静默截断。
      */
     list(limit = 50) {
         return this.index.search('', limit);
     }
     // ─── 快照 ─────────────────────────────────────────────
-    /**
-     * 统一查看记忆快照（3 层）
-     *
-     * 简化为 3 层（工作记忆 / Bootstrap / 归档记忆）。
-     *
-     * 设计原则：
-     * - **纯只读**——不动任何组件状态
-     * - **同步返回**——避免数据不一致（不调 LLM、不调 SQLite）
-     * - **轻量**——每层只返回前 N 条 + 总数
-     */
+    /** 统一查看记忆快照（3 层）：纯只读、同步返回、每层只返回前 N 条 + 总数。 */
     snapshot() {
         // 第 1 层：工作记忆（AgentLoop 的 messages 数组）
         const workingFull = this.loop.getMessages();
         const workingTotal = workingFull.length;
         const working = workingFull.slice(-WORKING_PREVIEW);
-        // 第 2 层：Bootstrap 记忆（永驻 + 领域）
-        // 直接按 source 查询，避免 search('', 50) 全量扫描
-        const rules = this.index.getBySource(SOURCE_LABELS.RULE);
-        const personas = this.index.getBySource(SOURCE_LABELS.PERSONA);
-        const skills = this.index.getBySource(SOURCE_LABELS.SKILL);
-        const bootstrap = [...rules, ...personas, ...skills];
-        // 第 3 层：归档记忆计数（insight + profile + work-projection）
-        const insightCount = this.index.countBySource(SOURCE_LABELS.INSIGHT);
-        const profileCount = this.index.countBySource(SOURCE_LABELS.PROFILE);
-        const workProjectionCount = this.index.countBySource(SOURCE_LABELS.WORK_PROJECTION);
-        const archiveTotal = insightCount + profileCount + workProjectionCount;
+        // 第 2 层 Bootstrap 恒空：设定记忆唯一归角色包，索引不再新增，rolePackPrompt 承载规则注入。
+        // 保留空壳形状。宿主治理面走 stats/list/searchByKeyword，不消费本层。
+        // 第 3 层：归档记忆计数（round-summary，记忆库唯一对话记忆）
+        const roundSummaryCount = this.index.countBySource(SOURCE_LABELS.ROUND_SUMMARY);
+        const archiveTotal = roundSummaryCount;
         return {
             working: {
                 total: workingTotal,
@@ -165,35 +69,26 @@ export class MemoryInspector {
                 })),
             },
             bootstrap: {
-                total: bootstrap.length,
-                items: bootstrap.map((m) => ({
-                    id: m.id,
-                    source: m.source,
-                    name: m.name,
-                    contentPreview: m.content.slice(0, CONTENT_PREVIEW_LEN),
-                    score: m.score,
-                })),
+                total: 0,
+                items: [],
             },
             archive: {
                 archiveCount: archiveTotal,
-                // ADR-014 关系边总数（relationStore 未注入时为 0）
-                relationCount: this.countRelations(),
                 currentSession: this.history.session ?? '(none)',
                 currentSessionName: this.history.currentSessionName ?? '(none)',
                 hint: '调 listAllSessions() 获取文件清单',
                 stats: {
-                    insight: insightCount,
-                    profile: profileCount,
-                    'work-projection': workProjectionCount,
+                    'round-summary': roundSummaryCount,
                 },
             },
         };
     }
     // ─── 搜索 ─────────────────────────────────────────────
     /**
-     * 搜索记忆（关键词 + FTS5 索引）
-     *
-     * 返回 CLI 友好的扁平结构（已处理内容截断）
+     * @deprecated 本同步通道已退役，功能由 `searchByKeyword()` 承担（后者含
+     * superseded 过滤 / excludeRoundIds 互斥 / accessedAt + 溯源揭示）。当前无生产/宿主消费方，
+     * 勿新增调用。
+     * 搜索记忆（关键词 + FTS5 索引），返回 CLI 友好扁平结构（已截断）。
      */
     search(query, limit = 10) {
         // 空 query 会让 search() 退化为"返回所有"，对宿主程序是静默误导
@@ -213,26 +108,30 @@ export class MemoryInspector {
             id: m.id,
             name: m.name,
             source: m.source,
-            score: m.score,
             // 截断长内容到搜索预览长度
             contentPreview: truncate(m.content, SEARCH_PREVIEW_LEN),
             createdAt: m.createdAt,
         }));
     }
     /**
-     * 混合搜索记忆（语义 + 关键词双通道）
+     * 搜索记忆（纯关键词单通道，无向量通道、无融合排序）。
      *
-     * 当 VectorStore 可用时，启用语义搜索通道，补强关键词召回的语义缺口。
-     * 向量搜索失败时静默降级到纯关键词（降级优先原则）。
+     * 边界声明（分层分轨）：searchByKeyword 是「记忆搜索工具」，不是召回管线——不应用 L1/L2 分层、
+     * 不进池策略（preference 无条件进池 / intent 排除）、不做 cap 内分配（capTokens / minSemanticShare）。
+     * 分层分轨原属「召回编排」`recall()`；**现行实现中已无任何召回编排**，
+     * 搜索工具只暴露过滤后的结果，供宿主/上层按需自取（见 memory-as-summary §4.5 边界标注）。
      *
-     * 融合排序算法已提取到 hybridMerge.ts，与 recall() 共享同一实现，
-     * 避免跨模块常量依赖。
+     * 无语义（向量）通道：embedding 写端缺失导致语义通道在生产从未生效，
+     * 属于「宣称能力零消费」的僵尸；且主流 agent（Anthropic Memory tool / Claude Code / Librarian Pattern）
+     * 已实证「LLM 消费者 + 小语料」下纯关键词足用——LLM 会自主改述重试（工具描述已提示）。向量语义检索
+     * 的 cache 形态方案记入探索期文档候选，等真实「关键词搜不到」复现再按缓存重算形态补回。
      *
-     * @returns 混合排序后的搜索结果（含相似度分数）
+     * @param excludeRoundIds 排除的轮次 ID 集合（可选）：这些轮次的 round-summary 已被装配期载入正文，
+     *                       不重复返回（工具召回与装配期正文互斥，§5.1）；缺省不过滤。
      */
-    async searchHybrid(query, limit = 10) {
+    async searchByKeyword(query, limit = 10, excludeRoundIds) {
         if (!query || query.trim() === '') {
-            throw configError('搜索关键词为空', 'searchHybrid() 需要非空 query', [
+            throw configError('搜索关键词为空', 'searchByKeyword() 需要非空 query', [
                 '传入非空字符串关键词',
             ]);
         }
@@ -241,640 +140,97 @@ export class MemoryInspector {
                 '使用 limit = 10（默认值）',
             ]);
         }
-        const merged = new Map();
-        // ── 通道 1：语义搜索（VectorStore 可用时） ──
-        if (this.vectorStore && this.vectorStore.size > 0) {
-            try {
-                const vectorResults = await this.vectorStore.search(query, limit * RECALL_LIMIT_MULTIPLIER, 0.3);
-                for (const vr of vectorResults) {
-                    const memory = this.index.getById(vr.id);
-                    if (memory) {
-                        merged.set(memory.id, { memory, vectorScore: vr.similarity });
-                    }
-                }
-            }
-            catch (err) {
-                logger.debug({ err }, '语义搜索失败，降级到关键词');
-            }
-        }
-        // ── 通道 2：关键词搜索（补齐语义通道未覆盖的） ──
-        const keywordResults = this.index.search(query, limit * RECALL_LIMIT_MULTIPLIER);
-        for (const m of keywordResults) {
-            if (!merged.has(m.id)) {
-                merged.set(m.id, { memory: m, vectorScore: 0 });
-            }
-        }
-        // ── 综合排序：委托给 hybridMerge 纯函数（与 recall() 共享） ──
-        const sorted = hybridMerge(merged.values(), limit);
-        return sorted.map(({ memory, vectorScore }) => ({
+        // 单个通道：纯关键词搜索（无向量通道、无融合排序，FTS 索引已按相关性返回）
+        const keywordResults = this.index.search(query, limit);
+        // 前置 superseded 过滤：被 supersededBy 取代的摘要不作为当前事实
+        // 返回（仍保留可回溯，trace_summary 可精确取原文）。在截断前过滤，避免占据 top-N 槽位挤掉有效命中。
+        const active = keywordResults.filter((m) => !m.supersededBy);
+        // 工具召回与装配期内容互斥（§5.1）：排除「正文或摘要已在眼前」轮次的 round-summary，
+        // 避免 LLM 拿回眼前内容的摘要重复（excludeRoundIds 由调用方按 loop.getExclusionRoundIds 精确派生，
+        // = 视图内 ∪ 被替换 ∪ 在途，天然不含当轮）。
+        // 被排除者不补位（工具语义）：返回更聚焦的结果即可，不强制凑满 limit。
+        const unexcluded = excludeRoundIds && excludeRoundIds.size > 0
+            ? active.filter((m) => !m.roundId || !excludeRoundIds.has(m.roundId))
+            : active;
+        // 截断到 limit；不引入 accessedAt 时间主序（§5.2 定案）——
+        // accessedAt 只作为事实字段揭示（工具命中 touch 刷新），优先级判断归 LLM 结合任务定夺。
+        const result = unexcluded.slice(0, limit);
+        return result.map((memory) => ({
             id: memory.id,
             name: memory.name,
             source: memory.source,
-            score: memory.score,
-            similarity: vectorScore,
             contentPreview: truncate(memory.content, SEARCH_PREVIEW_LEN),
             createdAt: memory.createdAt,
+            accessedAt: memory.accessedAt,
+            // 结构化溯源（§3.3「返回」行）：round-summary 命中项显式附 sessionId/roundId，
+            // 与 trace_summary 参数直通——LLM 零解析直用，不得隐式编码进 name 字段。
+            // 字段值源：round-summary 顶层持久化 sessionName（= YYYY-MM-DD-sessionName，即 trace_summary 的 sessionId）
+            // + roundId；metadata 不在存储契约的保证范围内，故不从 metadata 读。
+            sessionId: memory.sessionName,
+            roundId: memory.roundId,
         }));
     }
     // ─── 统计 ─────────────────────────────────────────────
-    /**
-     * 记忆库统计
-     *
-     * 返回记忆来源分布、数据库大小等关键指标。
-     * 优化：使用 getAllSources() 一次查询替代多次 countBySource + 全量 search，
-     * 复杂度从 O(n*knownSources + n) 降为 O(distinctSources)。
-     */
+    /** 记忆库统计：用 getAllSources() 一次查询来源分布（含宿主自定义标签），避免逐 source 多次 count */
     stats() {
         const total = this.index.count();
-        // 直接使用 getAllSources() 获取所有 source 分布（含宿主自定义标签）
         const sourceMap = this.index.getAllSources();
         const bySource = {};
         for (const [source, count] of sourceMap) {
             if (count > 0)
                 bySource[source] = count;
         }
-        return { bySource, total, relationCount: this.countRelations() };
-    }
-    // ─── 关系查询（ADR-014 侧车） ───────────────────────────
-    /**
-     * 查询指定记忆的关系边
-     *
-     * ADR-014 侧车模型：关系数据独立于 Memory 7 字段基元，存储在 IMemoryRelationStore。
-     * relationStore 未注入时返回空数组（向后兼容）。
-     *
-     * @param memoryId - 记忆 ID
-     * @param direction - 方向过滤：'outgoing'（出边）/ 'incoming'（入边）/ 'both'（双向，默认）
-     * @returns 关系边数组，按 createdAt 降序
-     */
-    getRelations(memoryId, direction = 'both') {
-        if (!this.relationStore)
-            return [];
-        return this.relationStore.getRelations(memoryId, direction);
-    }
-    /**
-     * 查询全部关系边
-     *
-     * 用于宿主 UI 渲染拓扑可视化（阶段 2.4）。
-     * relationStore 未注入时返回空数组（向后兼容）。
-     *
-     * @returns 全部关系边数组
-     */
-    getAllRelations() {
-        if (!this.relationStore)
-            return [];
-        return this.relationStore.getAllRelations();
-    }
-    // 关系写操作以 writeAddRelation / writeRemoveRelation 命名，见本类末尾"写操作"section。
-    /**
-     * 记忆关系路径追溯（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, maxDepth = 5, direction = 'incoming') {
-        // 起点节点（无论 relationStore 是否注入都返回）
-        const startMemory = this.index.getById(memoryId);
-        const path = [
-            {
-                memoryId,
-                memoryName: startMemory?.name ?? '(unknown)',
-                memorySource: startMemory?.source ?? '(unknown)',
-                relationType: null,
-                relationWeight: null,
-                depth: 0,
-            },
-        ];
-        // relationStore 未注入时仅返回起点（降级优先，ADR-014）
-        if (!this.relationStore)
-            return path;
-        // BFS 遍历，visited 防环
-        const visited = new Set([memoryId]);
-        const queue = [
-            { id: memoryId, depth: 0, relationType: '', relationWeight: 0 },
-        ];
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (current.depth >= maxDepth)
-                continue;
-            const relations = this.relationStore.getRelations(current.id, direction);
-            for (const rel of relations) {
-                // direction='incoming' 时邻居是 sourceId；'outgoing' 时邻居是 targetId
-                const neighborId = direction === 'incoming' ? rel.sourceId : rel.targetId;
-                if (visited.has(neighborId))
-                    continue;
-                visited.add(neighborId);
-                const neighborMemory = this.index.getById(neighborId);
-                path.push({
-                    memoryId: neighborId,
-                    memoryName: neighborMemory?.name ?? '(unknown)',
-                    memorySource: neighborMemory?.source ?? '(unknown)',
-                    relationType: rel.type,
-                    relationWeight: rel.weight,
-                    depth: current.depth + 1,
-                });
-                queue.push({
-                    id: neighborId,
-                    depth: current.depth + 1,
-                    relationType: rel.type,
-                    relationWeight: rel.weight,
-                });
-            }
-        }
-        return path;
-    }
-    /**
-     * 记忆关系邻居查询（ADR-014 扩展，Phase 5.2）
-     *
-     * 返回与指定记忆直接关联的记忆列表，含关系类型和方向。
-     * 用于宿主 UI 展示某记忆的直接关联记忆（如冲突记忆、支持记忆、后续记忆等）。
-     *
-     * relationStore 未注入时返回空数组（向后兼容，ADR-014 降级优先）。
-     *
-     * @param memoryId - 基准记忆 ID
-     * @param limit - 返回数量上限（默认 10，防止过多邻居导致 UI 拥挤）
-     * @returns 邻居记忆列表，含关系类型/权重/方向
-     */
-    getRelationNeighbors(memoryId, limit = 10) {
-        // relationStore 未注入时返回空数组（降级优先，ADR-014）
-        if (!this.relationStore)
-            return [];
-        const neighbors = [];
-        const seen = new Set(); // 去重（同一邻居可能有多条关系）
-        // outgoing：memoryId 是 sourceId，邻居是 targetId
-        const outgoing = this.relationStore.getRelations(memoryId, 'outgoing');
-        for (const rel of outgoing) {
-            if (seen.has(rel.targetId))
-                continue;
-            seen.add(rel.targetId);
-            const neighborMemory = this.index.getById(rel.targetId);
-            neighbors.push({
-                memoryId: rel.targetId,
-                memoryName: neighborMemory?.name ?? '(unknown)',
-                memorySource: neighborMemory?.source ?? '(unknown)',
-                memoryScore: neighborMemory?.score ?? 0,
-                relationType: rel.type,
-                relationWeight: rel.weight,
-                direction: 'outgoing',
-            });
-        }
-        // incoming：memoryId 是 targetId，邻居是 sourceId
-        const incoming = this.relationStore.getRelations(memoryId, 'incoming');
-        for (const rel of incoming) {
-            if (seen.has(rel.sourceId))
-                continue;
-            seen.add(rel.sourceId);
-            const neighborMemory = this.index.getById(rel.sourceId);
-            neighbors.push({
-                memoryId: rel.sourceId,
-                memoryName: neighborMemory?.name ?? '(unknown)',
-                memorySource: neighborMemory?.source ?? '(unknown)',
-                memoryScore: neighborMemory?.score ?? 0,
-                relationType: rel.type,
-                relationWeight: rel.weight,
-                direction: 'incoming',
-            });
-        }
-        return neighbors.slice(0, limit);
-    }
-    /**
-     * 统计关系边总数
-     *
-     * 用于 stats() 和 snapshot() 的 relationCount 字段。
-     * relationStore 未注入时返回 0（向后兼容）。
-     */
-    countRelations() {
-        if (!this.relationStore)
-            return 0;
-        return this.relationStore.getAllRelations().length;
-    }
-    // ─── 源健康诊断 + 关联推荐（委托给 MemoryAdvisor） ───
-    /**
-     * 记忆源健康诊断（委托给 MemoryAdvisor）
-     *
-     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态）。
-     * 实现已迁移至 MemoryAdvisor，此处保留委托以维持 API 契约。
-     */
-    sourceHealth() {
-        return this.advisor.sourceHealth();
-    }
-    /**
-     * 关联推荐（委托给 MemoryAdvisor）
-     *
-     * 基于 score + 时效性 + source 多样性推荐记忆。
-     * 实现已迁移至 MemoryAdvisor，此处保留委托以维持 API 契约。
-     *
-     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
-     * @param options - 推荐选项
-     */
-    suggest(query, options) {
-        return this.advisor.suggest(query, options);
-    }
-    /**
-     * L3 冲突检测（委托给 MemoryAdvisor.detectConflicts）
-     *
-     * 同 source 内配对，调用 LLM 判断语义冲突，仅检测不修复（需用户决策）。
-     * backgroundProvider 未注入时由 advisor 内部静默跳过（返回 skippedReason 报告）。
-     *
-     * 委托方法存在理由：agent.ts 仅持有 memoryInspector 引用，不直接持有 memoryAdvisor，
-     * 通过此转发保持"inspector 是读写 + 治理统一入口"语义。
-     *
-     * @param signal 可选的 AbortSignal
-     * @returns 冲突报告（扫描数 / 冲突数 / 冲突详情列表 / 跳过原因）
-     */
-    async detectConflicts(signal) {
-        return this.advisor.detectConflicts(signal);
+        return { bySource, total };
     }
-    // ─── 写操作（writeXxx 前缀，IMemoryStorage / IMemoryRelationStore 透传） ───
-    /**
-     * 插入或更新记忆
-     *
-     * @param memory 完整记忆对象
-     */
+    // ─── 写操作（writeXxx 前缀，IMemoryStorage 透传） ───
+    /** 插入或更新记忆 */
     writeUpsert(memory) {
         this.index.upsert(memory);
     }
-    /**
-     * 提升记忆的 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, increment = ADOPTION_BOOST_INCREMENT) {
-        const memory = this.index.getById(id);
-        if (!memory)
-            return false;
-        const boosted = {
-            ...memory,
-            score: Math.min(SCORE_CEILING, memory.score + increment),
-            accessedAt: nowIso(),
-        };
-        this.index.upsert(boosted);
-        return true;
-    }
-    /**
-     * 软删除记忆（写入 deletedAt）
-     *
-     * @param id 记忆唯一标识（${source}:${name} 格式）
-     */
+    /** 软删除记忆（写入 deletedAt） */
     writeDelete(id) {
         this.index.delete(id);
     }
     /**
-     * 恢复软删除的记忆（清除 deletedAt）
+     * 随问答闭环删除的摘要记忆软删：Round 引用归 0 被物理删除后联动。
+     *
+     * 软删即脱钩：命中 roundId 的 round-summary 清空溯源（sessionName/roundId）后再软删——
+     * 原会话/轮已不存在（物理回收），溯源悬空无意义；恢复后即为「无需溯源的独立记忆」。
+     * metadata 不在存储契约的保证范围内，故不用标记位，直接清顶层溯源字段最简。
+     * 治理页单条软删（writeDelete）不清溯源：误删恢复仍保留关联。
      *
-     * @param id 记忆唯一标识
+     * @param roundIds 被物理删除（引用归 0）的 Round ID 集合
+     * @returns 软删的摘要数量（0 = 无可联动记忆）
      */
+    softDeleteRoundSummaries(roundIds) {
+        if (roundIds.length === 0)
+            return 0;
+        const idSet = new Set(roundIds);
+        let count = 0;
+        for (const memory of this.index.getBySource(SOURCE_LABELS.ROUND_SUMMARY)) {
+            if (memory.roundId && idSet.has(memory.roundId)) {
+                // 脱钩溯源（覆盖写为无溯源副本，仅清除顶层字段不动内容/权重）→ 软删进回收站
+                this.index.upsert({ ...memory, sessionName: undefined, roundId: undefined });
+                this.index.delete(memory.id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /** 恢复软删除记忆（清除 deletedAt） */
     writeRestore(id) {
         this.index.restore(id);
     }
     /**
-     * 物理删除记忆（不可恢复，用于回收站彻底删除）
-     *
-     * @param id 记忆唯一标识
+     * 物理删除记忆（不可恢复）。IMemoryStorage.purge 为同步 void（无返回值、无异步弧），
+     * 宿主经 IPC 同步消费——无 fire-and-forget/catch 可言，注释按事实陈述。
      */
     writePurge(id) {
         this.index.purge(id);
     }
-    /**
-     * 清理过期的软删除记忆
-     *
-     * 物理删除所有 deletedAt 早于 before 的记忆。
-     * 由宿主项目的定时器调用（默认 30 天保留期）。
-     *
-     * @param before 时间阈值，deletedAt 早于此值的记忆将被物理删除
-     * @returns 被清理的记忆数量
-     */
+    /** 清理 deletedAt 早于 before 的软删除记忆（宿主定时器调用，默认 30 天保留期） */
     writePurgeExpired(before) {
         return this.index.purgeExpired(before);
     }
-    /**
-     * 添加记忆关系（透传 relationStore）
-     *
-     * 用于宿主 UI 手动创建关系（关系图右键菜单 → 连线 → 创建关系）。
-     * relationStore 未注入时静默降级（不阻塞）。
-     *
-     * @param relation 关系边数据
-     */
-    writeAddRelation(relation) {
-        if (!this.relationStore)
-            return;
-        this.relationStore.addRelation(relation);
-    }
-    /**
-     * 删除记忆关系（透传 relationStore）
-     *
-     * 用于宿主 UI 手动删除关系（关系图右键菜单 → 编辑关系 → 删除）。
-     * relationStore 未注入时静默降级（不阻塞）。
-     *
-     * @param sourceId 关系起点
-     * @param targetId 关系终点
-     * @param type 关系类型
-     */
-    writeRemoveRelation(sourceId, targetId, type) {
-        if (!this.relationStore)
-            return;
-        this.relationStore.removeRelation(sourceId, targetId, type);
-    }
-    // ─── LLM 记忆治理（异步，backgroundProvider 未注入时静默降级） ───
-    /**
-     * 语义去重：扫描名称高度相似的记忆对，调用 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 去重报告
-     */
-    async deduplicateMemories(signal) {
-        // backgroundProvider 未注入时静默降级（向后兼容）
-        if (!this.backgroundProvider) {
-            return {
-                scannedCount: 0,
-                pairCount: 0,
-                deduplicatedCount: 0,
-                demotedIds: [],
-                skippedReason: 'backgroundProvider 未注入',
-            };
-        }
-        // ── 步骤 1：加载候选记忆（按 score 降序，取前 50 条） ──
-        const candidates = [];
-        for (const source of DEDUP_SOURCES) {
-            const memories = this.index.getBySource(source);
-            candidates.push(...memories);
-        }
-        // 按 score 降序排列，优先处理高分记忆（更可能产生重复）
-        candidates.sort(byScoreDesc);
-        const limited = candidates.slice(0, DEDUP_CANDIDATE_LIMIT);
-        // ── 步骤 2：筛选名称高度相似的记忆对 ──
-        const pairs = this.findNameOverlapPairs(limited);
-        if (pairs.length === 0) {
-            return {
-                scannedCount: limited.length,
-                pairCount: 0,
-                deduplicatedCount: 0,
-                demotedIds: [],
-                skippedReason: '未发现名称相似的记忆对',
-            };
-        }
-        // ── 步骤 3：逐对调用 LLM 判断语义等价性 ──
-        const demotedIds = [];
-        const verdicts = [];
-        let deduplicatedCount = 0;
-        for (const pair of pairs) {
-            try {
-                const verdict = await this.judgeDuplicate(pair, signal);
-                if (verdict.isDuplicate) {
-                    // 降级低分记忆（b 的 score ≤ a 的 score，因 candidates 已按 score 降序）
-                    this.demoteMemory(pair.b, verdict.mergedContent);
-                    demotedIds.push(pair.b.id);
-                    // 收集审计详情（供 UI 展示"为什么降级"和"合并后保留了什么"）
-                    verdicts.push({
-                        demotedId: pair.b.id,
-                        reason: verdict.reason,
-                        mergedContent: verdict.mergedContent,
-                    });
-                    deduplicatedCount++;
-                    logger.info({ demotedId: pair.b.id, keptId: pair.a.id, reason: verdict.reason }, '语义去重：降级重复记忆');
-                }
-            }
-            catch (err) {
-                // 单对 LLM 判断失败不阻塞后续对，记录警告继续
-                logger.warn({ err, pairId: `${pair.a.id}↔${pair.b.id}` }, '语义去重：LLM 判断失败，跳过此对');
-            }
-        }
-        return {
-            scannedCount: limited.length,
-            pairCount: pairs.length,
-            deduplicatedCount,
-            demotedIds,
-            verdicts,
-        };
-    }
-    /**
-     * 筛选名称高度相似的候选记忆对
-     *
-     * 判定规则（满足任一即视为名称相似）：
-     *   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）
-     */
-    findNameOverlapPairs(candidates) {
-        const pairs = [];
-        const usedIds = new Set();
-        // 双重循环生成所有可能的对，按相似度排序后贪心选取
-        const allPairs = [];
-        for (let i = 0; i < candidates.length; i++) {
-            for (let j = i + 1; j < candidates.length; j++) {
-                const a = candidates[i]; // i 循环内，score 较高
-                const b = candidates[j]; // j > i，score 较低或相等
-                const similarity = MemoryInspector.computeNameSimilarity(a.name, b.name);
-                if (similarity <= DEDUP_NAME_SIMILARITY_THRESHOLD) {
-                    allPairs.push({ a, b, nameSimilarity: similarity });
-                }
-            }
-        }
-        // 按相似度升序排列（越相似越优先处理）
-        allPairs.sort((x, y) => x.nameSimilarity - y.nameSimilarity);
-        // 贪心选取：已配对的记忆不再参与后续配对
-        for (const { a, b, nameSimilarity } of allPairs) {
-            if (usedIds.has(a.id) || usedIds.has(b.id))
-                continue;
-            pairs.push({ a, b, nameSimilarity });
-            usedIds.add(a.id);
-            usedIds.add(b.id);
-            if (pairs.length >= DEDUP_PAIR_LIMIT)
-                break;
-        }
-        return pairs;
-    }
-    /**
-     * 计算两个名称的归一化相似度（0-1，越小越相似）
-     *
-     * 综合两种规则取较小值：
-     *   1. 归一化 Levenshtein 距离 = distance / max(len_a, len_b)
-     *   2. 包含关系：若一个名称包含另一个，相似度 = 0（完全相似）
-     *
-     * @param nameA 名称 A
-     * @param nameB 名称 B
-     * @returns 相似度（0=完全相似，1=完全不同）
-     */
-    static computeNameSimilarity(nameA, nameB) {
-        // 规则 2：包含关系（如 "用户偏好" vs "用户偏好设置"）
-        if (nameA.includes(nameB) || nameB.includes(nameA)) {
-            return 0;
-        }
-        // 规则 1：归一化 Levenshtein 距离
-        const maxLen = Math.max(nameA.length, nameB.length);
-        if (maxLen === 0)
-            return 0; // 两个空字符串视为完全相似
-        const distance = levenshtein(nameA, nameB);
-        return distance / maxLen;
-    }
-    /**
-     * 调用 LLM 判断单对记忆的语义等价性
-     *
-     * 使用结构化 JSON 输出（isDuplicate + mergedContent + reason），
-     * 参照 SessionArchiver.generateSummary 的 parseLlmJson 模式。
-     *
-     * LLM 失败时抛出异常（由 deduplicateMemories 捕获并降级跳过此对）。
-     *
-     * @param pair 候选记忆对
-     * @param signal 可选的 AbortSignal
-     * @returns LLM 判断结果
-     */
-    async judgeDuplicate(pair, signal) {
-        const messages = buildDedupMessages(pair);
-        let llmResponse = '';
-        // 流式累积模式（与 TextPolishManager / SessionArchiver 一致）
-        for await (const chunk of this.backgroundProvider.chat(messages, {
-            maxTokens: 300,
-            temperature: 0,
-            timeoutMs: DEDUP_TIMEOUT_MS,
-            signal,
-        })) {
-            if (chunk.content)
-                llmResponse += chunk.content;
-        }
-        // 解析 LLM 响应（JSON 格式）
-        const parsed = parseLlmJson(llmResponse.trim());
-        if (!parsed) {
-            throw new Error('LLM 去重判断返回非法 JSON');
-        }
-        return {
-            isDuplicate: parsed.isDuplicate === true,
-            mergedContent: typeof parsed.mergedContent === 'string' ? parsed.mergedContent : undefined,
-            reason: typeof parsed.reason === 'string' ? parsed.reason : '(LLM 未提供理由)',
-        };
-    }
-    /**
-     * 降级重复记忆（score → DEDUP_LOW_SCORE，可选合并内容）
-     *
-     * 安全设计：
-     *   - 不物理删除，仅降低 score，保留可恢复性
-     *   - 若提供 mergedContent，更新保留记忆（a）的 content 为合并后内容
-     *   - 通过 upsert 覆盖原记忆（保持 id/source/name/createdAt 不变）
-     *
-     * @param memory 待降级的记忆（低分方）
-     * @param mergedContent 可选的合并后内容（更新到保留方，由调用方负责）
-     */
-    demoteMemory(memory, mergedContent) {
-        const demoted = {
-            ...memory,
-            score: DEDUP_LOW_SCORE,
-            // 更新 accessedAt，标记最近被处理过
-            accessedAt: nowIso(),
-        };
-        this.index.upsert(demoted);
-        // 若提供合并内容，调用方可通过 writeUpsert 单独更新保留方
-        // 此处不直接修改保留方，保持职责单一（仅降级低分方）
-        if (mergedContent) {
-            logger.debug({ demotedId: memory.id, mergedContentLen: mergedContent.length }, '语义去重：合并内容已生成（需调用方手动更新保留方）');
-        }
-    }
-}
-// ─── L1 语义去重 Prompt 模板（模块级函数，与 TextPolishManager.buildPolishMessages 同模式） ───
-/**
- * 构建语义去重判断的 LLM 消息
- *
- * 设计要点：
- *   - system 消息定义判断规则（语义等价 = 表达同一事实/偏好/洞察）
- *   - user 消息携带候选对的内容预览（截断到 200 字符）
- *   - 要求输出结构化 JSON（isDuplicate + mergedContent + reason）
- *   - few-shot 示例降低 LLM 误判率
- *
- * @param pair 候选记忆对
- * @returns system + user 消息数组
- */
-function buildDedupMessages(pair) {
-    const contentA = pair.a.content.length > DEDUP_CONTENT_PREVIEW_LEN
-        ? truncate(pair.a.content, DEDUP_CONTENT_PREVIEW_LEN, '…[截断]')
-        : pair.a.content;
-    const contentB = pair.b.content.length > DEDUP_CONTENT_PREVIEW_LEN
-        ? truncate(pair.b.content, DEDUP_CONTENT_PREVIEW_LEN, '…[截断]')
-        : pair.b.content;
-    return [
-        {
-            role: 'system',
-            content: `你是记忆去重助手。判断给定的两条记忆是否语义等价（表达同一事实/偏好/洞察）。
-
-判断规则：
-- 语义等价 = 核心信息相同，仅措辞/格式/细节程度不同
-- 语义不等价 = 核心信息不同，或一条是另一条的补充/细化（非等价）
-- 忽略时间戳、ID 等元数据差异
-- 忽略措辞风格差异（如"喜欢"vs"偏爱"）
-
-输出 JSON 格式：
-{
-  "isDuplicate": true/false,
-  "mergedContent": "合并后的内容（仅 isDuplicate=true 时提供，保留两条记忆的完整信息）",
-  "reason": "判断理由（简短说明）"
-}
-
-示例：
-输入 A: "用户偏好简洁的 UI 设计"
-输入 B: "用户喜欢简洁的界面风格"
-输出: {"isDuplicate": true, "mergedContent": "用户偏好简洁的 UI/界面设计风格", "reason": "核心偏好相同，仅措辞差异"}
-
-输入 A: "用户是 TypeScript 开发者"
-输入 B: "用户偏好使用 TypeScript 进行后端开发"
-输出: {"isDuplicate": false, "reason": "B 是 A 的细化（限定后端），非语义等价"}`,
-        },
-        {
-            role: 'user',
-            content: `请判断以下两条记忆是否语义等价：
-
-记忆 A（score: ${pair.a.score}，保留候选）：
-- 名称：${pair.a.name}
-- 来源：${pair.a.source}
-- 内容：${contentA}
-
-记忆 B（score: ${pair.b.score}，降级候选）：
-- 名称：${pair.b.name}
-- 来源：${pair.b.source}
-- 内容：${contentB}
-
-名称相似度：${pair.nameSimilarity.toFixed(2)}（0=完全相同，1=完全不同）
-
-请输出 JSON 判断结果。`,
-        },
-    ];
 }
 //# sourceMappingURL=memoryInspector.js.map