dsh-prime-memory 0.11.0

package/dist/pipeline/l1.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from '../config.js';
+import type { L1Store } from '../store/l1.js';
+import type { MemoryState } from '../store/state.js';
+import type { ConversationMessage, ExtractMode, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+export interface ExtractionResult {
+    stored: number;
+    skipped: boolean;
+    sceneName: string;
+    newRecords: MemoryRecord[];
+}
+/** 分族 checkpoint 桶(活引用,改动由调用方 save 落盘)。 */
+export type FamilyStates = Record<MemoryFamily, MemoryState>;
+/**
+ * 按字符预算把消息切成多块(保持顺序,单条超预算独占一块,由 callLLM 兜底截断)。
+ * 每条消息按 content 长度 + 64 字符脚手架开销(id/时间戳行)计。
+ */
+export declare function chunkByCharBudget(messages: ConversationMessage[], budgetChars: number): ConversationMessage[][];
+export declare function runExtraction(ctx: Context, cfg: MemoryConfig, store: L1Store, states: FamilyStates, pending: ConversationMessage[], background: ConversationMessage[], logger: MemoryLogger, mode: ExtractMode): Promise<ExtractionResult>;

package/dist/pipeline/l1.js

@@ -0,0 +1,271 @@
+/**
+ * L1 蒸馏:抽取(情境切分 + 记忆提取)→ 去重(冲突检测 + 合并)→ 写入。
+ *
+ * 流程(官方管线语义):抽取 prompt 分块跑(按 llm.maxInputChars 预算,情境链式
+ * 衔接)→ 去重候选按族召回 → 批量冲突检测 prompt → 决策应用:新记录追加进事实源,
+ * 被替换目标只从检索库删除。 族隔离贯穿始终:去重候选只在同族内,合并产物保持
+ * 新记忆的族标签。
+ */
+import { randomBytes } from 'node:crypto';
+import { callLLM, parseJsonLogged, resolveLayerTokens } from '../llm.js';
+import { formatExtractionPrompt, getExtractMemoriesSystemPrompt } from '../prompts/l1-extraction.js';
+import { formatBatchConflictPrompt, getConflictDetectionSystemPrompt } from '../prompts/l1-dedup.js';
+import { familyForType, normPersistence, resolveRecordFamily } from '../types.js';
+/** 解析 ISO/epoch 时间证据,非法或非正值一律 undefined——不猜测。 */
+function parseTimeEvidence(raw) {
+    const t = typeof raw === 'string' ? Date.parse(raw) : typeof raw === 'number' ? raw : Number.NaN;
+    return Number.isFinite(t) && t > 0 ? t : undefined;
+}
+/**
+ * 抽取产出的 metadata → 记录的时间轴。
+ *
+ * `activity_start_time`/`activity_end_time` 是这两列的前身(prompt 已在产出),
+ * 这里把它们提升为结构化字段;`persistence` 由 prompt 产出,缺省即未判定。
+ */
+function temporalOf(meta) {
+    return {
+        validFrom: parseTimeEvidence(meta?.activity_start_time),
+        validTo: parseTimeEvidence(meta?.activity_end_time),
+        persistence: normPersistence(meta?.persistence),
+    };
+}
+/**
+ * 合并(merge/update)时的有效期并集:
+ * 起 = 两侧最早;止 = 任一侧未闭合则仍未闭合(undefined),否则取最晚。
+ * 持续性以新记忆为准(合并产物描述的是当前认知),新记忆未判定时继承旧记录。
+ */
+function mergeTemporal(self, targets) {
+    const froms = [self.validFrom, ...targets.map((r) => r.validFrom)].filter((t) => t !== undefined);
+    const tos = [self.validTo, ...targets.map((r) => r.validTo)];
+    const anyOpen = tos.some((t) => t === undefined);
+    const closed = tos.filter((t) => t !== undefined);
+    return {
+        validFrom: froms.length > 0 ? Math.min(...froms) : undefined,
+        validTo: anyOpen || closed.length === 0 ? undefined : Math.max(...closed),
+        persistence: self.persistence ?? targets.find((r) => r.persistence)?.persistence,
+    };
+}
+function newId(prefix) {
+    return `${prefix}_${Date.now()}_${randomBytes(3).toString('hex')}`;
+}
+/**
+ * 按字符预算把消息切成多块(保持顺序,单条超预算独占一块,由 callLLM 兜底截断)。
+ * 每条消息按 content 长度 + 64 字符脚手架开销(id/时间戳行)计。
+ */
+export function chunkByCharBudget(messages, budgetChars) {
+    if (messages.length === 0)
+        return [];
+    const chunks = [];
+    let cur = [];
+    let curChars = 0;
+    for (const m of messages) {
+        const len = m.content.length + 64;
+        if (cur.length > 0 && curChars + len > budgetChars) {
+            chunks.push(cur);
+            cur = [];
+            curChars = 0;
+        }
+        cur.push(m);
+        curChars += len;
+    }
+    if (cur.length > 0)
+        chunks.push(cur);
+    return chunks;
+}
+export async function runExtraction(ctx, cfg, store, states, pending, background, logger, mode) {
+    if (!cfg.extract.enabled)
+        return { stored: 0, skipped: true, sceneName: chainHead(states, mode), newRecords: [] };
+    // 触发阈值(渐进爬坡 + 按会话切片计数)由 runner 判定(trigger.ts);
+    // 此处不再重复 gate——重建轮 force 与 warmup 早期轮次都会传入小于稳态值的切片。
+    // 纯档强制族 = 档位族;auto 档抽取后的记录族按 type 前缀判定
+    const forcedFamily = mode === 'auto' ? undefined : mode;
+    // 情境链锚点桶:纯档用本族;auto 用最近活跃的族(chainHead 同源)
+    const chainState = mode === 'auto' ? activeState(states) : states[mode];
+    // ── Step 1: 抽取(输入按 llm.maxInputChars 预算分块,情境链式衔接,不丢消息) ──
+    const backgroundMsgs = background.slice(-cfg.extract.backgroundMessages);
+    // 预留:背景消息(≤10 条 ×4000 字)+ prompt 脚手架
+    const perChunk = Math.max(20_000, cfg.llm.maxInputChars - 42_000);
+    const chunks = chunkByCharBudget(pending, perChunk);
+    if (chunks.length > 1) {
+        logger.info(`[memory] L1 输入超预算(${pending.length} 条消息),分 ${chunks.length} 块抽取(每块 ≤${perChunk} 字符)`);
+    }
+    const extracted = [];
+    let lastScene = chainState.lastSceneName;
+    let sceneCount = 0;
+    for (const chunk of chunks) {
+        const userPrompt = formatExtractionPrompt({
+            newMessages: chunk,
+            backgroundMessages: backgroundMsgs,
+            previousSceneName: lastScene || '无',
+            halls: cfg.hall?.enabled,
+        });
+        const raw = await callLLM(ctx, cfg, {
+            system: getExtractMemoriesSystemPrompt(mode),
+            user: userPrompt,
+            maxTokens: resolveLayerTokens(cfg, 'extract'),
+            layer: 'l1-extract',
+            logger,
+        });
+        const scenes = parseJsonLogged(raw, 'L1 抽取', logger);
+        if (!Array.isArray(scenes))
+            throw new Error('L1 抽取输出不是 JSON 数组');
+        for (const scene of scenes) {
+            if (!scene || typeof scene.scene_name !== 'string')
+                continue;
+            lastScene = scene.scene_name;
+            sceneCount++;
+            for (const m of scene.memories ?? []) {
+                if (!m || typeof m.content !== 'string' || !m.content.trim())
+                    continue;
+                extracted.push({
+                    ...m,
+                    record_id: newId('mem'),
+                    scene_name: scene.scene_name,
+                    family: resolveRecordFamily(forcedFamily, m.family, m.type ?? ''),
+                });
+            }
+        }
+    }
+    if (extracted.length === 0) {
+        logger.info(`[memory] L1 抽取完成:无可提取记忆(mode=${mode},${pending.length} 条消息,${sceneCount} 个情境)`);
+        // 成功但零产出:同样推进时间戳/场景,与失败(lastExtractAt 保持 0)区分开
+        markExtracted(states, mode, lastScene);
+        return { stored: 0, skipped: false, sceneName: lastScene, newRecords: [] };
+    }
+    // ── Step 2: 去重(batch 冲突检测;候选只在本族内召回,去重永不跨族) ──
+    const matches = await Promise.all(extracted.map(async (m) => ({
+        newMemory: m,
+        candidates: await store.searchCandidates(m.content, cfg.extract.candidatePool, m.family),
+    })));
+    const dedupPrompt = formatBatchConflictPrompt(matches);
+    const dedupRaw = await callLLM(ctx, cfg, {
+        system: getConflictDetectionSystemPrompt(mode),
+        user: dedupPrompt,
+        maxTokens: resolveLayerTokens(cfg, 'dedup'),
+        layer: 'l1-dedup',
+        logger,
+    });
+    const decisions = parseJsonLogged(dedupRaw, 'L1 去重判定', logger);
+    const byRecord = new Map();
+    for (const d of Array.isArray(decisions) ? decisions : []) {
+        if (d && typeof d.record_id === 'string')
+            byRecord.set(d.record_id, d);
+    }
+    // 去重决策统计:无决策的记录按 skip 处理,聚合成单行日志便于排查
+    const actionCount = {};
+    for (const m of extracted) {
+        const action = byRecord.get(m.record_id)?.action ?? 'skip(未返回)';
+        actionCount[action] = (actionCount[action] ?? 0) + 1;
+    }
+    const candidateTotal = matches.reduce((n, m) => n + m.candidates.length, 0);
+    logger.info(`[memory] L1 去重判定:${extracted.length} 条候选记忆召回 ${candidateTotal} 条已有记录,决策 ${Object.entries(actionCount)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(' ')}`);
+    // ── Step 3: 应用决策(官方语义:新记录追加进事实源,被替换目标只从检索库删除) ──
+    // 只按需取决策涉及的记录(候选 + 目标 id 并集),避免每轮全表扫描
+    const relatedIds = new Set();
+    for (const d of byRecord.values()) {
+        for (const id of d.target_ids ?? [])
+            relatedIds.add(id);
+    }
+    for (const m of matches) {
+        for (const c of m.candidates)
+            relatedIds.add(c.id);
+    }
+    const byId = new Map(store.getByIds([...relatedIds]).map((r) => [r.id, r]));
+    const deletedIds = new Set();
+    const added = [];
+    const now = Date.now();
+    for (const m of extracted) {
+        const decision = byRecord.get(m.record_id);
+        if (!decision || decision.action === 'skip')
+            continue;
+        const action = decision.action;
+        const ts = m.metadata?.activity_start_time ? Date.parse(String(m.metadata.activity_start_time)) : now;
+        if (action === 'store') {
+            added.push({
+                id: m.record_id,
+                content: m.content,
+                type: m.type,
+                priority: Number(m.priority) || 60,
+                scene_name: m.scene_name,
+                timestamps: [Number.isNaN(ts) ? now : ts],
+                createdAt: now,
+                updatedAt: now,
+                version: 0,
+                source_message_ids: m.source_message_ids ?? [],
+                metadata: m.metadata ?? {},
+                family: m.family,
+                ...temporalOf(m.metadata),
+            });
+            continue;
+        }
+        // update / merge:目标记录从检索库删除,合并结果作为新记录追加(版本 +1)
+        // 候选召回按族隔离,合并产物保持新记忆的族标签
+        const targets = (decision.target_ids ?? []).filter((id) => byId.has(id));
+        for (const id of targets)
+            deletedIds.add(id);
+        const targetVersion = targets.reduce((max, id) => Math.max(max, byId.get(id)?.version ?? 0), 0);
+        const mergedTs = (decision.merged_timestamps ?? [])
+            .map((t) => Date.parse(t))
+            .filter((t) => !Number.isNaN(t))
+            .concat([now]);
+        added.push({
+            id: m.record_id,
+            content: decision.merged_content && decision.merged_content.trim()
+                ? decision.merged_content
+                : m.content,
+            type: decision.merged_type || m.type,
+            priority: Number(decision.merged_priority) || Number(m.priority) || 60,
+            scene_name: m.scene_name,
+            timestamps: Array.from(new Set(mergedTs)).sort((a, b) => a - b),
+            createdAt: now,
+            updatedAt: now,
+            version: targetVersion + 1,
+            source_message_ids: m.source_message_ids ?? [],
+            metadata: m.metadata ?? {},
+            family: m.family,
+            // 合并的有效期取并集:起 = 两侧最早;止 = 任一侧未闭合则仍未闭合(undefined)。
+            ...mergeTemporal(temporalOf(m.metadata), targets.map((id) => byId.get(id)).filter((r) => r !== undefined)),
+        });
+    }
+    await store.appendNew(added);
+    if (deletedIds.size > 0)
+        await store.deleteBatch([...deletedIds]);
+    // 状态按记录族分桶推进(阈值计数各自独立)
+    const addedByFamily = { chat: 0, work: 0 };
+    for (const r of added)
+        addedByFamily[r.family ?? familyForType(r.type)]++;
+    for (const f of ['chat', 'work']) {
+        if (addedByFamily[f] === 0)
+            continue;
+        states[f].totalExtracted += addedByFamily[f];
+        states[f].newMemoriesSinceL2 += addedByFamily[f];
+        states[f].memoriesSinceL3 += addedByFamily[f];
+    }
+    markExtracted(states, mode, lastScene);
+    logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条,去重后新增 ${added.length} 条(替换 ${deletedIds.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
+    return { stored: added.length, skipped: false, sceneName: lastScene, newRecords: added };
+}
+/** auto 档取最近活跃的族 checkpoint(情境链/计数锚点)。 */
+function activeState(states) {
+    return states.chat.lastExtractAt >= states.work.lastExtractAt ? states.chat : states.work;
+}
+/** 情境链读取:auto → 最近活跃族;纯档 → 本族。 */
+function chainHead(states, mode) {
+    return (mode === 'auto' ? activeState(states) : states[mode]).lastSceneName;
+}
+/** 抽取成功后推进时间戳/情境链:auto → 两族都推进(链只写锚点桶);纯档 → 本族。 */
+function markExtracted(states, mode, lastScene) {
+    const now = Date.now();
+    if (mode === 'auto') {
+        // 两族的 lastExtractAt 都推进(去重候选各自族内判断"新消息");情境链只维护锚点桶
+        states.chat.lastExtractAt = now;
+        states.work.lastExtractAt = now;
+        activeState(states).lastSceneName = lastScene;
+    }
+    else {
+        states[mode].lastExtractAt = now;
+        states[mode].lastSceneName = lastScene;
+    }
+}

package/dist/pipeline/l2.d.ts

@@ -0,0 +1,13 @@
+/**
+ * L2 场景整合:把新记忆交给 LLM,输出文件操作 JSON,工程侧执行。
+ * (UPDATE 优先 / MERGE / 上限预警 / heat 管理;Bm25 选相关场景全文作上下文。)
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from '../config.js';
+import type { SceneStore } from '../store/scenes.js';
+import type { MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+export interface SceneResult {
+    changed: number;
+    personaRequestedReason?: string;
+}
+export declare function runSceneConsolidation(ctx: Context, cfg: MemoryConfig, scenes: SceneStore, newMemories: MemoryRecord[], logger: MemoryLogger, family: MemoryFamily): Promise<SceneResult>;

package/dist/pipeline/l2.js

@@ -0,0 +1,83 @@
+import { callLLM, parseJsonLogged, resolveLayerTokens } from '../llm.js';
+import { buildScenePrompt, formatSceneSummaries } from '../prompts/scene.js';
+import { Bm25Index } from '../store/bm25.js';
+const REQUEST_RE = /\[PERSONA_UPDATE_REQUEST\]\s*reason:\s*([\s\S]*?)\[\/PERSONA_UPDATE_REQUEST\]/;
+export async function runSceneConsolidation(ctx, cfg, scenes, newMemories, logger, family) {
+    if (!cfg.l2.enabled || newMemories.length === 0) {
+        return { changed: 0 };
+    }
+    const summaries = await scenes.list();
+    // ── 组装 prompt ──
+    const memoriesJson = JSON.stringify(newMemories.map((m) => ({
+        record_id: m.id,
+        content: m.content,
+        type: m.type,
+        priority: m.priority,
+        scene_name: m.scene_name,
+        timestamps: m.timestamps.map((t) => new Date(t).toISOString()),
+    })), null, 2);
+    const sceneSummaries = formatSceneSummaries(summaries);
+    const sceneContents = await pickSceneContents(scenes, summaries, newMemories, cfg.l2.sceneContextLimit);
+    const { systemPrompt, userPrompt } = buildScenePrompt({
+        memoriesJson,
+        sceneSummaries,
+        sceneContents,
+        currentTimestamp: new Date().toISOString(),
+        existingSceneFiles: summaries.map((s) => s.path),
+        maxScenes: cfg.l2.maxScenes,
+        family,
+    });
+    const raw = await callLLM(ctx, cfg, {
+        system: systemPrompt,
+        user: userPrompt,
+        maxTokens: resolveLayerTokens(cfg, 'l2'),
+        layer: 'l2',
+        logger,
+    });
+    // ── 解析:先取 PERSONA_UPDATE_REQUEST 标记,再解析操作数组 ──
+    const reqMatch = REQUEST_RE.exec(raw);
+    const personaRequestedReason = reqMatch?.[1]?.trim() || undefined;
+    const opsRaw = reqMatch ? raw.replace(REQUEST_RE, '') : raw;
+    const ops = parseJsonLogged(opsRaw, 'L2 场景操作', logger);
+    if (!Array.isArray(ops))
+        throw new Error('L2 输出不是操作数组');
+    let changed = 0;
+    for (const op of ops) {
+        if (!op || typeof op.path !== 'string')
+            continue;
+        try {
+            if (op.op === 'write' && typeof op.content === 'string') {
+                await scenes.write(op.path, op.content);
+                changed++;
+                logger.debug?.(`[memory] L2 写入场景 ${op.path} (${op.content.length} 字符)`);
+            }
+            else if (op.op === 'delete') {
+                await scenes.write(op.path, '[DELETED]');
+                changed++;
+                logger.debug?.(`[memory] L2 删除场景 ${op.path}`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[memory] L2 操作失败 ${op.path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    logger.info(`[memory] L2 场景整合完成(family=${family}):${newMemories.length} 条新记忆 → ${changed} 个文件操作(场景总数 ${summaries.length})` +
+        (personaRequestedReason ? `,请求 L3 更新:${personaRequestedReason}` : ''));
+    return { changed, personaRequestedReason };
+}
+/** 选出与本次新记忆最相关的场景全文(供 LLM 参考,避免全量塞入)。 */
+async function pickSceneContents(scenes, summaries, newMemories, limit) {
+    if (summaries.length === 0 || limit <= 0)
+        return '';
+    const index = new Bm25Index();
+    index.rebuild(summaries.map((s) => ({ id: s.path, text: `${s.summary} ${s.path}` })));
+    const query = newMemories.map((m) => m.content).join(' ');
+    const hits = index.search(query, limit);
+    const parts = [];
+    for (const h of hits) {
+        const content = await scenes.read(h.id);
+        if (content)
+            parts.push(`### 文件: ${h.id}\n\`\`\`markdown\n${content}\n\`\`\``);
+    }
+    return parts.join('\n\n');
+}

package/dist/pipeline/l3.d.ts

@@ -0,0 +1,15 @@
+/**
+ * L3 画像蒸馏:把变化场景交给 LLM,直接产出 persona-<family>.md 完整内容。
+ * 触发条件(persona-trigger):L2 主动请求 / 冷启动 / 恢复 / 间隔阈值。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from '../config.js';
+import type { PersonaStore } from '../store/persona.js';
+import type { SceneStore } from '../store/scenes.js';
+import type { MemoryState } from '../store/state.js';
+import type { MemoryFamily, MemoryLogger } from '../types.js';
+export interface PersonaResult {
+    generated: boolean;
+    reason: string;
+}
+export declare function runPersona(ctx: Context, cfg: MemoryConfig, scenes: SceneStore, persona: PersonaStore, state: MemoryState, logger: MemoryLogger, family: MemoryFamily): Promise<PersonaResult>;

package/dist/pipeline/l3.js

@@ -0,0 +1,78 @@
+import { callLLM, resolveLayerTokens } from '../llm.js';
+import { buildPersonaPrompt } from '../prompts/persona.js';
+export async function runPersona(ctx, cfg, scenes, persona, state, logger, family) {
+    if (!cfg.l3.enabled)
+        return { generated: false, reason: 'l3 disabled' };
+    // ── 触发判定 ──
+    const existingPersona = await persona.read();
+    let reason;
+    if (state.personaRequestedReason) {
+        reason = `主动请求: ${state.personaRequestedReason}`;
+    }
+    else if (!state.hasPersona || !existingPersona) {
+        reason = '冷启动/恢复:首次生成或画像缺失';
+    }
+    else if (state.memoriesSinceL3 >= cfg.l3.interval) {
+        reason = `达到阈值: ${state.memoriesSinceL3} >= ${cfg.l3.interval}`;
+    }
+    else {
+        logger.debug?.(`[memory] L3 未触发(自上次蒸馏以来 ${state.memoriesSinceL3}/${cfg.l3.interval} 条新记忆)`);
+        return { generated: false, reason: 'no trigger' };
+    }
+    // ── 收集变化场景(自上次蒸馏以来 updated 变化 / 首次则全部) ──
+    const all = await scenes.list();
+    const changed = state.hasPersona
+        ? all.filter((s) => {
+            const t = Date.parse(s.updated);
+            return !Number.isNaN(t) && t > state.lastL3At;
+        })
+        : all;
+    if (changed.length === 0 && state.hasPersona) {
+        logger.debug?.('[memory] L3 触发但无变化场景,跳过');
+        return { generated: false, reason: 'no changed scenes' };
+    }
+    const changedContents = [];
+    for (const s of changed) {
+        const content = await scenes.read(s.path);
+        if (content)
+            changedContents.push(`### 场景: ${s.path}\n\`\`\`markdown\n${content}\n\`\`\``);
+    }
+    const { systemPrompt, userPrompt } = buildPersonaPrompt({
+        mode: existingPersona ? 'incremental' : 'first',
+        family,
+        currentTime: new Date().toISOString(),
+        totalProcessed: state.totalExtracted,
+        sceneCount: all.length,
+        changedSceneCount: changed.length,
+        changedScenesContent: changedContents.join('\n\n'),
+        existingPersona,
+        triggerInfo: reason,
+    });
+    const raw = await callLLM(ctx, cfg, {
+        system: systemPrompt,
+        user: userPrompt,
+        maxTokens: resolveLayerTokens(cfg, 'l3'),
+        layer: 'l3',
+        logger,
+    });
+    const body = unwrapFence(raw);
+    if (!body) {
+        logger.error(`[memory] L3 输出为空,原始输出前 400 字符: ${raw.slice(0, 400)}`);
+        throw new Error('L3 输出为空');
+    }
+    await persona.write(body);
+    state.hasPersona = true;
+    state.lastL3At = Date.now();
+    state.memoriesSinceL3 = 0;
+    state.personaRequestedReason = undefined;
+    logger.info(`[memory] L3 画像蒸馏完成(family=${family},${reason}):${body.length} 字符,场景 ${changed.length}/${all.length} 个`);
+    return { generated: true, reason };
+}
+/** 剥掉可能的 ```markdown 围栏。 */
+function unwrapFence(text) {
+    let s = text.trim();
+    if (s.startsWith('```')) {
+        s = s.replace(/^```[a-zA-Z]*\n?/, '').replace(/```$/, '').trim();
+    }
+    return s;
+}

package/dist/pipeline/rebuild.d.ts

@@ -0,0 +1,61 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type MemoryConfig } from '../config.js';
+import type { L1Store } from '../store/l1.js';
+import type { PersonaStore } from '../store/persona.js';
+import type { SceneStore } from '../store/scenes.js';
+import type { StateStore } from '../store/state.js';
+import type { MemoryDb } from '../store/sqlite.js';
+import type { LiveSettingsHandle } from '../settings.js';
+import type { ConversationMessage, L0MessageRecord, MemoryFamily, MemoryLogger } from '../types.js';
+import { type MemoryRunner } from './runner.js';
+/** 重建所需的存储子集(l0 不需要——快照直接走 db)。 */
+export interface RebuildStores {
+    l1: L1Store;
+    scenes: Record<MemoryFamily, SceneStore>;
+    persona: Record<MemoryFamily, PersonaStore>;
+    state: StateStore;
+}
+import type { RebuildStatus } from '../contract.js';
+export type { RebuildPhase, RebuildStatus } from '../contract.js';
+export interface RebuildChunk {
+    sessionId: string;
+    messages: ConversationMessage[];
+}
+export declare function groupL0Sessions(records: L0MessageRecord[]): RebuildChunk[];
+/** 抽取调用数下界估算(与 l1.ts 的 perChunk 同式;会话数与字符预算取大)。 */
+export declare function estimateCalls(sessions: number, messages: number, chars: number, maxInputChars: number): number;
+export declare class RebuildController {
+    private readonly ctx;
+    private readonly cfg;
+    private readonly stores;
+    private readonly db;
+    private readonly runner;
+    private readonly logger;
+    private readonly live;
+    private status;
+    private chunks;
+    private cancelRequested;
+    /** 快照时刻(收尾时按它区分重建产物与重建后新对话的记录)。 */
+    private rebuildStartMs;
+    constructor(ctx: Context, cfg: MemoryConfig, stores: RebuildStores, db: MemoryDb, runner: Pick<MemoryRunner, 'enqueueRebuildTask' | 'runRebuildTurn' | 'states'>, logger: MemoryLogger, live: LiveSettingsHandle);
+    /** 状态快照(idle 时附带实时 L0 预估,供确认弹窗显示成本)。 */
+    getStatus(): RebuildStatus;
+    /** 内存中尚未处理的会话快照块数(收尾后应为 0——快照即弃,诊断/冒烟用)。 */
+    get chunkCount(): number;
+    /** 启动重建(校验后入队准备任务;真正的清库/归档在管线队列里串行执行,避开并发竞态)。 */
+    start(): RebuildStatus;
+    /** 请求取消:当前块完成后停止,已重建部分保留并照常收尾 L2/L3。 */
+    requestCancel(): RebuildStatus;
+    private prepare;
+    /** 分块链:一次只挂一个重建块,跑完再挂下一块——正常轮次可随时插队。 */
+    private scheduleChunk;
+    private finalize;
+    /**
+     * 收集重建窗口内某族的记录:重建产物全部是新插入(updated==created),
+     * 按 updated_time 倒序翻页、越过 rebuildStartMs 即停。
+     */
+    private collectRebuildRecords;
+    private finish;
+    /** 归档旧派生层:records/ scenes/ persona-*.md 改名 .bak.<ts>。不存在则跳过。 */
+    private archiveDerived;
+}