@zooique/memora 0.1.0

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

@@ -0,0 +1,96 @@
+import type { IMemoryStorage } from '../../memory/storageInterface.js';
+/** 记忆源健康状态 */
+export type SourceHealthStatus = 'healthy' | 'warning' | 'critical';
+/** 单个 source 的健康指标 */
+export interface SourceHealthEntry {
+    /** 来源标签 */
+    source: string;
+    /** 记忆数量 */
+    count: number;
+    /** 平均 score（0-1） */
+    avgScore: number;
+    /** 距上次访问的天数（取该 source 中最近访问的记忆） */
+    daysSinceLastAccess: number;
+    /** 健康状态：healthy（score≥0.5 且 7 天内有访问）/ warning（score<0.5 或 7-30 天未访问）/ critical（score<0.2 或 30 天以上未访问） */
+    status: SourceHealthStatus;
+}
+/** 记忆源健康诊断报告 */
+export interface SourceHealthReport {
+    /** 各 source 健康指标 */
+    sources: SourceHealthEntry[];
+    /** 整体健康状态（取最差 source 的状态） */
+    overallStatus: SourceHealthStatus;
+    /** 诊断时间（ISO 8601） */
+    diagnosedAt: string;
+}
+/** 关联推荐选项 */
+export interface SuggestOptions {
+    /** 返回数量上限（默认 5） */
+    limit?: number;
+    /** 排除的 source 标签（默认排除 persona、rule、skill） */
+    excludeSources?: string[];
+    /** 时效性权重（0-1，默认 0.3）：越高越偏好最近访问的记忆 */
+    recencyWeight?: number;
+}
+/** 关联推荐结果 */
+export interface SuggestHit {
+    /** 记忆名称 */
+    name: string;
+    /** 来源标签 */
+    source: string;
+    /** 推荐分数（0-1，由 score + recency 综合计算） */
+    relevance: number;
+    /** 内容预览（截断到 120 字符） */
+    contentPreview: string;
+    /** 推荐理由 */
+    reason: string;
+}
+/**
+ * 记忆顾问
+ *
+ * 从 MemoryInspector 拆分（QC-R2-11），负责基于记忆数据的分析计算：
+ *   - sourceHealth()：记忆源健康诊断（数量、score、新鲜度）
+ *   - suggest()：关联推荐（基于 score + 时效性 + 多样性）
+ *
+ * 与 MemoryInspector 的分工：
+ *   - MemoryInspector：直接数据查询（snapshot/search/stats/relations + 写操作代理）
+ *   - MemoryAdvisor：分析计算（健康诊断 + 推荐排序）
+ */
+export declare class MemoryAdvisor {
+    private readonly index;
+    /**
+     * @param index - 记忆存储（只读访问，用于健康诊断和推荐计算）
+     */
+    constructor(index: IMemoryStorage);
+    /**
+     * 记忆源健康诊断
+     *
+     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态），
+     * 帮助宿主项目判断是否需要触发衰减、清理或补充。
+     *
+     * 健康状态判定：
+     * - healthy：avgScore ≥ 0.5 且 7 天内有访问
+     * - warning：avgScore < 0.5 或 7-30 天未访问
+     * - critical：avgScore < 0.2 或 30 天以上未访问
+     *
+     * 纯只读、同步、不调 LLM，与 stats() 互补（stats 只有数量，本方法有质量指标）。
+     * P2-2 优化：使用 getAllSources() 发现所有 source 标签，替代全量 search。
+     */
+    sourceHealth(): SourceHealthReport;
+    /**
+     * 关联推荐：基于已有记忆数据，推荐你可能感兴趣的记忆
+     *
+     * 不调 LLM，纯计算。综合 score（权重）+ accessedAt（时效性）+ source 多样性，
+     * 返回"与你当前关注点相关但尚未直接搜索到"的记忆。
+     *
+     * 适用场景：
+     * - 用户搜索后，展示"你可能还想看"
+     * - 对话开始时，展示"最近你可能关心的记忆"
+     * - 宿主程序构建个性化推荐面板
+     *
+     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
+     * @param options - 推荐选项
+     */
+    suggest(query?: string, options?: SuggestOptions): SuggestHit[];
+}
+//# sourceMappingURL=memoryAdvisor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoryAdvisor.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryAdvisor.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAyBnE,cAAc;AACd,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpE,sBAAsB;AACtB,MAAM,WAAW,iBAAiB;IAChC,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yGAAyG;IACzG,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,gBAAgB;AAChB,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,6BAA6B;IAC7B,aAAa,EAAE,kBAAkB,CAAC;IAClC,qBAAqB;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,aAAa;AACb,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,aAAa;AACb,MAAM,WAAW,UAAU;IACzB,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IAIZ,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC;;OAEG;gBAC0B,KAAK,EAAE,cAAc;IAIlD;;;;;;;;;;;;;OAaG;IACH,YAAY,IAAI,kBAAkB;IAiElC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,UAAU,EAAE;CAmFpE"}

