@zooique/memora 2.0.3 → 3.0.1

package/dist/memory/gcService.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 垃圾回收服务 —— 清理孤立的问答闭环和关联摘要
+ *
+ * 设计理念：
+ * - 基于引用计数的自动清理机制
+ * - 只清理 refCount === 0 且超龄的 Round（不分状态：pending/error 崩溃残留同样可回收）
+ * - 同时清理关联的记忆摘要（round-summary）
+ * - 支持定时执行和手动触发
+ *
+ * 触发时机：
+ * 1. 会话删除时，减少引用计数后检查
+ * 2. 定时任务（如每天一次）自动执行（启动时立即执行一次清存量孤儿）
+ * 3. 宿主手动触发（run() 公开入口）
+ */
+import type { IRoundStore } from '../memory/roundStore.js';
+import type { IMemoryStorage } from '../memory/storageInterface.js';
+/**
+ * GC 配置选项
+ */
+export interface GCConfig {
+    /**
+     * 最小存活时间（毫秒）
+     *
+     * 避免清理正在使用的 Round：
+     * - Round 创建后短时间内可能还在被引用
+     * - 默认 5 分钟
+     */
+    minAgeMs: number;
+    /**
+     * 批处理大小
+     *
+     * 避免单次清理过多导致性能问题
+     * - 默认 100
+     */
+    batchSize: number;
+    /**
+     * 是否清理关联的记忆摘要
+     *
+     * - true：删除 Round 时同时删除 round-summary 记忆
+     * - false：只删除 Round，保留摘要（可能导致孤立摘要）
+     * - 默认 true（推荐）
+     */
+    cleanUpMemory: boolean;
+    /**
+     * 是否记录详细日志
+     *
+     * - 默认 false（生产环境避免日志爆炸）
+     */
+    verbose: boolean;
+    /**
+     * 忙碌检查回调（可选）
+     *
+     * 定时 GC 在对话进行中（chatLock busy / 长任务执行中）延迟执行，
+     * 避免进行中 pending Round 被误清（minAgeMs 判龄对长任务不可靠）。
+     * 返回 true = 当前忙，跳过本次 GC。
+     */
+    shouldSkip?: () => boolean;
+}
+/**
+ * GC 结果统计
+ */
+export interface GCResult {
+    /** 扫描的 Round 总数 */
+    scanned: number;
+    /** 发现的孤立 Round 数 */
+    orphaned: number;
+    /** 成功删除的 Round 数 */
+    deleted: number;
+    /** 因引用计数导致删除失败的数量 */
+    failedDueToRefCount: number;
+    /** 清理的记忆摘要数量 */
+    memoryCleaned: number;
+    /** 实际执行的时间（毫秒） */
+    elapsedMs: number;
+}
+/**
+ * 垃圾回收服务
+ *
+ * 使用方式：
+ * ```typescript
+ * const gc = new GCService(roundStore, memoryStorage);
+ *
+ * // 手动触发
+ * const result = gc.run();
+ *
+ * // 配置定时任务
+ * gc.startPeriodic(60 * 60 * 1000); // 每小时执行一次
+ * gc.stopPeriodic();
+ * ```
+ */
+export declare class GCService {
+    private readonly roundStore;
+    private readonly memoryStorage;
+    private readonly config;
+    private timer;
+    constructor(roundStore: IRoundStore, memoryStorage: IMemoryStorage, config?: Partial<GCConfig>);
+    /**
+     * 执行垃圾回收
+     *
+     * 流程：
+     * 1. 忙碌检查（可选 shouldSkip）：对话进行中（长任务执行）跳过本次，
+     *    minAgeMs 判龄对多轮长任务不可靠，防止进行中 pending Round 被误清
+     * 2. 列出所有孤立的 Round（refCount === 0 且超龄，不分状态）
+     * 3. 分批删除孤立 Round
+     * 4. 同时清理关联的记忆摘要（purge 硬删除，不进回收站）
+     *
+     * @returns GC 结果统计
+     */
+    run(): GCResult;
+    /**
+     * 清理 Round 关联的记忆摘要
+     *
+     * 摘要记忆的**规范 ID** 为 `round-summary:{sessionName}:{roundId}`（由
+     * roundSummaryGenerator 构造，含会话段）——Round 侧**不持有反向指针**，
+     * 故此处按 `roundId` 顶层字段反查，覆盖全部会话命名空间。
+     *
+     * 系统治理删除走 purge 物理删除（不进回收站——孤儿摘要是系统清理产物，
+     * 非用户主动删除的数据）。
+     *
+     * @param round - 要清理的 Round
+     */
+    private cleanUpRoundSummary;
+    /**
+     * 物理删除摘要（round-summary 随 Round 引用归零联动清理）
+     *
+     * @param summaryId - 摘要记忆 ID
+     */
+    private purgeSummary;
+    /**
+     * 启动定时 GC
+     *
+     * VSCode 窗口生命周期通常远小于定时周期 → 启动时立即执行一次（run），
+     * 先清存量孤儿，再按周期续跑。
+     *
+     * @param intervalMs - 执行间隔（毫秒）
+     */
+    startPeriodic(intervalMs: number): void;
+    /**
+     * 停止定时 GC
+     */
+    stopPeriodic(): void;
+    /**
+     * 获取当前配置
+     *
+     * @returns GC 配置
+     */
+    getConfig(): Readonly<GCConfig>;
+    /**
+     * 更新配置
+     *
+     * @param partial - 部分配置更新
+     */
+    updateConfig(partial: Partial<GCConfig>): void;
+}
+/**
+ * 创建默认 GC 服务的工厂函数
+ *
+ * @param roundStore - 问答闭环存储
+ * @param memoryStorage - 记忆存储
+ * @param shouldSkip - 忙碌检查回调（可选：对话进行中跳过本次）
+ * @returns GC 服务实例
+ */
+export declare function createDefaultGCService(roundStore: IRoundStore, memoryStorage: IMemoryStorage, shouldSkip?: () => boolean): GCService;
+//# sourceMappingURL=gcService.d.ts.map

