@co-engram/core 0.1.0

package/dist/dreaming/rem.js

@@ -0,0 +1,228 @@
+/**
+ * REM Dreaming（跨情境抽象 + 模式发现）
+ *
+ * 神经科学依据：REM 睡眠期间，海马与皮层协同重放，发现跨情境的共同模式。
+ *
+ * 实现（spec §5.2）：
+ *   1. 取所有 active engram
+ *   2. 相似度聚类（基于 TokenJaccardSimilarityEngine）
+ *   3. 对每个 ≥ minClusterSize 的 cluster 调用 abstractionProvider 抽象
+ *   4. 生成 ConsolidationProposal（title/content/sourceIds/confidence）
+ *   5. confidence ≥ autoAdoptionThreshold → 自动创建 pattern engram + 连接 derives_from
+ *
+ * Core 层提供 PatternAbstractionProvider 接口，宿主可注入真正的 LLM 抽象器；
+ * 默认实现 LocalHeuristicPatternAbstraction 基于 token 频率提取共同 tokens。
+ *
+ * @module @co-engram/core/dreaming
+ */
+import { randomUUID } from "node:crypto";
+import { tokenizeForDedup, TokenJaccardSimilarityEngine, } from "../dedup/similar.js";
+// ============================================================
+// 默认启发式抽象
+// ============================================================
+/**
+ * 启发式模式抽象（无 LLM）
+ *
+ * 算法：
+ *   1. 合并 cluster 内所有 engram 的 tokens
+ *   2. 按 token 频率倒序，取 top N 作为"共同关键词"
+ *   3. title = "Pattern: {top1} {top2} {top3}"
+ *   4. content = 共同关键词列表 + source 列表
+ *   5. confidence = (top1 频率 / cluster size) × 加权
+ *
+ * 这是 P2 启发式；生产环境应该用 LLM 做语义抽象。
+ */
+export class LocalHeuristicPatternAbstraction {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    abstract(input) {
+        const topTokens = this.options.topTokens ?? 5;
+        const minConfidence = this.options.minConfidence ?? 0.3;
+        if (input.engrams.length === 0) {
+            return {
+                title: "Pattern: <empty>",
+                content: "",
+                summary: "空 cluster",
+                confidence: 0,
+                reason: "empty cluster",
+            };
+        }
+        // 合并所有 tokens 并统计频率
+        const tokenFreq = new Map();
+        for (const e of input.engrams) {
+            const tokens = tokenizeForDedup(`${e.title} ${e.summary} ${e.content}`);
+            for (const t of tokens) {
+                tokenFreq.set(t, (tokenFreq.get(t) ?? 0) + 1);
+            }
+        }
+        // 取出现频率 ≥ 一半 engram 的 token 作为"共同关键词"
+        const threshold = Math.ceil(input.engrams.length / 2);
+        const commonTokens = [...tokenFreq.entries()]
+            .filter(([, count]) => count >= threshold)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, topTokens)
+            .map(([t]) => t);
+        if (commonTokens.length === 0) {
+            return {
+                title: `Pattern: ${input.engrams[0].domainTags[0] ?? "unknown"}`,
+                content: "共同 tokens 不足，无法抽象出明确模式",
+                summary: "低相似度 cluster",
+                confidence: minConfidence,
+                reason: "no common tokens above threshold",
+            };
+        }
+        const title = `Pattern: ${commonTokens.slice(0, 3).join(" / ")}`;
+        const content = [
+            `# ${title}`,
+            "",
+            `**抽象来源**：${input.engrams.length} 个 engram`,
+            "",
+            "**共同关键词**：",
+            ...commonTokens.map((t) => `- ${t}`),
+            "",
+            "**来源 engram**：",
+            ...input.engrams.map((e) => `- [${e.id}] ${e.title}`),
+        ].join("\n");
+        // confidence = 共同 token 数 / 期望数（归一化到 [0,1]）
+        const confidence = Math.min(1, commonTokens.length / topTokens);
+        const reason = `${commonTokens.length} common tokens across ${input.engrams.length} engrams`;
+        return {
+            title,
+            content,
+            summary: `${commonTokens.length} 个共同关键词`,
+            confidence,
+            reason,
+        };
+    }
+}
+/**
+ * 简单贪心聚类：按 id 字典序遍历，每个 engram 找未聚类的相似邻居组成 cluster
+ */
+export function clusterSimilarEngrams(repo, options = {}) {
+    const similarityThreshold = options.similarityThreshold ?? 0.4;
+    const maxClusterSize = options.maxClusterSize ?? 10;
+    const engine = new TokenJaccardSimilarityEngine(repo);
+    const entries = [...repo.listEngrams()].sort((a, b) => a.id < b.id ? -1 : 1);
+    const clustered = new Set();
+    const clusters = [];
+    for (const entry of entries) {
+        if (clustered.has(entry.id))
+            continue;
+        const engram = repo.readEngram(entry.id);
+        if (engram.status !== "active")
+            continue;
+        const candidates = engine.findCandidatesSync(`${engram.title} ${engram.summary} ${engram.content}`, { topK: maxClusterSize, minSimilarity: similarityThreshold });
+        const memberIds = [entry.id];
+        clustered.add(entry.id);
+        for (const c of candidates) {
+            if (c.id === entry.id)
+                continue;
+            if (clustered.has(c.id))
+                continue;
+            const candidateEngram = repo.readEngram(c.id);
+            if (candidateEngram.status !== "active")
+                continue;
+            memberIds.push(c.id);
+            clustered.add(c.id);
+            if (memberIds.length >= maxClusterSize)
+                break;
+        }
+        if (memberIds.length > 1) {
+            clusters.push({ representativeId: entry.id, memberIds });
+        }
+    }
+    return clusters;
+}
+/**
+ * 执行 REM Dreaming
+ *
+ * 1. 聚类所有 active engram
+ * 2. 对每个 ≥ minClusterSize 的 cluster 生成抽象提案
+ * 3. confidence ≥ autoAdoptionThreshold → 自动创建 pattern engram + derives_from synapse
+ *
+ * 注意：core 层不绑定 LLM；abstractionProvider 由宿主注入。
+ */
+export async function runRemDreaming(repo, options = {}) {
+    const provider = options.abstractionProvider ?? new LocalHeuristicPatternAbstraction();
+    const minClusterSize = options.minClusterSize ?? 3;
+    const autoAdoptionThreshold = options.autoAdoptionThreshold ?? 0.85;
+    const createdBy = options.createdBy ?? "dreaming-rem";
+    const dryRun = options.dryRun ?? false;
+    const clusters = clusterSimilarEngrams(repo, options.clustering ?? {});
+    const proposals = [];
+    const adopted = [];
+    const skipped = [];
+    for (const cluster of clusters) {
+        if (cluster.memberIds.length < minClusterSize)
+            continue;
+        const engrams = cluster.memberIds.map((id) => {
+            const e = repo.readEngram(id);
+            return {
+                id: e.id,
+                title: e.title,
+                summary: e.summary,
+                content: e.content,
+                domainTags: [...e.domainTags],
+            };
+        });
+        const output = await provider.abstract({ engrams });
+        const proposal = {
+            title: output.title,
+            content: output.content,
+            summary: output.summary,
+            confidence: output.confidence,
+            reason: output.reason,
+            sourceIds: cluster.memberIds,
+            clusterRepresentativeId: cluster.representativeId,
+        };
+        proposals.push(proposal);
+        if (output.confidence >= autoAdoptionThreshold && !dryRun) {
+            // 自动采纳：创建 pattern engram + derives_from synapse
+            const patternEngram = repo.createEngram({
+                title: proposal.title,
+                content: proposal.content,
+                summary: proposal.summary,
+                kind: "pattern",
+                domainTags: [...new Set(engrams.flatMap((e) => e.domainTags))],
+                importance: 0.7,
+                confidence: output.confidence,
+                sourceType: "inferred",
+                createdBy,
+            });
+            // 连接 derives_from 每个 source
+            const timestamp = patternEngram.createdAt;
+            for (const sourceId of proposal.sourceIds) {
+                const synapse = {
+                    id: randomUUID(),
+                    from: patternEngram.id,
+                    to: sourceId,
+                    kind: "derives_from",
+                    weight: 0.8,
+                    direction: "directional",
+                    evidence: [],
+                    createdBy,
+                    createdAt: timestamp,
+                    updatedAt: timestamp,
+                    retrievalWeight: 0.8,
+                };
+                repo.addOutgoingSynapse(patternEngram.id, synapse);
+            }
+            adopted.push({ patternEngramId: patternEngram.id, proposal });
+        }
+        else if (output.confidence < autoAdoptionThreshold) {
+            skipped.push({
+                proposal,
+                reason: `confidence ${output.confidence.toFixed(2)} < threshold ${autoAdoptionThreshold}`,
+            });
+        }
+    }
+    return {
+        clustersScanned: clusters.length,
+        proposals,
+        adopted,
+        skipped,
+    };
+}
+//# sourceMappingURL=rem.js.map