package/dist/agent/managers/memoryAdvisor.js

@@ -0,0 +1,198 @@
+import { SOURCE_LABELS } from '../../memory/types.js';
+import { ONE_DAY_MS } from '../../memory/recall.js';
+// ─── 常量 ────────────────────────────────────────────────
+/** 关联推荐：每个 source 采样 top-N 条 */
+const SUGGEST_TOP_PER_SOURCE = 3;
+/** 关联推荐：时效性衰减窗口（天），超过此天数归零 */
+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,
+};
+// ─── 类 ──────────────────────────────────────────────────
+/**
+ * 记忆顾问
+ *
+ * 从 MemoryInspector 拆分（QC-R2-11），负责基于记忆数据的分析计算：
+ *   - sourceHealth()：记忆源健康诊断（数量、score、新鲜度）
+ *   - suggest()：关联推荐（基于 score + 时效性 + 多样性）
+ *
+ * 与 MemoryInspector 的分工：
+ *   - MemoryInspector：直接数据查询（snapshot/search/stats/relations + 写操作代理）
+ *   - MemoryAdvisor：分析计算（健康诊断 + 推荐排序）
+ */
+export class MemoryAdvisor {
+    index;
+    /**
+     * @param index - 记忆存储（只读访问，用于健康诊断和推荐计算）
+     */
+    constructor(index) {
+        this.index = index;
+    }
+    // ─── 源健康诊断 ─────────────────────────────────────────
+    /**
+     * 记忆源健康诊断
+     *
+     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态），
+     * 帮助宿主项目判断是否需要触发衰减、清理或补充。
+     *
+     * 健康状态判定：
+     * - healthy：avgScore ≥ 0.5 且 7 天内有访问
+     * - warning：avgScore < 0.5 或 7-30 天未访问
+     * - critical：avgScore < 0.2 或 30 天以上未访问
+     *
+     * 纯只读、同步、不调 LLM，与 stats() 互补（stats 只有数量，本方法有质量指标）。
+     * P2-2 优化：使用 getAllSources() 发现所有 source 标签，替代全量 search。
+     */
+    sourceHealth() {
+        const now = Date.now();
+        // P2-2 使用 getAllSources() 获取所有有数据的 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）
+            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';
+            }
+            entries.push({
+                source,
+                count,
+                avgScore: Math.round(avgScore * 1000) / 1000,
+                daysSinceLastAccess: Math.round(daysSinceLastAccess * 10) / 10,
+                status,
+            });
+        }
+        // 整体状态取最差 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,
+            diagnosedAt: new Date().toISOString(),
+        };
+    }
+    // ─── 关联推荐 ─────────────────────────────────────────
+    /**
+     * 关联推荐：基于已有记忆数据，推荐你可能感兴趣的记忆
+     *
+     * 不调 LLM，纯计算。综合 score（权重）+ accessedAt（时效性）+ source 多样性，
+     * 返回"与你当前关注点相关但尚未直接搜索到"的记忆。
+     *
+     * 适用场景：
+     * - 用户搜索后，展示"你可能还想看"
+     * - 对话开始时，展示"最近你可能关心的记忆"
+     * - 宿主程序构建个性化推荐面板
+     *
+     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
+     * @param options - 推荐选项
+     */
+    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 now = Date.now();
+        // 收集候选记忆
+        const candidates = new Map();
+        // 如果有 query，先搜索直接匹配的记忆（标记为 searchHit）
+        if (query && query.trim()) {
+            const directHits = this.index.search(query, limit * 3);
+            for (const m of directHits) {
+                if (!excludeSources.includes(m.source)) {
+                    candidates.set(m.id, { memory: m, searchHit: true });
+                }
+            }
+        }
+        // 补充：按 source 分组采样，确保来源多样性
+        const knownSources = [SOURCE_LABELS.INSIGHT, SOURCE_LABELS.PROFILE, SOURCE_LABELS.WORK_PROJECTION];
+        for (const source of knownSources) {
+            const count = this.index.countBySource(source);
+            if (count > 0 && !excludeSources.includes(source)) {
+                const memories = this.index.getBySource(source);
+                // 取 score 最高的前 N 条
+                const top = memories.sort((a, b) => b.score - a.score).slice(0, SUGGEST_TOP_PER_SOURCE);
+                for (const m of top) {
+                    if (!candidates.has(m.id)) {
+                        candidates.set(m.id, { memory: m, searchHit: false });
+                    }
+                }
+            }
+        }
+        if (candidates.size === 0)
+            return [];
+        // 计算综合推荐分数
+        const scored = [];
+        for (const { memory, searchHit } of candidates.values()) {
+            // 时效性分：窗口内线性衰减，超过窗口归零
+            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;
+            // 生成推荐理由
+            let reason;
+            if (searchHit) {
+                reason = '与搜索相关';
+            }
+            else if (daysSinceAccess < 1) {
+                reason = '最近访问';
+            }
+            else if (memory.score >= 0.8) {
+                reason = '高频记忆';
+            }
+            else {
+                reason = `${memory.source} 推荐`;
+            }
+            scored.push({ memory, searchHit, relevance, reason });
+        }
+        // 排序：搜索命中优先，然后按 relevance 降序
+        scored.sort((a, b) => {
+            if (a.searchHit !== b.searchHit)
+                return a.searchHit ? -1 : 1;
+            return b.relevance - a.relevance;
+        });
+        return scored.slice(0, limit).map(({ memory, relevance, reason }) => ({
+            name: memory.name,
+            source: memory.source,
+            relevance: Math.round(relevance * 100) / 100,
+            contentPreview: memory.content.length > ADVISOR_PREVIEW_LEN ? memory.content.slice(0, ADVISOR_PREVIEW_LEN) + '...' : memory.content,
+            reason,
+        }));
+    }
+}
+//# sourceMappingURL=memoryAdvisor.js.map

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

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

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