package/dist/memory/gcService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcService.d.ts","sourceRoot":"","sources":["../../src/memory/gcService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAInE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,KAAK,CAA+C;gBAEhD,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC;IAY9F;;;;;;;;;;;OAWG;IACH,GAAG,IAAI,QAAQ;IAsEf;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAKpB;;;;;;;OAOG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAgBvC;;OAEG;IACH,YAAY,IAAI,IAAI;IAQpB;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC;IAI/B;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;CAG/C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,WAAW,EACvB,aAAa,EAAE,cAAc,EAC7B,UAAU,CAAC,EAAE,MAAM,OAAO,GACzB,SAAS,CAQX"}

package/dist/memory/gcService.js

@@ -0,0 +1,215 @@
+/**
+ * 垃圾回收服务 —— 清理孤立的问答闭环和关联摘要
+ *
+ * 设计理念：
+ * - 基于引用计数的自动清理机制
+ * - 只清理 refCount === 0 且超龄的 Round（不分状态：pending/error 崩溃残留同样可回收）
+ * - 同时清理关联的记忆摘要（round-summary）
+ * - 支持定时执行和手动触发
+ *
+ * 触发时机：
+ * 1. 会话删除时，减少引用计数后检查
+ * 2. 定时任务（如每天一次）自动执行（启动时立即执行一次清存量孤儿）
+ * 3. 宿主手动触发（run() 公开入口）
+ */
+import { logger } from '../logging/logger.js';
+import { SOURCE_LABELS } from '../memory/types.js';
+/**
+ * 垃圾回收服务
+ *
+ * 使用方式：
+ * ```typescript
+ * const gc = new GCService(roundStore, memoryStorage);
+ *
+ * // 手动触发
+ * const result = gc.run();
+ *
+ * // 配置定时任务
+ * gc.startPeriodic(60 * 60 * 1000); // 每小时执行一次
+ * gc.stopPeriodic();
+ * ```
+ */
+export class GCService {
+    roundStore;
+    memoryStorage;
+    config;
+    timer = null;
+    constructor(roundStore, memoryStorage, config) {
+        this.roundStore = roundStore;
+        this.memoryStorage = memoryStorage;
+        this.config = {
+            minAgeMs: config?.minAgeMs ?? 5 * 60 * 1000, // 5 分钟
+            batchSize: config?.batchSize ?? 100,
+            cleanUpMemory: config?.cleanUpMemory ?? true,
+            verbose: config?.verbose ?? false,
+            shouldSkip: config?.shouldSkip,
+        };
+    }
+    /**
+     * 执行垃圾回收
+     *
+     * 流程：
+     * 1. 忙碌检查（可选 shouldSkip）：对话进行中（长任务执行）跳过本次，
+     *    minAgeMs 判龄对多轮长任务不可靠，防止进行中 pending Round 被误清
+     * 2. 列出所有孤立的 Round（refCount === 0 且超龄，不分状态）
+     * 3. 分批删除孤立 Round
+     * 4. 同时清理关联的记忆摘要（purge 硬删除，不进回收站）
+     *
+     * @returns GC 结果统计
+     */
+    run() {
+        const startTime = Date.now();
+        const result = {
+            scanned: 0,
+            orphaned: 0,
+            deleted: 0,
+            failedDueToRefCount: 0,
+            memoryCleaned: 0,
+            elapsedMs: 0,
+        };
+        // 忙碌检查：对话进行中跳过本次（定时/手动触发均生效）
+        if (this.config.shouldSkip?.()) {
+            logger.debug('GC: 对话进行中（shouldSkip），跳过本次执行');
+            result.elapsedMs = Date.now() - startTime;
+            return result;
+        }
+        try {
+            // 1. 获取所有孤立的 Round
+            // listOrphaned 可能是可选方法，需要检查
+            const listOrphanedFn = this.roundStore.listOrphaned;
+            const orphanedRounds = listOrphanedFn
+                ? listOrphanedFn.call(this.roundStore, this.config.minAgeMs)
+                : [];
+            result.scanned = this.roundStore.listAll().length;
+            result.orphaned = orphanedRounds.length;
+            if (this.config.verbose) {
+                logger.info({ total: result.scanned, orphaned: result.orphaned }, 'GC: 发现孤立问答闭环');
+            }
+            if (orphanedRounds.length === 0) {
+                result.elapsedMs = Date.now() - startTime;
+                return result;
+            }
+            // 2. 分批删除
+            for (let i = 0; i < orphanedRounds.length; i += this.config.batchSize) {
+                const batch = orphanedRounds.slice(i, i + this.config.batchSize);
+                for (const round of batch) {
+                    // 删除 Round
+                    const deleted = this.roundStore.delete(round.id);
+                    if (deleted) {
+                        result.deleted++;
+                        // 同时清理关联的记忆摘要
+                        if (this.config.cleanUpMemory) {
+                            this.cleanUpRoundSummary(round);
+                            result.memoryCleaned++;
+                        }
+                    }
+                    else {
+                        result.failedDueToRefCount++;
+                    }
+                }
+            }
+            if (this.config.verbose) {
+                logger.info({ result: { ...result } }, 'GC: 完成');
+            }
+        }
+        catch (error) {
+            logger.error({ error }, 'GC: 执行失败');
+        }
+        result.elapsedMs = Date.now() - startTime;
+        return result;
+    }
+    /**
+     * 清理 Round 关联的记忆摘要
+     *
+     * 摘要记忆的**规范 ID** 为 `round-summary:{sessionName}:{roundId}`（由
+     * roundSummaryGenerator 构造，含会话段）——Round 侧**不持有反向指针**，
+     * 故此处按 `roundId` 顶层字段反查，覆盖全部会话命名空间。
+     *
+     * 系统治理删除走 purge 物理删除（不进回收站——孤儿摘要是系统清理产物，
+     * 非用户主动删除的数据）。
+     *
+     * @param round - 要清理的 Round
+     */
+    cleanUpRoundSummary(round) {
+        // 按 roundId 顶层字段反查全部会话命名空间的两段式摘要
+        const roundSummaries = this.memoryStorage
+            .getBySource(SOURCE_LABELS.ROUND_SUMMARY)
+            .filter((m) => m.roundId === round.id);
+        for (const summary of roundSummaries) {
+            this.purgeSummary(summary.id);
+        }
+    }
+    /**
+     * 物理删除摘要（round-summary 随 Round 引用归零联动清理）
+     *
+     * @param summaryId - 摘要记忆 ID
+     */
+    purgeSummary(summaryId) {
+        // purge = 物理删除（不可恢复），孤儿摘要是系统治理决定，不进用户回收站
+        this.memoryStorage.purge(summaryId);
+    }
+    /**
+     * 启动定时 GC
+     *
+     * VSCode 窗口生命周期通常远小于定时周期 → 启动时立即执行一次（run），
+     * 先清存量孤儿，再按周期续跑。
+     *
+     * @param intervalMs - 执行间隔（毫秒）
+     */
+    startPeriodic(intervalMs) {
+        if (this.timer) {
+            logger.warn('GC: 定时任务已启动，忽略重复调用');
+            return;
+        }
+        // 启动即执行一次：窗口生命周期内可能等不到首个周期，先清存量孤儿
+        this.run();
+        this.timer = setInterval(() => {
+            this.run();
+        }, intervalMs);
+        logger.info({ intervalMs }, 'GC: 定时任务已启动');
+    }
+    /**
+     * 停止定时 GC
+     */
+    stopPeriodic() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            logger.info('GC: 定时任务已停止');
+        }
+    }
+    /**
+     * 获取当前配置
+     *
+     * @returns GC 配置
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * 更新配置
+     *
+     * @param partial - 部分配置更新
+     */
+    updateConfig(partial) {
+        Object.assign(this.config, partial);
+    }
+}
+/**
+ * 创建默认 GC 服务的工厂函数
+ *
+ * @param roundStore - 问答闭环存储
+ * @param memoryStorage - 记忆存储
+ * @param shouldSkip - 忙碌检查回调（可选：对话进行中跳过本次）
+ * @returns GC 服务实例
+ */
+export function createDefaultGCService(roundStore, memoryStorage, shouldSkip) {
+    return new GCService(roundStore, memoryStorage, {
+        minAgeMs: 5 * 60 * 1000, // 5 分钟最小存活时间
+        batchSize: 100,
+        cleanUpMemory: true,
+        verbose: false,
+        shouldSkip,
+    });
+}
+//# sourceMappingURL=gcService.js.map