package/dist/dreaming/rem.js.map

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

package/dist/dreaming/scheduler.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Dreaming 调度器（host-agnostic）
+ *
+ * 提供简单的"按间隔触发"抽象，不绑定 cron 库。
+ * 宿主（OpenClaw / Claude Code MCP）负责：
+ *   - 实际的时间触发（cron / setInterval / 外部事件）
+ *   - 低负载时段判断（spec 2.5.6）
+ *   - CLI 命令（spec 2.5.5）
+ *
+ * Core 只提供：
+ *   - 注册 light/deep 任务
+ *   - 立即触发（trigger）
+ *   - 启停定时调度（基于 setInterval）
+ *
+ * @module @co-engram/core/dreaming
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import { type LightDreamingOptions, type LightDreamingResult } from "./light.js";
+import { type DeepDreamingOptions, type DeepDreamingResult } from "./deep.js";
+import { type RemDreamingOptions, type RemDreamingResult } from "./rem.js";
+export type DreamingStage = "light" | "deep" | "rem";
+export interface DreamingScheduleConfig {
+    /** Light Dreaming 间隔（毫秒）。默认 1 小时。 */
+    readonly lightIntervalMs?: number;
+    /** Deep Dreaming 间隔（毫秒）。默认 24 小时。 */
+    readonly deepIntervalMs?: number;
+    /** Rem Dreaming 间隔（毫秒）。默认 7 天。P4 新增。 */
+    readonly remIntervalMs?: number;
+    /** Light Dreaming 选项 */
+    readonly lightOptions?: LightDreamingOptions;
+    /** Deep Dreaming 选项 */
+    readonly deepOptions?: DeepDreamingOptions;
+    /** Rem Dreaming 选项。P4 新增。 */
+    readonly remOptions?: RemDreamingOptions;
+}
+export interface DreamingRunRecord {
+    readonly stage: DreamingStage;
+    readonly at: string;
+    readonly result: LightDreamingResult | DeepDreamingResult | RemDreamingResult;
+}
+export type DreamingRunHandler = (record: DreamingRunRecord) => void;
+/**
+ * Dreaming 调度器
+ *
+ * 使用：
+ *   const scheduler = createDreamingScheduler(repo, {
+ *     lightIntervalMs: 60_000,
+ *     deepIntervalMs: 24 * 60 * 60_000,
+ *   })
+ *   scheduler.onRun((record) => log(record))
+ *   scheduler.start()
+ *   // ... 应用运行期间自动触发
+ *   scheduler.stop()
+ *
+ * 或者立即手动触发：
+ *   scheduler.trigger('light')
+ *   scheduler.trigger('deep')
+ */
+export interface DreamingScheduler {
+    /** 注册运行回调（可多次调用添加多个 handler） */
+    onRun(handler: DreamingRunHandler): void;
+    /** 启动定时调度 */
+    start(): void;
+    /** 停止定时调度 */
+    stop(): void;
+    /** 立即触发指定阶段 */
+    trigger(stage: DreamingStage): DreamingRunRecord;
+    /** 是否正在运行 */
+    isRunning(): boolean;
+}
+/**
+ * 创建 Dreaming 调度器
+ */
+export declare function createDreamingScheduler(repo: EngramRepository, config?: DreamingScheduleConfig): DreamingScheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/dreaming/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/dreaming/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,sBAAsB;IACrC,qCAAqC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,qCAAqC;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wCAAwC;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,uBAAuB;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;CAC/E;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,aAAa;IACb,KAAK,IAAI,IAAI,CAAC;IACd,aAAa;IACb,IAAI,IAAI,IAAI,CAAC;IACb,eAAe;IACf,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,CAAC;IACjD,aAAa;IACb,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,EACtB,MAAM,GAAE,sBAA2B,GAClC,iBAAiB,CAkHnB"}