@@ -0,0 +1,231 @@
+/**
+ * 记忆查看器 — 统一查看记忆快照 + 搜索 + 统计
+ *
+ * 从 Agent 拆分出来，负责只读记忆查询操作。
+ *
+ * 设计原则：
+ *   - 纯只读——不动任何组件状态
+ *   - 同步返回——避免数据不一致（不调 LLM、不调 SQLite 写入）
+ *   - 轻量——每层只返回前 N 条 + 总数
+ */
+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 } from '../../memory/types.js';
+import type { VectorStore } from '../../memory/vectorStore.js';
+import type { MessageHistory } from '../../agent/messageHistory.js';
+import type { AgentLoop } from '../../agent/loop.js';
+import type { SourceHealthReport, SuggestOptions, SuggestHit } from '../../agent/managers/memoryAdvisor.js';
+export type { SourceHealthStatus, SourceHealthEntry, SourceHealthReport, SuggestOptions, SuggestHit, } from '../../agent/managers/memoryAdvisor.js';
+/** 记忆快照 */
+export interface MemorySnapshot {
+    /** 第 1 层：工作记忆（messages 数组） */
+    working: WorkingMemorySnapshot;
+    /** 第 2 层：Bootstrap 记忆（永驻 + 领域） */
+    bootstrap: BootstrapSnapshot;
+    /** 第 3 层：归档洞察（insight 记忆） */
+    archive: ArchiveSnapshot;
+}
+/** 第 1 层：工作记忆快照 */
+export interface WorkingMemorySnapshot {
+    total: number;
+    preview: Array<{
+        role: 'system' | 'user' | 'assistant' | 'tool';
+        contentPreview: string;
+        contentLength: number;
+    }>;
+}
+/** 第 2 层：Bootstrap 记忆快照 */
+export interface BootstrapSnapshot {
+    total: number;
+    items: Array<{
+        id: string;
+        /** 来源标签（开放字符串） */
+        source: string;
+        name: string;
+        contentPreview: string;
+        /** 权重（0-1） */
+        score: number;
+    }>;
+}
+/** 第 3 层：归档记忆快照（insight + profile + work-projection） */
+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;
+    };
+}
+/** Agent 记忆搜索结果（cli 友好的扁平结构） */
+export interface AgentSearchHit {
+    /** 记忆唯一标识（${source}:${name} 格式，供 showMemory/deleteMemory 等操作使用） */
+    id: string;
+    /** 记忆名称 */
+    name: string;
+    /** 来源标签 */
+    source: string;
+    /** 权重（0-1） */
+    score: number;
+    /** 内容预览（截断到 120 字符） */
+    contentPreview: string;
+    /** 语义相似度（0-1，仅 searchHybrid 返回，纯关键词搜索时无此字段） */
+    similarity?: number;
+    /** 创建时间（ISO 8601，供 UI 层时间筛选/排序使用） */
+    createdAt?: string;
+}
+/** 记忆库统计数据 */
+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;
+    /** 记忆顾问（QC-R2-11：sourceHealth + suggest 委托） */
+    private readonly advisor;
+    /**
+     * @param index - 记忆存储（用于搜索 + 统计）
+     * @param loop - AgentLoop（用于获取工作记忆）
+     * @param history - MessageHistory（用于获取当前会话信息）
+     * @param relationStore - 关系存储侧车（可选，ADR-014，未注入时关系相关方法降级返回空）
+     */
+    constructor(index: IMemoryStorage, loop: AgentLoop, history: MessageHistory, relationStore?: IMemoryRelationStore | null);
+    /**
+     * 注入向量存储（由 Agent 在初始化后调用，解决构造时序）
+     */
+    setVectorStore(vs: VectorStore | null): void;
+    /**
+     * 插入或更新记忆
+     *
+     * @param memory 完整记忆对象
+     */
+    upsert(memory: Memory): void;
+    /**
+     * 删除记忆
+     *
+     * @param id 记忆唯一标识（${source}:${name} 格式）
+     */
+    delete(id: string): void;
+    /**
+     * 按 ID 获取单条记忆
+     *
+     * @param id 记忆唯一标识
+     * @returns 记忆对象，不存在时返回 null
+     */
+    getById(id: string): Memory | null;
+    /**
+     * 按来源标签获取记忆列表
+     *
+     * @param source 来源标签（如 'persona'、'rule'、'insight'）
+     * @returns 该来源的所有记忆
+     */
+    getBySource(source: string): Memory[];
+    /**
+     * 列出所有记忆（用于宿主项目的记忆管理面板）
+     *
+     * 与 search() 不同，本方法允许空查询，返回按 score 降序排列的记忆列表。
+     * search() 拒绝空查询是为了防止"静默全量返回"的误用；
+     * list() 则是显式声明"我要列出所有记忆"的意图。
+     *
+     * @param limit 返回数量上限（默认 50）
+     * @returns 记忆列表（按 score 降序）
+     */
+    list(limit?: number): Memory[];
+    /**
+     * 统一查看记忆快照（3 层）
+     *
+     * 简化为 3 层（工作记忆 / Bootstrap / 归档记忆）。
+     *
+     * 设计原则：
+     * - **纯只读**——不动任何组件状态
+     * - **同步返回**——避免数据不一致（不调 LLM、不调 SQLite）
+     * - **轻量**——每层只返回前 N 条 + 总数
+     */
+    snapshot(): MemorySnapshot;
+    /**
+     * 搜索记忆（关键词 + FTS5 索引）
+     *
+     * 返回 CLI 友好的扁平结构（已处理内容截断）
+     */
+    search(query: string, limit?: number): AgentSearchHit[];
+    /**
+     * 混合搜索记忆（语义 + 关键词双通道）
+     *
+     * V-101：当 VectorStore 可用时，启用语义搜索通道，补强关键词召回的语义缺口。
+     * 向量搜索失败时静默降级到纯关键词（降级优先原则）。
+     *
+     * @returns 混合排序后的搜索结果（含相似度分数）
+     */
+    searchHybrid(query: string, limit?: number): Promise<AgentSearchHit[]>;
+    /**
+     * 记忆库统计
+     *
+     * 返回记忆来源分布、数据库大小等关键指标。
+     * P2-2 优化：使用 getAllSources() 一次查询替代多次 countBySource + 全量 search，
+     * 复杂度从 O(n*knownSources + n) 降为 O(distinctSources)。
+     */
+    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[];
+    /**
+     * 统计关系边总数
+     *
+     * 用于 stats() 和 snapshot() 的 relationCount 字段。
+     * relationStore 未注入时返回 0（向后兼容）。
+     */
+    private countRelations;
+    /**
+     * 记忆源健康诊断（委托给 MemoryAdvisor）
+     *
+     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态）。
+     * 实现已迁移至 MemoryAdvisor（QC-R2-11），此处保留委托以维持 API 契约。
+     */
+    sourceHealth(): SourceHealthReport;
+    /**
+     * 关联推荐（委托给 MemoryAdvisor）
+     *
+     * 基于 score + 时效性 + source 多样性推荐记忆。
+     * 实现已迁移至 MemoryAdvisor（QC-R2-11），此处保留委托以维持 API 契约。
+     *
+     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
+     * @param options - 推荐选项
+     */
+    suggest(query?: string, options?: SuggestOptions): SuggestHit[];
+}
+//# sourceMappingURL=memoryInspector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoryInspector.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryInspector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAUjD,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,UAAU,EACX,MAAM,mCAAmC,CAAC;AAG3C,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,UAAU,GACX,MAAM,mCAAmC,CAAC;AAa3C,WAAW;AACX,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,kCAAkC;IAClC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,6BAA6B;IAC7B,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;QACvB,cAAc;QACd,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACJ;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;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;IACd,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;CACvB;AAID,qBAAa,eAAe;IAexB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhB1B,uCAAuC;IACvC,OAAO,CAAC,WAAW,CAA4B;IAC/C,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAC5D,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC;;;;;OAKG;gBAEgB,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,cAAc,EACxC,aAAa,GAAE,oBAAoB,GAAG,IAAW;IAOnD;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAS5C;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIlC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAIrC;;;;;;;;;OASG;IACH,IAAI,CAAC,KAAK,SAAK,GAAG,MAAM,EAAE;IAM1B;;;;;;;;;OASG;IACH,QAAQ,IAAI,cAAc;IA0D1B;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,cAAc,EAAE;IAyBnD;;;;;;;OAOG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAyDxE;;;;;;OAMG;IACH,KAAK,IAAI,UAAU;IAenB;;;;;;;;;OASG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,iBAA0B,GAAG,cAAc,EAAE;IAKvF;;;;;;;OAOG;IACH,eAAe,IAAI,cAAc,EAAE;IAKnC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAOtB;;;;;OAKG;IACH,YAAY,IAAI,kBAAkB;IAIlC;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,EAAE;CAGhE"}