package/dist/memory/gcService.js.map

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

package/dist/memory/governance.d.ts

@@ -1,50 +1,17 @@
 /**
- * LLM 治理源列表 — 参与去重 / 冲突检测 / 时效性评估 / 衰减的 source 集合
+ * 记忆治理共享常量 — 治理源列表。
+ * 排序单归语义分：使用轨迹唯一事实源为 accessedAt，无 score 写位/排序/clamp 位。
+ * 纯常量模块（零依赖，仅类型 import），被 agent/managers 多模块消费，符合 agent → memory 单向依赖。
  *
- * 不含配置型记忆（persona / rule / skill），这些是启动时加载的永驻记忆，
- * 不参与运行时治理。如未来扩展治理范围，仅需修改此数组。
+ * 治理模型：supersede（写时取代）；无衰减——
+ * 摘要是事实记录无"过时"语义，记忆有效性由 superseded 写时取代判定，
+ * 低频记忆经相关性排序自然后移退出召回面，无"沉底/自然遗忘归档"语义。
  */
-export declare const GOVERNANCE_SOURCES: readonly string[];
 /**
- * score 提升量 — "越常用越重要"语义统一
- *
- * 消费者：
- *   - recall.ts boostScore：召回时触发（被动）
- *   - memoryInspector.writeBoost：用户主动采纳时触发（主动）
- */
-export declare const BOOST_INCREMENT = 0.05;
-/**
- * score 上限 — 防止 boost 超过 1.0
- *
- * 消费者：recall.ts / memoryInspector.ts
+ * 治理源列表：实际写入记忆库的 source 才参与去重 / 冲突治理。
+ * 当前记忆库唯一自动轨 = round-summary（摘要即记忆本体，见 memory-as-summary.md），
+ * 其治理由 superseded 写时取代承担，不入本数组；content 历史残留 source 无生产写入路径。
+ * 空列表时 dedup/冲突检测空转（测试可显式注入治理源）。
  */
