@zooique/memora 2.0.3 → 3.0.1

package/dist/agent/managers/memoryGovernance.js

@@ -1,61 +1,44 @@
 export class MemoryGovernance {
     dedupManager;
-    decayScheduler;
     memoryAdvisor;
-    constructor(dedupManager, decayScheduler, memoryAdvisor) {
+    constructor(dedupManager, memoryAdvisor) {
         this.dedupManager = dedupManager;
-        this.decayScheduler = decayScheduler;
         this.memoryAdvisor = memoryAdvisor;
     }
-    // ── L0 衰减 ──────────────────────────────────────────
-    /**
-     * 手动触发一次记忆衰减（纯 score 递减，无 LLM 调用）
-     */
-    decay() {
-        this.decayScheduler?.runOnce();
-    }
     // ── L1 语义去重 ──────────────────────────────────────
-    /**
-     * 语义去重：扫描名称相似记忆对，LLM 判断等价性，降级重复记忆
-     */
+    /** 语义去重：扫描名称相似记忆对，LLM 判断等价性，降级重复记忆 */
     async deduplicate(signal) {
         if (!this.dedupManager) {
-            return { scannedCount: 0, pairCount: 0, deduplicatedCount: 0, demotedIds: [], skippedReason: 'Agent 未初始化' };
+            return {
+                scannedCount: 0,
+                pairCount: 0,
+                deduplicatedCount: 0,
+                demotedIds: [],
+                skippedReason: 'Agent 未初始化',
+            };
         }
         return this.dedupManager.deduplicateMemories(signal);
     }
-    // ── L2 时效性评估 ────────────────────────────────────
-    /**
-     * 时效性评估：LLM 判断低分记忆是否过时，降级过时记忆
-     */
-    async evaluateTimeliness(signal) {
-        if (!this.decayScheduler) {
-            return { scannedCount: 0, outdatedCount: 0, demotedIds: [], skippedReason: 'Agent 未初始化' };
-        }
-        return this.decayScheduler.evaluateTimeliness(signal);
-    }
     // ── L3 冲突检测 ──────────────────────────────────────
-    /**
-     * 冲突检测：LLM 判断同 source 记忆是否存在语义矛盾
-     */
+    /** 冲突检测：LLM 判断同 source 记忆是否存在语义矛盾 */
     async detectConflicts(signal) {
         if (!this.memoryAdvisor) {
-            return { scannedCount: 0, pairCount: 0, conflictCount: 0, conflicts: [], skippedReason: 'Agent 未初始化' };
+            return {
+                scannedCount: 0,
+                pairCount: 0,
+                conflictCount: 0,
+                conflicts: [],
+                skippedReason: 'Agent 未初始化',
+            };
         }
         return this.memoryAdvisor.detectConflicts(signal);
     }
     // ── 诊断 ─────────────────────────────────────────────
-    /**
-     * 记忆源健康诊断（纯只读，不修改状态）
-     *
-     * @returns 健康报告；advisor 未注入时返回 null
-     */
+    /** 记忆源健康诊断（纯只读）；advisor 未注入返回 null */
     sourceHealth() {
         return this.memoryAdvisor?.sourceHealth() ?? null;
     }
-    /**
-     * 记忆关联推荐（纯只读，不修改状态）
-     */
+    /** 记忆关联推荐（纯只读） */
     suggest(query, options) {
         return this.memoryAdvisor?.suggest(query, options) ?? [];
     }

package/dist/agent/managers/memoryGovernance.js.map

@@ -1 +1 @@
-{"version":3,"file":"memoryGovernance.js","sourceRoot":"","sources":["../../../src/agent/managers/memoryGovernance.ts"],"names":[],"mappings":"AA2BA,MAAM,OAAO,gBAAgB;IAER;IACA;IACA;IAHnB,YACmB,YAAiC,EACjC,cAA2C,EAC3C,aAAmC;QAFnC,iBAAY,GAAZ,YAAY,CAAqB;QACjC,mBAAc,GAAd,cAAc,CAA6B;QAC3C,kBAAa,GAAb,aAAa,CAAsB;IACnD,CAAC;IAEJ,sDAAsD;IAEtD;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,cAAc,EAAE,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,oDAAoD;IAEpD;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,MAAoB;QACpC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;QAC9G,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,mDAAmD;IAEnD;;OAEG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAAoB;QAC3C,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;QAC5F,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACxD,CAAC;IAED,oDAAoD;IAEpD;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,MAAoB;QACxC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;QACzG,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,sDAAsD;IAEtD;;;;OAIG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,aAAa,EAAE,YAAY,EAAE,IAAI,IAAI,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,KAAc,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3D,CAAC;CACF"}
+{"version":3,"file":"memoryGovernance.js","sourceRoot":"","sources":["../../../src/agent/managers/memoryGovernance.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,gBAAgB;IAER;IACA;IAFnB,YACmB,YAAiC,EACjC,aAAmC;QADnC,iBAAY,GAAZ,YAAY,CAAqB;QACjC,kBAAa,GAAb,aAAa,CAAsB;IACnD,CAAC;IAEJ,oDAAoD;IAEpD,sCAAsC;IACtC,KAAK,CAAC,WAAW,CAAC,MAAoB;QACpC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO;gBACL,YAAY,EAAE,CAAC;gBACf,SAAS,EAAE,CAAC;gBACZ,iBAAiB,EAAE,CAAC;gBACpB,UAAU,EAAE,EAAE;gBACd,aAAa,EAAE,YAAY;aAC5B,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,oDAAoD;IAEpD,qCAAqC;IACrC,KAAK,CAAC,eAAe,CAAC,MAAoB;QACxC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO;gBACL,YAAY,EAAE,CAAC;gBACf,SAAS,EAAE,CAAC;gBACZ,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,EAAE;gBACb,aAAa,EAAE,YAAY;aAC5B,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,sDAAsD;IAEtD,sCAAsC;IACtC,YAAY;QACV,OAAO,IAAI,CAAC,aAAa,EAAE,YAAY,EAAE,IAAI,IAAI,CAAC;IACpD,CAAC;IAED,kBAAkB;IAClB,OAAO,CAAC,KAAc,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3D,CAAC;CACF"}

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

@@ -1,45 +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
- *   - 写操作（writeXxx 前缀）：
- *     writeUpsert / writeDelete / writeRestore / writePurge / writePurgeExpired /
- *     writeAddRelation / writeRemoveRelation
- *
- * 拆分历史：
- *   - SPLIT-3（2026-07-21）：L1 语义去重（deduplicateMemories）拆分至 DedupManager
- *   - v2 PROXY-1（2026-07-21）：detectConflicts 直连 MemoryAdvisor（消除 3 层代理）
- *   - FIX-P1-3（2026-07-24）：sourceHealth/suggest 直连 MemoryAdvisor，
- *     删除本类转发方法 + advisor 字段，Agent 作为门面委托 advisor（与
- *     detectConflicts 同模式）。本类回归纯存储读写 + 查询入口。
+ * 记忆管理器 — 统一的记忆读写入口。
+ * 写方法 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';
-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 层：工作记忆快照 */
@@ -60,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 {
@@ -104,259 +72,82 @@ export interface AgentStats {
     bySource: Record<string, number>;
     /** 记忆总数 */
     total: number;
-    /** 关系边总数（ADR-014，relationStore 未注入时为 0） */
-    relationCount: number;
 }
 export declare class MemoryInspector {
     private readonly index;
     private readonly loop;
     private readonly history;
-    /** 向量存储（可选，提供时 searchHybrid 启用语义搜索） */
-    private vectorStore;
-    /** 关系存储（可选，ADR-014 侧车，未注入时关系方法静默降级） */
-    private readonly relationStore;
     /**
-     * FIX-P1-3（2026-07-24）：移除 advisor 参数，sourceHealth/suggest 改由
-     * Agent 直接委托 MemoryAdvisor（与 detectConflicts 同模式），消除 3 层代理。
-     *
-     * @param index - 记忆存储（用于读写操作）
-     * @param loop - AgentLoop（用于获取工作记忆）
-     * @param history - MessageHistory（用于获取当前会话信息）
-     * @param relationStore - 关系存储侧车（可选，ADR-014，未注入时关系方法降级返回空/no-op）
-     */
-    constructor(index: IMemoryStorage, loop: AgentLoop, history: MessageHistory, relationStore?: IMemoryRelationStore | null);
-    /**
-     * 注入向量存储（由 Agent 在初始化后调用，解决构造时序）
-     */
-    setVectorStore(vs: IVectorStore | null): void;
-    /**
-     * 列出回收站中的软删除记忆（只读查询）
-     *
-     * @param limit 返回数量上限。`limit <= 0` 或 `undefined` 表示不设上限（返回全部）；
-     *              正整数 N 表示返回最近 N 条。默认 undefined（全部）。
-     * @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 可用时，启用语义搜索通道，补强关键词召回的语义缺口。
-     * 向量搜索失败时静默降级到纯关键词（降级优先原则）。
+     * 边界声明（分层分轨）：searchByKeyword 是「记忆搜索工具」，不是召回管线——不应用 L1/L2 分层、
+     * 不进池策略（preference 无条件进池 / intent 排除）、不做 cap 内分配（capTokens / minSemanticShare）。
+     * 分层分轨原属「召回编排」`recall()`；**现行实现中已无任何召回编排**，
+     * 搜索工具只暴露过滤后的结果，供宿主/上层按需自取（见 memory-as-summary §4.5 边界标注）。
      *
-     * 融合排序算法已提取到 hybridMerge.ts，与 recall() 共享同一实现，
-     * 避免跨模块常量依赖。
-     *
-     * @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;
-    /**
-     * 插入或更新记忆
-     *
-     * @param memory 完整记忆对象
-     */
+    /** 插入或更新记忆 */
     writeUpsert(memory: Memory): void;
-    /**
-     * 提升记忆的 score（L2 采纳反哺内核）
-     *
-     * 用户在补全模块采纳某条候选后，通过 IPC 调用此方法反哺到内核 Memory.score。
-     * 与 recall.ts 的 boostScore 路径语义一致（"越常用越重要"），但触发源不同：
-     *   - recall.ts boostScore：召回时触发（被动）
-     *   - writeBoost：用户主动采纳时触发（主动）
-     *
-     * 设计原则：
-     *   - 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 被物理删除后联动。
+     *
+     * 软删即脱钩：命中 roundId 的 round-summary 清空溯源（sessionName/roundId）后再软删——
+     * 原会话/轮已不存在（物理回收），溯源悬空无意义；恢复后即为「无需溯源的独立记忆」。
+     * metadata 不在存储契约的保证范围内，故不用标记位，直接清顶层溯源字段最简。
+     * 治理页单条软删（writeDelete）不清溯源：误删恢复仍保留关联。
      *
-     * @param id 记忆唯一标识
+     * @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;
-    /**
-     * 清理过期的软删除记忆（FIX-P0-2：统一编排关系清理）
-     *
-     * 物理删除所有 deletedAt 早于 before 的记忆，并同步清理这些记忆的关系边。
-     * 由宿主项目的定时器调用（默认 30 天保留期）。
-     *
-     * FIX-P0-2 修复说明：
-     *   原实现仅调用 `index.purgeExpired(before)` 物理删除记忆，不清理 memory_relations
-     *   表中的关系边，导致孤儿边残留。手动 purge 路径会清理关系，但自动清理路径遗漏。
-     *   本方法是统一协调点（已持有 relationStore 引用），先查询待清理记忆 → 逐个清理关系边
-     *   → 再物理删除记忆，保证两侧数据一致。
-     *
-     * 容错策略：
-     *   - relationStore 未注入时跳过关系清理，仅物理删除记忆（向后兼容）
-     *   - 单条关系清理失败不阻塞整体流程，记录 warn 日志后继续
-     *
-     * @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;
-    /**
-     * 删除某记忆的所有关系边（透传 relationStore）
-     *
-     * 用于记忆软删除/物理删除场景，防止 memory_relations 表残留孤儿边。
-     * relationStore 未注入时静默降级（不阻塞记忆删除主流程）。
-     *
-     * @param memoryId 记忆 ID
-     * @returns 被删除的关系数量（relationStore 未注入时返回 0）
-     */
-    writeRemoveRelationsByMemoryId(memoryId: string): number;
 }
 //# 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":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAejD,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,yBAAyB;IACzB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,gCAAgC;IAChC,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,mBAAmB;AACnB,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;QAC/C,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ;AAED,2BAA2B;AAC3B,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,kBAAkB;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;CACJ;AAED,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,KAAK,EAAE;QACL,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,cAAc;AACd,MAAM,WAAW,UAAU;IACzB,mBAAmB;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAID,qBAAa,eAAe;IAKxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B;;OAEG;gBAEgB,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,cAAc;IAK1C,0EAA0E;IAC1E,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAIrC,wDAAwD;IACxD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIzC,kCAAkC;IAClC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIlC,sDAAsD;IACtD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAIrC;;;;;OAKG;IACH,IAAI,CAAC,KAAK,SAAK,GAAG,MAAM,EAAE;IAM1B,8CAA8C;IAC9C,QAAQ,IAAI,cAAc;IA0C1B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,cAAc,EAAE;IAwBnD;;;;;;;;;;;;;;;OAeG;IACG,eAAe,CACnB,KAAK,EAAE,MAAM,EACb,KAAK,SAAK,EACV,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,OAAO,CAAC,cAAc,EAAE,CAAC;IA+C5B,qEAAqE;IACrE,KAAK,IAAI,UAAU;IAcnB,cAAc;IACd,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIjC,0BAA0B;IAC1B,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;;;;;;;OAUG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM;IAepD,4BAA4B;IAC5B,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI9B;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,wDAAwD;IACxD,iBAAiB,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM;CAGxC"}