package/dist/dreaming/scheduler.js

@@ -0,0 +1,138 @@
+/**
+ * Dreaming 调度器（host-agnostic）
+ *
+ * 提供简单的"按间隔触发"抽象，不绑定 cron 库。
+ * 宿主（OpenClaw / Claude Code MCP）负责：
+ *   - 实际的时间触发（cron / setInterval / 外部事件）
+ *   - 低负载时段判断（spec 2.5.6）
+ *   - CLI 命令（spec 2.5.5）
+ *
+ * Core 只提供：
+ *   - 注册 light/deep 任务
+ *   - 立即触发（trigger）
+ *   - 启停定时调度（基于 setInterval）
+ *
+ * @module @co-engram/core/dreaming
+ */
+import { runLightDreaming, } from "./light.js";
+import { runDeepDreaming, } from "./deep.js";
+import { runRemDreaming, } from "./rem.js";
+/**
+ * 创建 Dreaming 调度器
+ */
+export function createDreamingScheduler(repo, config = {}) {
+    const lightIntervalMs = config.lightIntervalMs ?? 60 * 60 * 1000;
+    const deepIntervalMs = config.deepIntervalMs ?? 24 * 60 * 60 * 1000;
+    const remIntervalMs = config.remIntervalMs ?? 7 * 24 * 60 * 60 * 1000;
+    const handlers = [];
+    let lightTimer = null;
+    let deepTimer = null;
+    let remTimer = null;
+    let running = false;
+    const emit = (record) => {
+        for (const h of handlers) {
+            try {
+                h(record);
+            }
+            catch {
+                // handler 异常不影响调度（仅记录）
+            }
+        }
+    };
+    const runStage = async (stage) => {
+        const at = new Date().toISOString();
+        if (stage === "light") {
+            const result = runLightDreaming(repo, config.lightOptions ?? {});
+            return { stage, at, result };
+        }
+        if (stage === "deep") {
+            const result = runDeepDreaming(repo, config.deepOptions ?? {});
+            return { stage, at, result };
+        }
+        // rem
+        const result = await runRemDreaming(repo, config.remOptions ?? {});
+        return { stage, at, result };
+    };
+    return {
+        onRun(handler) {
+            handlers.push(handler);
+        },
+        start() {
+            if (running)
+                return;
+            running = true;
+            lightTimer = setInterval(() => {
+                runStage("light")
+                    .then(emit)
+                    .catch(() => { });
+            }, lightIntervalMs);
+            deepTimer = setInterval(() => {
+                runStage("deep")
+                    .then(emit)
+                    .catch(() => { });
+            }, deepIntervalMs);
+            remTimer = setInterval(() => {
+                runStage("rem")
+                    .then(emit)
+                    .catch(() => { });
+            }, remIntervalMs);
+            // unref：定时器不阻止 Node 进程退出（宿主决定生命周期）
+            lightTimer.unref?.();
+            deepTimer.unref?.();
+            remTimer.unref?.();
+        },
+        stop() {
+            if (!running)
+                return;
+            running = false;
+            if (lightTimer) {
+                clearInterval(lightTimer);
+                lightTimer = null;
+            }
+            if (deepTimer) {
+                clearInterval(deepTimer);
+                deepTimer = null;
+            }
+            if (remTimer) {
+                clearInterval(remTimer);
+                remTimer = null;
+            }
+        },
+        trigger(stage) {
+            const at = new Date().toISOString();
+            if (stage === "light") {
+                const result = runLightDreaming(repo, config.lightOptions ?? {});
+                const record = { stage, at, result };
+                emit(record);
+                return record;
+            }
+            if (stage === "deep") {
+                const result = runDeepDreaming(repo, config.deepOptions ?? {});
+                const record = { stage, at, result };
+                emit(record);
+                return record;
+            }
+            // rem 是 async,trigger 同步签名无法等待。
+            // 返回 placeholder record,真实 result 通过 onRun handler 拿到。
+            const placeholder = {
+                clustersScanned: 0,
+                proposals: [],
+                adopted: [],
+                skipped: [],
+            };
+            const record = { stage, at, result: placeholder };
+            runRemDreaming(repo, config.remOptions ?? {})
+                .then((realResult) => {
+                emit({ stage, at, result: realResult });
+            })
+                .catch(() => {
+                // 失败不阻塞
+            });
+            return record;
+        },
+        isRunning() {
+            return running;
+        },
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/dreaming/scheduler.js.map

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

package/dist/dreaming/trash.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 记忆回收站（Trash Sweep）
+ *
+ * 神经科学类比：遗忘不等于物理销毁——已被"遗忘"的突触在一段时间内仍可被找回。
+ * 此模块把"已 forgotten 超过 N 天"的 engram 从主索引物理移动到 `.trash/YYYY-MM/`，
+ * 既给了恢复窗口,又降低了 FTS / 图遍历对陈旧数据的扫描成本。
+ *
+ * 设计约束：
+ *   - 文件系统操作：rename / mkdir。优先 git mv（若仓库为 git 仓库）,否则退化为 fs.rename。
+ *   - 不动 synapse 引用：允许 dangling（其他 engram 仍可能指向被回收的 id）。
+ *     这是有意的：未来若 restore,引用自动恢复有效。
+ *   - purge（物理删除）独立阶段,默认 365 天后才删,且需要显式开启。
+ *   - engram 是单文件 (.md),移动一个文件即可;同时更新 engram-index.json
+ *     以保证主索引不再列出已回收的条目。
+ *
+ * 时间戳策略：
+ *   使用 engram 文件的 mtime 作为"最后被触碰时刻"的近似。
+ *   原因：forgotten 状态切换走 `updateLifecycle`,不写 updatedAt；mtime 是最接近真相的信号。
+ *   已知缺陷：任何对文件的写入都会刷新 mtime。对 forgotten engram 来说,这种写入很少发生,
+ *   所以近似在 90%+ 场景下是准确的。后续如需精确,可加 `forgottenAt` 字段。
+ *
+ * @module @co-engram/core/dreaming
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import type { AuditLog } from "../observability/audit-log.js";
+/** Trash 配置 */
+export interface TrashOptions {
+    /** 当前时间（测试用）,默认 new Date() */
+    readonly nowIso?: string;
+    /** forgotten 后多少天才进入回收站（默认 30 天） */
+    readonly afterDays?: number;
+    /** 回收站中多少天后物理删除（默认 365 天）;0 或负数表示永不删除 */
+    readonly purgeAfterDays?: number;
+    /** 只读模式：只计算不落盘 */
+    readonly dryRun?: boolean;
+    /** 可选审计日志：sweep/restore/purge 时自动记录 */
+    readonly auditLog?: AuditLog;
+}
+/** 单次 sweep 结果 */
+export interface TrashSweepResult {
+    /** 扫描的 forgotten engram 数 */
+    readonly scanned: number;
+    /** 已移入回收站的 id 列表 */
+    readonly trashed: string[];
+    /** 已从回收站物理删除的 id 列表（purge 阶段） */
+    readonly purged: string[];
+    /** 跳过的 id → 原因 */
+    readonly skipped: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+/** Trash 根目录名（相对仓库根） */
+export declare const TRASH_DIR_NAME = ".trash";
+/** 默认进入回收站阈值：forgotten 后 30 天 */
+export declare const DEFAULT_TRASH_AFTER_DAYS = 30;
+/** 默认物理删除阈值：进入回收站后 365 天 */
+export declare const DEFAULT_TRASH_PURGE_AFTER_DAYS = 365;
+/**
+ * 计算某个月份分区名（YYYY-MM）
+ *
+ * 使用 UTC 以避免本地时区在跨日边界的不一致。
+ */
+export declare function formatTrashPartition(date: Date): string;
+/**
+ * 计算 engram 在 trash 分区下的相对路径
+ *
+ * 输入：原 engram 相对路径（如 "testing/adb/foo.md"）,分区名 "2026-06"
+ * 输出：".trash/2026-06/testing/adb/foo.md"
+ *
+ * 注：trash 下不再分 content/meta/synapses 子目录（单文件布局）。
+ */
+export declare function deriveTrashFilePath(relativePath: string, partition: string): string;
+/** 旧版三路径 API（兼容调用方/测试）：派生 trash 下的镜像路径 */
+export declare function deriveTrashFilePaths(relativePath: string, partition: string): {
+    content: string;
+    meta: string;
+    synapses: string;
+};
+/**
+ * 执行 trash sweep
+ *
+ * 流程：
+ *   1. 扫描所有 engram,过滤出 status=forgotten
+ *   2. 对每个 forgotten engram,读文件 mtime,判断是否 ≥ afterDays
+ *   3. 满足条件 → 计算分区（按当前时间）→ 移动单文件到 .trash/<partition>/<relativePath>
+ *   4. （可选）扫描 .trash/ 中已存在且 ≥ purgeAfterDays 的分区,物理删除
+ *
+ * 安全保证：
+ *   - 目标路径已存在时跳过（避免覆盖）
+ *   - 移动失败时记录到 skipped,不抛
+ */
+export declare function sweepToTrash(repo: EngramRepository, options?: TrashOptions): TrashSweepResult;
+/**
+ * 列出 trash 中的所有 engram（跨分区）
+ *
+ * 用于 restore 工具的"查询接口"和排查。
+ */
+export interface TrashedEngram {
+    /** 原 engram id */
+    readonly id: string;
+    /** 所在分区（YYYY-MM） */
+    readonly partition: string;
+    /** 在 trash 中的绝对路径（.md 文件） */
+    readonly contentPath: string;
+    /** 进入 trash 的时间（分区目录 mtime） */
+    readonly trashedAt: string;
+}
+export declare function listTrashed(repo: EngramRepository): TrashedEngram[];
+/**
+ * 在 trash 中查找指定 id 的 engram
+ */
+export declare function findTrashed(repo: EngramRepository, engramId: string): TrashedEngram | null;
+/**
+ * 一键清空回收站(永久删除)
+ *
+ * 与 sweepToTrash 内部的 purgeExpiredTrash 不同,本函数:
+ *   - 不按时间过滤,而是清掉所有(或指定 partition)的 trashed engram
+ *   - 由用户在 UI 显式触发,审计日志记 actor='user'(非 system)
+ *   - 同步审计:每条删除写一条 action='purge' 审计
+ *
+ * 安全策略:
+ *   - dryRun=true 时只计算 purged id,不真正删除
+ *   - partition 未传 → 清所有分区
+ *   - partition 传入但不存在 → 返回空(不抛)
+ *
+ * @returns purged id 列表(按字典序)
+ */
+export declare function purgeAllTrash(repo: EngramRepository, options?: {
+    /** 仅清空指定分区(YYYY-MM);不传则清所有分区 */
+    readonly partition?: string;
+    /** 只读模式:只返回会删的 id,不真正删除 */
+    readonly dryRun?: boolean;
+    /** 可选审计日志 */
+    readonly auditLog?: AuditLog;
+    /** 审计行为者(默认 'user',因为是用户在 UI 触发) */
+    readonly actor?: "user" | "llm" | "system";
+}): {
+    purged: readonly string[];
+    partitionsRemoved: readonly string[];
+};
+/**
+ * 读取 trash 中某个 engram 的完整内容(供 UI 预览)
+ *
+ * 返回 frontmatter + body,以及 partition / trashedAt 元信息。
+ * 不存在时返回 null(由调用方决定 404)。
+ */
+export declare function readTrashed(repo: EngramRepository, engramId: string): {
+    readonly id: string;
+    readonly partition: string;
+    readonly trashedAt: string;
+    readonly frontmatter: Record<string, unknown>;
+    readonly content: string;
+    readonly contentPath: string;
+} | null;
+/**
+ * 从 trash 恢复 engram：物理移回原位 + status 切回 active
+ *
+ * 流程：
+ *   1. 在 .trash/ 中查找 id（可能跨多个分区）
+ *   2. 把单文件移回 <root>/<originalRelativePath>
+ *   3. repo.updateLifecycle(id, 'active', 'fresh') 重置检索状态
+ *
+ * 不抛：找不到返回 { ok: false, reason }。
+ */
+export declare function restoreFromTrash(repo: EngramRepository, engramId: string, options?: {
+    readonly auditLog?: AuditLog;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+//# sourceMappingURL=trash.d.ts.map

package/dist/dreaming/trash.d.ts.map

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