-export declare const SCORE_CEILING = 1;
-/**
- * score 下限 — 衰减/demote 的底线（MIND2-L3：incrementScore clamp 下限）
- *
- * 消费者：
- *   - recall.ts applyDecayToMemory（衰减下限）
- *   - InMemoryStorage / SqliteStorage incrementScore（clamp 下限）
- */
-export declare const DECAY_FLOOR = 0.1;
-/**
- * 衰减：未访问天数阈值（天）— 超过此天数才开始衰减
- *
- * 消费者：
- *   - recall.ts applyDecayToMemory（内存衰减判断）
- *   - SqliteStorage.decayScores（SQL 衰减 WHERE 条件）
- *
- * 修改时必须同步两处（v2 神木回天：消除跨层重复硬编码）
- */
-export declare const DECAY_AGE_DAYS = 7;
-/**
- * 衰减：每过一个周期 score 降低量
- *
- * 消费者：
- *   - recall.ts applyDecayToMemory（内存衰减计算）
- *   - SqliteStorage.decayScores（SQL 衰减 SET 计算）
- *
- * 修改时必须同步两处（v2 神木回天：消除跨层重复硬编码）
- */
-export declare const DECAY_AMOUNT = 0.02;
+export declare const GOVERNANCE_SOURCES: readonly string[];
 //# sourceMappingURL=governance.d.ts.map

package/dist/memory/governance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"governance.d.ts","sourceRoot":"","sources":["../../src/memory/governance.ts"],"names":[],"mappings":"AAiBA;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAI/C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,aAAa,IAAM,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC"}
+{"version":3,"file":"governance.d.ts","sourceRoot":"","sources":["../../src/memory/governance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAO,CAAC"}

package/dist/memory/governance.js

@@ -1,70 +1,17 @@
 /**
- * 记忆治理共享常量 — LLM 治理源列表 + score 提升量/上限的统一真理源
+ * 记忆治理共享常量 — 治理源列表。
+ * 排序单归语义分：使用轨迹唯一事实源为 accessedAt，无 score 写位/排序/clamp 位。
+ * 纯常量模块（零依赖，仅类型 import），被 agent/managers 多模块消费，符合 agent → memory 单向依赖。
  *
- * 设计原因：memoryInspector / memoryAdvisor / memoryDecayScheduler 三个治理模块
- * 各自维护同一份 `[INSIGHT, PROFILE, WORK_PROJECTION]` 列表，存在 5 处独立维护。
- * 提取到共享模块后，未来调整治理范围只需改 1 处（v2 年轮审判 REPEAT-1 闭环）。
- *
- * 同时收纳 score 提升量/上限常量（recall.ts 召回 boost + memoryInspector 采纳反哺 boost），
- * 消除 2 处重复（v2 年轮审判 REPEAT-2 闭环）。
- *
- * 依赖方向：memory/governance.ts 是纯常量模块（零依赖，仅类型 import），
- * 被 agent/managers/ 多个模块消费，符合 agent → memory 单向依赖原则。
- *
- * 详见 ADR-004（记忆统一模型）：所有 source 都是开放字符串，治理范围由本文件集中维护。
- */
-import { SOURCE_LABELS } from '../memory/types.js';
-/**
- * LLM 治理源列表 — 参与去重 / 冲突检测 / 时效性评估 / 衰减的 source 集合
- *
- * 不含配置型记忆（persona / rule / skill），这些是启动时加载的永驻记忆，
- * 不参与运行时治理。如未来扩展治理范围，仅需修改此数组。
+ * 治理模型：supersede（写时取代）；无衰减——
+ * 摘要是事实记录无"过时"语义，记忆有效性由 superseded 写时取代判定，
+ * 低频记忆经相关性排序自然后移退出召回面，无"沉底/自然遗忘归档"语义。
  */
-export const GOVERNANCE_SOURCES = [
-    SOURCE_LABELS.INSIGHT,
-    SOURCE_LABELS.PROFILE,
-    SOURCE_LABELS.WORK_PROJECTION,
-];
 /**
- * score 提升量 — "越常用越重要"语义统一
- *
- * 消费者：
- *   - recall.ts boostScore：召回时触发（被动）
- *   - memoryInspector.writeBoost：用户主动采纳时触发（主动）
- */
-export const BOOST_INCREMENT = 0.05;
-/**
- * score 上限 — 防止 boost 超过 1.0
- *
- * 消费者：recall.ts / memoryInspector.ts
- */
-export const SCORE_CEILING = 1.0;
-/**
- * score 下限 — 衰减/demote 的底线（MIND2-L3：incrementScore clamp 下限）
- *
- * 消费者：
- *   - recall.ts applyDecayToMemory（衰减下限）
- *   - InMemoryStorage / SqliteStorage incrementScore（clamp 下限）
- */
-export const DECAY_FLOOR = 0.1;
-/**
- * 衰减：未访问天数阈值（天）— 超过此天数才开始衰减
- *
- * 消费者：
- *   - recall.ts applyDecayToMemory（内存衰减判断）
- *   - SqliteStorage.decayScores（SQL 衰减 WHERE 条件）
- *
- * 修改时必须同步两处（v2 神木回天：消除跨层重复硬编码）
- */
-export const DECAY_AGE_DAYS = 7;
-/**
- * 衰减：每过一个周期 score 降低量
- *
- * 消费者：
- *   - recall.ts applyDecayToMemory（内存衰减计算）
- *   - SqliteStorage.decayScores（SQL 衰减 SET 计算）
- *
- * 修改时必须同步两处（v2 神木回天：消除跨层重复硬编码）
+ * 治理源列表：实际写入记忆库的 source 才参与去重 / 冲突治理。
+ * 当前记忆库唯一自动轨 = round-summary（摘要即记忆本体，见 memory-as-summary.md），
+ * 其治理由 superseded 写时取代承担，不入本数组；content 历史残留 source 无生产写入路径。
+ * 空列表时 dedup/冲突检测空转（测试可显式注入治理源）。
  */
-export const DECAY_AMOUNT = 0.02;
+export const GOVERNANCE_SOURCES = [];
 //# sourceMappingURL=governance.js.map

package/dist/memory/governance.js.map

@@ -1 +1 @@
-{"version":3,"file":"governance.js","sourceRoot":"","sources":["../../src/memory/governance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,aAAa,CAAC,OAAO;IACrB,aAAa,CAAC,OAAO;IACrB,aAAa,CAAC,eAAe;CAC9B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC"}
+{"version":3,"file":"governance.js","sourceRoot":"","sources":["../../src/memory/governance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB,EAAE,CAAC"}

package/dist/memory/inMemoryRoundStore.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 内存问答闭环存储实现 — IRoundStore 的纯 JS 内存版
+ *
+ * 设计理念：
+ * - 零依赖零 IO，用于单元测试、临时占位
+ * - 不持久化（进程退出即丢失），仅限测试/开发
+ * - 生产由宿主注入持久化实现（FileRoundStore 或宿主自选后端）
+ */
+import type { Round, RoundStatus, IRoundStore } from '../memory/roundStore.js';
+/**
+ * 内存问答闭环存储
+ *
+ * 核心实现：
+ * - Map 存储（id → Round）
+ * - 引用计数内置于 Round.refCount
+ * - 支持批量获取（getByIds）
+ * - 支持按状态筛选（listByStatus）
+ * - 支持孤立检查（listOrphaned）
+ */
+export declare class InMemoryRoundStore implements IRoundStore {
+    /** Round 存储（id → Round） */
+    private rounds;
+    /**
+     * 存储问答闭环（新增或更新）
+     *
+     * @param round - 问答闭环对象
+     */
+    save(round: Round): void;
+    /**
+     * 按 ID 获取问答闭环
+     *
+     * @param roundId - 全局唯一 Round ID
+     * @returns Round 对象，不存在返回 null
+     */
+    getById(roundId: string): Round | null;
+    /**
+     * 批量获取问答闭环
+     *
+     * 不存在的 ID 会被跳过，不报错
+     *
+     * @param roundIds - Round ID 数组
+     * @returns Round 对象数组（按输入顺序，跳过不存在的）
+     */
+    getByIds(roundIds: string[]): Round[];
+    /**
+     * 列出所有问答闭环
+     *
+     * ⚠️ 生产环境慎用：全量遍历可能性能开销大
+     *
+     * @returns 所有 Round 数组（浅拷贝）
+     */
+    listAll(): Round[];
+    /**
+     * 增加引用计数
+     *
+     * 分叉时调用：新会话引用同一个 Round
+     *
+     * @param roundId - 需要增加引用的 Round ID
+     */
+    incrementRef(roundId: string): void;
+    /**
+     * 减少引用计数
+     *
+     * 删除会话时调用
+     * 引用计数不会降到 0 以下
+     *
+     * @param roundId - 需要减少引用的 Round ID
+     */
+    decrementRef(roundId: string): void;
+    /**
+     * 删除问答闭环（物理删除，不可恢复）
+     *
+     * 前置条件：refCount === 0
+     *
+     * @param roundId - 要删除的 Round ID
+     * @returns 是否删除成功（refCount > 0 时返回 false）
+     */
+    delete(roundId: string): boolean;
+    /**
+     * 按状态列出问答闭环
+     *
+     * @param status - Round 状态筛选
+     * @returns 符合条件的 Round 数组
+     */
+    listByStatus(status: RoundStatus): Round[];
+    /**
+     * 获取孤立的问答闭环列表（refCount === 0）
+     *
+     * 用于 GC 服务批量清理
+     *
+     * @param minAgeMs - 最小存活时间（毫秒），避免清理正在使用的 Round
+     * @returns 孤立 Round 数组
+     */
+    listOrphaned(minAgeMs?: number): Round[];
+    /**
+     * 列出指定日期最近未完成（pending/error）的崩溃残留轮（step 原子落盘）。
+     *
+     * 崩溃发生在 appendAssistant 前时，该轮 refCount=0、未登记会话、orphan 但可能有已落盘
+     * processEvents（step 检查点）。宿主重启后经此口「找到」中断轮，再调收场方法
+     * （MessageHistory.appendInterrupted）**升级为正常 stop turn**（非半成品草稿）。
+     * 只读、不改写、不登记会话；升级完成（complete + refCount>0）前为打捞窗口内中间态，
+     * 超龄仍未升级的中断轮由 GC 回收（默认 24h 存活保护覆盖打捞窗口，不误回收）。
+     *
+     * @param date - YYYY-MM-DD，按 createdAt 前缀匹配（ISO 头 10 位）
+     * @param limit - 最多条数，按 createdAt 降序（最新在前）；缺省不截断
+     * @returns 中断残留 Round 数组（倒序）
+     */
+    listInterruptedRecent(date: string, limit?: number): Round[];
+    /**
+     * 获取存储中的 Round 数量
+     *
+     * 用于监控和测试
+     *
+     * @returns Round 总数
+     */
+    size(): number;
+    /**
+     * 清空存储（测试用）
+     *
+     * ⚠️ 不可逆操作，仅用于测试
+     */
+    clear(): void;
+}
+//# sourceMappingURL=inMemoryRoundStore.d.ts.map

package/dist/memory/inMemoryRoundStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryRoundStore.d.ts","sourceRoot":"","sources":["../../src/memory/inMemoryRoundStore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG9E;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACpD,2BAA2B;IAC3B,OAAO,CAAC,MAAM,CAAiC;IAE/C;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAKxB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAMtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE;IAWrC;;;;;;OAMG;IACH,OAAO,IAAI,KAAK,EAAE;IAIlB;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUnC;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAYnC;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAchC;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,EAAE;IAM1C;;;;;;;OAOG;IACH,YAAY,CAAC,QAAQ,GAAE,MAAU,GAAG,KAAK,EAAE;IAsB3C;;;;;;;;;;;;OAYG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE;IAmB5D;;;;;;OAMG;IACH,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd"}