@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/memory/phase1.js

@@ -0,0 +1,292 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { sanitizeInternalReminderBlocks } from "../agent/internal-reminder-sanitizer.js";
+import { tryCheckpointMessages } from "../context/checkpoint.js";
+import { isCompactionSummaryMessage } from "../context/compact.js";
+import { MemoryDatabase } from "./db.js";
+import { getBubbleHome } from "./paths.js";
+import { buildStageOneMessages, parseJsonObject } from "./prompts.js";
+import { classifyMemorySession } from "./session-policy.js";
+import { clearGeneratedMemoryOutputs } from "./storage.js";
+import { redactSecrets } from "./store.js";
+const DEFAULT_MIN_ENTRIES = 4;
+const DEFAULT_LIMIT = 24;
+const MAX_TRANSCRIPT_CHARS = 70_000;
+const MAX_CONTENT_CHARS = 3_000;
+// Bump when the extraction input/selection contract changes, even if the archive does not.
+const EXTRACTOR_VERSION = "checkpoint-segments-v1";
+export async function runMemoryPhase1(options) {
+    const result = { scanned: 0, claimed: 0, succeeded: 0, empty: 0, failed: 0, skipped: 0, errors: [] };
+    if (!options.model) {
+        result.skipped++;
+        result.errors.push("no active model");
+        return result;
+    }
+    const db = new MemoryDatabase(options.cwd);
+    try {
+        const sessions = listEligibleSessionFiles(options.limit ?? DEFAULT_LIMIT);
+        result.scanned = sessions.length;
+        for (const sessionFile of sessions) {
+            const source = classifyMemorySession(sessionFile);
+            if (source.kind !== "native") {
+                if (db.getStage1Output(sessionFile)) {
+                    // Clear before deleting the provenance row so interruption cannot
+                    // leave an unsafe generated artifact that looks source-less later.
+                    clearGeneratedMemoryOutputs(options.cwd);
+                    db.deleteStage1Output(sessionFile);
+                }
+                result.skipped++;
+                continue;
+            }
+            if (db.getThreadMemoryMode(sessionFile) === "disabled") {
+                result.skipped++;
+                continue;
+            }
+            const session = source.session;
+            const sessionCwd = session.getMetadata().cwd ?? options.cwd;
+            const entries = session.getEntries();
+            const entryCount = entries.length;
+            if (countMeaningfulEntries(entries) < (options.minEntries ?? DEFAULT_MIN_ENTRIES)) {
+                result.skipped++;
+                continue;
+            }
+            const sourceUpdatedAt = statSync(sessionFile).mtime.toISOString();
+            const existing = db.getStage1Output(sessionFile);
+            if (existing && existing.extractorVersion === EXTRACTOR_VERSION
+                && existing.entryCount === entryCount && existing.sourceUpdatedAt === sourceUpdatedAt) {
+                result.skipped++;
+                continue;
+            }
+            const claim = db.claimPhase1Job(sessionFile, randomUUID(), 3600);
+            if (!claim.claimed) {
+                result.skipped++;
+                continue;
+            }
+            result.claimed++;
+            try {
+                const transcript = serializeSessionEntries(entries);
+                const raw = await options.complete(buildStageOneMessages({
+                    cwd: sessionCwd,
+                    sessionFile,
+                    transcript,
+                }), {
+                    model: options.model,
+                    temperature: 0,
+                    thinkingLevel: "off",
+                });
+                const parsed = parseJsonObject(raw);
+                const rawMemory = stringField(parsed.raw_memory);
+                const rolloutSummary = stringField(parsed.rollout_summary);
+                if (!rawMemory && !rolloutSummary) {
+                    result.empty++;
+                    continue;
+                }
+                db.upsertStage1Output({
+                    sessionFile,
+                    cwd: sessionCwd,
+                    entryCount,
+                    sourceUpdatedAt,
+                    extractorVersion: EXTRACTOR_VERSION,
+                    generatedAt: (options.now ?? new Date()).toISOString(),
+                    rawMemory: redactSecrets(rawMemory || rolloutSummary).text,
+                    rolloutSummary: redactSecrets(rolloutSummary || rawMemory).text,
+                    rolloutSlug: stringField(parsed.rollout_slug) || undefined,
+                });
+                db.finishPhase1Job(sessionFile, true);
+                result.succeeded++;
+            }
+            catch (error) {
+                db.finishPhase1Job(sessionFile, false, error instanceof Error ? error.message : String(error));
+                result.failed++;
+                result.errors.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    finally {
+        db.close();
+    }
+    return result;
+}
+function listEligibleSessionFiles(limit) {
+    const dir = join(getBubbleHome(), "sessions");
+    if (!existsSync(dir))
+        return [];
+    return collectSessionFiles(dir)
+        .filter((file) => {
+        try {
+            return statSync(file).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+        .slice(0, limit);
+}
+function collectSessionFiles(dir) {
+    const files = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectSessionFiles(path));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+            files.push(path);
+        }
+    }
+    return files;
+}
+function serializeSessionEntries(entries) {
+    // A checkpoint supersedes originals only within its /clear segment. Unlike
+    // live context, durable memory must still consider completed pre-clear work.
+    const segments = [];
+    let segment = [];
+    for (const entry of entries) {
+        if (entry.type === "marker" && entry.kind === "conversation_clear") {
+            if (segment.length)
+                segments.push(segment);
+            segment = [];
+        }
+        else if (entry.type === "context_checkpoint") {
+            // An unreadable checkpoint supersedes nothing; its originals stay in play.
+            const messages = tryCheckpointMessages(entry.checkpoint);
+            if (!messages)
+                continue;
+            segment = messages.flatMap(serializeCheckpointMessage);
+            if (entry.checkpoint.summary && !segment.some(line => line.summary)) {
+                segment.unshift({ text: `[summary] ${cleanText(entry.checkpoint.summary, MAX_CONTENT_CHARS)}`, summary: true });
+            }
+        }
+        else if (entry.type === "summary") {
+            // Legacy summaries have the same superseding semantics as checkpoints.
+            segment = [{ text: serializeSessionEntry(entry), summary: true }];
+        }
+        else {
+            const text = serializeSessionEntry(entry);
+            if (text)
+                segment.push({ text });
+        }
+    }
+    if (segment.length)
+        segments.push(segment);
+    // Give every clear segment a share so a long new conversation cannot erase
+    // all prior durable evidence. Spend unused shares on the newest segments.
+    const budgets = segments.map(() => Math.floor(MAX_TRANSCRIPT_CHARS / Math.max(1, segments.length)));
+    const sizes = segments.map(lines => lines.reduce((total, line) => total + line.text.length + 1, 0) + 40);
+    let spare = MAX_TRANSCRIPT_CHARS;
+    for (let i = 0; i < budgets.length; i++) {
+        budgets[i] = Math.min(budgets[i], sizes[i]);
+        spare -= budgets[i];
+    }
+    for (let i = budgets.length - 1; i >= 0 && spare > 0; i--) {
+        const extra = Math.min(spare, sizes[i] - budgets[i]);
+        budgets[i] += extra;
+        spare -= extra;
+    }
+    return segments.map((lines, i) => selectTranscriptLines(lines, budgets[i], i)).filter(Boolean).join("\n");
+}
+function selectTranscriptLines(lines, budget, segment) {
+    const header = `[conversation segment ${segment + 1}]\n`;
+    if (budget <= header.length + 1)
+        return "";
+    let remaining = budget - header.length - 1;
+    if (lines.reduce((total, line) => total + line.text.length + 1, 0) <= remaining) {
+        return header + lines.map(line => line.text).join("\n");
+    }
+    const selected = new Map();
+    // Reserve at most half for summaries, leaving room for retained and suffix
+    // evidence (especially corrections/revocations). Emit in chronological order.
+    let summaryBudget = Math.floor(remaining / 2);
+    for (let i = lines.length - 1; i >= 0 && summaryBudget > 40; i--) {
+        if (!lines[i].summary)
+            continue;
+        const text = truncate(lines[i].text, Math.min(summaryBudget, remaining) - 1);
+        selected.set(i, text);
+        remaining -= text.length + 1;
+        summaryBudget -= text.length + 1;
+    }
+    for (let i = lines.length - 1; i >= 0 && remaining > 1; i--) {
+        if (selected.has(i))
+            continue;
+        if (lines[i].text.length >= remaining && remaining <= 40)
+            break;
+        const text = truncate(lines[i].text, remaining - 1);
+        selected.set(i, text);
+        remaining -= text.length + 1;
+    }
+    return header + [...selected].sort(([a], [b]) => a - b).map(([, text]) => text).join("\n");
+}
+function serializeCheckpointMessage(message) {
+    if (isCompactionSummaryMessage(message)) {
+        // Projected summaries use an internal-context envelope, but unlike runtime
+        // reminders its payload is durable. Unwrap only this recognized summary.
+        const text = contentToText(message.content).trim()
+            .replace(/^<bubble_internal_context\b[^>]*>\s*/, "")
+            .replace(/\s*<\/bubble_internal_context>$/, "");
+        return [{ text: `[summary] ${cleanText(text, MAX_CONTENT_CHARS)}`, summary: true }];
+    }
+    switch (message.role) {
+        case "user":
+            return textLine("user", contentToText(message.content), MAX_CONTENT_CHARS);
+        case "assistant":
+            return [
+                ...textLine("assistant", message.content, MAX_CONTENT_CHARS),
+                ...(message.toolCalls ?? []).flatMap(call => textLine(`tool_call:${call.name}`, call.arguments, 1_500)),
+            ];
+        case "tool":
+            return textLine(`tool_result${message.isError ? " error=true" : ""}`, message.content, 2_000);
+        case "system":
+        case "meta":
+            return []; // Host prompts and ephemeral runtime reminders are not memory.
+    }
+}
+function textLine(label, content, limit) {
+    const text = cleanText(content, limit);
+    return text.trim() ? [{ text: `[${label}] ${text}` }] : [];
+}
+function cleanText(content, limit) {
+    return truncate(sanitizeInternalReminderBlocks(content), limit);
+}
+function serializeSessionEntry(entry) {
+    switch (entry.type) {
+        case "metadata":
+            return `[metadata] ${JSON.stringify(entry.metadata)}`;
+        case "summary":
+            return `[summary] ${cleanText(entry.summary, MAX_CONTENT_CHARS)}`;
+        case "marker":
+            return `[marker:${entry.kind}] ${cleanText(entry.value, MAX_CONTENT_CHARS)}`;
+        case "user_message":
+            return serializeCheckpointMessage(entry.message).map(line => line.text).join("\n");
+        case "assistant_message":
+            return textLine("assistant", entry.message.content, MAX_CONTENT_CHARS).map(line => line.text).join("\n");
+        case "tool_call":
+            return `[tool_call:${entry.toolCall.name}] ${cleanText(entry.toolCall.arguments, 1_500)}`;
+        case "tool_result":
+            return `[tool_result${entry.message.isError ? " error=true" : ""}] ${cleanText(entry.message.content, 2_000)}`;
+        case "context_checkpoint":
+            return ""; // Handled as a segment projection above.
+        case "provider_error":
+            // Operational diagnostics stay out of the memory-extraction prompt. The
+            // structured session record remains available for local debugging.
+            return "";
+    }
+}
+function countMeaningfulEntries(entries) {
+    return entries.filter((entry) => entry.type === "user_message"
+        || entry.type === "assistant_message"
+        || entry.type === "tool_call"
+        || entry.type === "tool_result"
+        || entry.type === "summary").length;
+}
+function contentToText(content) {
+    return typeof content === "string"
+        ? content
+        : content.map((part) => part.type === "text" ? part.text : "[image]").join("\n");
+}
+function truncate(value, maxChars) {
+    return value.length <= maxChars ? value : `${value.slice(0, maxChars - 40).trimEnd()}\n[truncated ${value.length - maxChars + 40} chars]`;
+}
+function stringField(value) {
+    return typeof value === "string" ? value.trim() : "";
+}

package/dist/memory/phase2.d.ts

@@ -0,0 +1,19 @@
+import type { Message, ThinkingLevel } from "../types.js";
+export interface Phase2Options {
+    cwd: string;
+    complete: (messages: Message[], options?: {
+        model?: string;
+        temperature?: number;
+        thinkingLevel?: ThinkingLevel;
+    }) => Promise<string>;
+    model?: string;
+    limit?: number;
+}
+export interface Phase2Result {
+    status: "succeeded" | "skipped" | "failed";
+    reason?: string;
+    selected: number;
+    memoryPath?: string;
+    summaryPath?: string;
+}
+export declare function runMemoryPhase2(options: Phase2Options): Promise<Phase2Result>;

package/dist/memory/phase2.js

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+import { MemoryDatabase } from "./db.js";
+import { getMemoryPaths } from "./paths.js";
+import { buildConsolidationMessages, parseJsonObject } from "./prompts.js";
+import { classifyMemorySession } from "./session-policy.js";
+import { clearGeneratedMemoryOutputs, rebuildRawMemories, syncRolloutSummaries, writeConsolidatedMemory, } from "./storage.js";
+const DEFAULT_SELECTION_LIMIT = 40;
+export async function runMemoryPhase2(options) {
+    if (!options.model) {
+        return { status: "skipped", reason: "no active model", selected: 0 };
+    }
+    const db = new MemoryDatabase(options.cwd);
+    const paths = getMemoryPaths(options.cwd);
+    const workerId = randomUUID();
+    const claim = db.claimGlobalPhase2Job(workerId, 3600);
+    if (!claim.claimed) {
+        db.close();
+        return { status: "skipped", reason: claim.reason ?? "phase2 unavailable", selected: 0 };
+    }
+    try {
+        const eligible = [];
+        let clearedUnsafeArtifacts = false;
+        for (const output of db.listAllStage1Outputs()) {
+            const source = classifyMemorySession(output.sessionFile);
+            if (source.kind === "native") {
+                eligible.push(output);
+            }
+            else {
+                if (!clearedUnsafeArtifacts) {
+                    // Clear before deleting provenance rows; phase 2 will rebuild from
+                    // the remaining native-only selection below.
+                    clearGeneratedMemoryOutputs(options.cwd);
+                    clearedUnsafeArtifacts = true;
+                }
+                db.deleteStage1Output(output.sessionFile);
+            }
+        }
+        const selected = eligible.slice(0, Math.max(0, options.limit ?? DEFAULT_SELECTION_LIMIT));
+        if (selected.length === 0) {
+            clearGeneratedMemoryOutputs(options.cwd);
+            db.finishGlobalPhase2Job(true, Date.now());
+            return { status: "skipped", reason: "no stage-1 outputs", selected: 0 };
+        }
+        const retained = selected.filter((item) => item.selectedForPhase2);
+        const removed = db.listPreviouslySelectedNotIn(selected.map((item) => item.sessionFile));
+        syncRolloutSummaries(options.cwd, selected);
+        const rawMemories = rebuildRawMemories(options.cwd, selected);
+        writeConsolidatedMemory(options.cwd, buildFallbackConsolidatedMemory(selected));
+        const raw = await options.complete(buildConsolidationMessages({
+            memoryRoot: paths.globalRoot,
+            selected,
+            retained,
+            removed,
+            rawMemories,
+        }), {
+            model: options.model,
+            temperature: 0,
+            thinkingLevel: "off",
+        });
+        const parsed = parseJsonObject(raw);
+        const memoryMd = stringField(parsed.memory_md);
+        const memorySummaryMd = stringField(parsed.memory_summary_md);
+        if (!memoryMd || !memorySummaryMd) {
+            throw new Error("consolidation output must include memory_md and memory_summary_md");
+        }
+        writeConsolidatedMemory(options.cwd, { memoryMd, memorySummaryMd });
+        db.markSelectedForPhase2(selected);
+        db.finishGlobalPhase2Job(true, Date.now());
+        return {
+            status: "succeeded",
+            selected: selected.length,
+            memoryPath: paths.globalMemory,
+            summaryPath: paths.globalSummary,
+        };
+    }
+    catch (error) {
+        db.finishGlobalPhase2Job(false, Date.now(), error instanceof Error ? error.message : String(error));
+        return {
+            status: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+            selected: 0,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+function stringField(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function buildFallbackConsolidatedMemory(selected) {
+    const memoryLines = [
+        "# Bubble Memory",
+        "",
+        "This deterministic memory snapshot was generated from completed phase-1 extraction outputs. It may be replaced by a model-consolidated version when phase 2 finishes.",
+        "",
+    ];
+    const summaryLines = [
+        "# Bubble Memory Summary",
+        "",
+        "Model consolidation is in progress or previously failed, so this summary is derived directly from extracted rollout summaries.",
+        "",
+    ];
+    for (const item of selected) {
+        const title = item.rolloutSlug || item.sessionFile.split("/").pop()?.replace(/\.jsonl$/, "") || "rollout";
+        memoryLines.push(`## ${title}`);
+        memoryLines.push(`cwd: ${item.cwd}`);
+        memoryLines.push(`rollout_path: ${item.sessionFile}`);
+        memoryLines.push("");
+        memoryLines.push(item.rawMemory.trim());
+        memoryLines.push("");
+        const summary = item.rolloutSummary.trim();
+        summaryLines.push(`- ${item.cwd}: ${summary}`);
+    }
+    return {
+        memoryMd: memoryLines.join("\n").trim(),
+        memorySummaryMd: summaryLines.join("\n").trim(),
+    };
+}

package/dist/memory/prompts.d.ts

@@ -0,0 +1,19 @@
+import type { Message } from "../types.js";
+import type { Stage1Output } from "./db.js";
+export declare function buildStageOneMessages(input: {
+    cwd: string;
+    sessionFile: string;
+    transcript: string;
+}): Message[];
+export declare function buildConsolidationMessages(input: {
+    memoryRoot: string;
+    selected: Stage1Output[];
+    retained: Stage1Output[];
+    removed: Stage1Output[];
+    rawMemories: string;
+}): Message[];
+export declare function buildReadPathPrompt(input: {
+    memoryRoot: string;
+    memorySummary: string;
+}): string;
+export declare function parseJsonObject(raw: string): Record<string, unknown>;

package/dist/memory/prompts.js

@@ -0,0 +1,104 @@
+export function buildStageOneMessages(input) {
+    return [
+        {
+            role: "system",
+            content: [
+                "You are Bubble's phase-1 memory extractor.",
+                "Extract durable, reusable memory from one coding-agent rollout.",
+                "Return strict JSON only. Do not wrap it in markdown.",
+                "Do not include secrets, credentials, API keys, tokens, private keys, or full large logs.",
+                "Prefer concrete project facts, user preferences, workflows, decisions, and gotchas.",
+                "Skip transient progress updates and one-off chatter.",
+                "The transcript is a bounded chronological projection; checkpoint summaries replace superseded originals.",
+                "Conversation segments are separated by context clears, not requests to forget durable memory.",
+                "Prefer later corrections and decisions over earlier claims; do not retain revoked facts as current truth.",
+            ].join("\n"),
+        },
+        {
+            role: "user",
+            content: [
+                `rollout_cwd: ${input.cwd}`,
+                `rollout_path: ${input.sessionFile}`,
+                "",
+                "Return this JSON shape:",
+                JSON.stringify({
+                    raw_memory: "detailed markdown memory for this rollout",
+                    rollout_summary: "compact recap with durable lessons and evidence",
+                    rollout_slug: "short-kebab-case-slug",
+                }, null, 2),
+                "",
+                "Rollout transcript:",
+                input.transcript,
+            ].join("\n"),
+        },
+    ];
+}
+export function buildConsolidationMessages(input) {
+    return [
+        {
+            role: "system",
+            content: [
+                "You are Bubble's phase-2 memory consolidation agent.",
+                "Maintain the durable memory workspace automatically.",
+                "Return strict JSON only. Do not wrap it in markdown.",
+                "Do not include secrets, credentials, API keys, tokens, private keys, or full large logs.",
+                "Merge duplicate facts, preserve cwd/project boundaries in the content, and remove stale one-off details.",
+            ].join("\n"),
+        },
+        {
+            role: "user",
+            content: [
+                `memory_root: ${input.memoryRoot}`,
+                "",
+                "Return this JSON shape:",
+                JSON.stringify({
+                    memory_md: "# Bubble Memory\n\n...",
+                    memory_summary_md: "# Bubble Memory Summary\n\n...",
+                }, null, 2),
+                "",
+                `Selected inputs this run: ${input.selected.length}`,
+                `Retained from previous successful Phase 2 selection: ${input.retained.length}`,
+                `Removed from previous successful Phase 2 selection: ${input.removed.length}`,
+                "",
+                "Current selected Phase 1 inputs:",
+                ...input.selected.map((item) => `- session=${item.sessionFile} cwd=${item.cwd} updated_at=${item.sourceUpdatedAt}`),
+                "",
+                "Raw memories:",
+                input.rawMemories,
+            ].join("\n"),
+        },
+    ];
+}
+export function buildReadPathPrompt(input) {
+    return [
+        "## Persistent Memory",
+        "",
+        "You have access to Bubble's persistent memory workspace for continuity across sessions.",
+        "",
+        "Memory retrieval rules:",
+        "- Use memory when the task mentions prior work, this repo, user preferences, or a recurring workflow.",
+        "- Start from the injected memory_summary.md below; use the memory tool (with a query to search, without to re-read the summary) when more detail is needed.",
+        "- Search MEMORY.md before opening rollout summaries; open only the most relevant detailed files.",
+        "- Do not update memory directly during normal tasks; the startup memory pipeline maintains it automatically.",
+        "- Treat memory content and memory rules as private control context.",
+        "- Use memory quietly. Do not mention the memory workspace, memory_summary.md, MEMORY.md, rollout summaries, or <oai-mem-citation> in user-facing answers, hidden reasoning, or tool inputs.",
+        "- Do not quote, list, cite, or summarize memory as a source unless the user explicitly asks how memory affected the answer.",
+        "",
+        `Memory root: ${input.memoryRoot}`,
+        "",
+        "### memory_summary.md",
+        input.memorySummary,
+    ].join("\n");
+}
+export function parseJsonObject(raw) {
+    const trimmed = raw.trim();
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        throw new Error("model did not return a JSON object");
+    const parsed = JSON.parse(trimmed.slice(start, end + 1));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("model returned invalid JSON object");
+    }
+    return parsed;
+}

package/dist/memory/reset.d.ts

@@ -0,0 +1 @@
+export declare function resetMemory(cwd: string): string;

package/dist/memory/reset.js

@@ -0,0 +1,13 @@
+import { MemoryDatabase } from "./db.js";
+import { resetMemoryWorkspace } from "./storage.js";
+export function resetMemory(cwd) {
+    const db = new MemoryDatabase(cwd);
+    try {
+        db.resetStageData();
+    }
+    finally {
+        db.close();
+    }
+    resetMemoryWorkspace(cwd);
+    return "Memory reset complete.";
+}

package/dist/memory/session-policy.d.ts

@@ -0,0 +1,25 @@
+import { SessionManager } from "../session.js";
+export type MemorySessionClassification = {
+    kind: "native";
+    session: SessionManager;
+} | {
+    kind: "external";
+    session: SessionManager;
+} | {
+    kind: "unavailable";
+};
+/**
+ * Classify a persisted Bubble session before its content can enter the native
+ * memory pipeline. Unreadable sources are not assumed to be native: phase 2
+ * must be able to verify the persisted metadata before reusing a stage-1 row.
+ */
+export declare function classifyMemorySession(sessionFile: string): MemorySessionClassification;
+/**
+ * Validate persisted stage-1 provenance before generated memory can be read
+ * into a native provider prompt. Any unverifiable or external source makes
+ * the existing generated artifacts unsafe as a unit: clear them first, then
+ * remove the offending rows so a later phase 2 can rebuild from native-only
+ * inputs. Clearing before deleting is intentional so a crash cannot leave a
+ * contaminated artifact with no database row that identifies its source.
+ */
+export declare function purgeUnsafeMemorySources(cwd: string): number;

package/dist/memory/session-policy.js

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { SessionManager } from "../session.js";
+import { MemoryDatabase } from "./db.js";
+import { clearGeneratedMemoryOutputs } from "./storage.js";
+/**
+ * Classify a persisted Bubble session before its content can enter the native
+ * memory pipeline. Unreadable sources are not assumed to be native: phase 2
+ * must be able to verify the persisted metadata before reusing a stage-1 row.
+ */
+export function classifyMemorySession(sessionFile) {
+    if (!existsSync(sessionFile))
+        return { kind: "unavailable" };
+    try {
+        const session = new SessionManager(sessionFile);
+        return session.getMetadata().externalRuntime === undefined
+            ? { kind: "native", session }
+            : { kind: "external", session };
+    }
+    catch {
+        return { kind: "unavailable" };
+    }
+}
+/**
+ * Validate persisted stage-1 provenance before generated memory can be read
+ * into a native provider prompt. Any unverifiable or external source makes
+ * the existing generated artifacts unsafe as a unit: clear them first, then
+ * remove the offending rows so a later phase 2 can rebuild from native-only
+ * inputs. Clearing before deleting is intentional so a crash cannot leave a
+ * contaminated artifact with no database row that identifies its source.
+ */
+export function purgeUnsafeMemorySources(cwd) {
+    let db;
+    try {
+        db = new MemoryDatabase(cwd);
+        const outputs = db.listAllStage1Outputs();
+        const unsafe = outputs.filter((output) => classifyMemorySession(output.sessionFile).kind !== "native");
+        if (unsafe.length === 0) {
+            if (outputs.length === 0)
+                clearGeneratedMemoryOutputs(cwd);
+            return 0;
+        }
+        clearGeneratedMemoryOutputs(cwd);
+        for (const output of unsafe)
+            db.deleteStage1Output(output.sessionFile);
+        return unsafe.length;
+    }
+    catch {
+        // Generated memory without verifiable provenance must never be injected.
+        clearGeneratedMemoryOutputs(cwd);
+        return 0;
+    }
+    finally {
+        db?.close();
+    }
+}

package/dist/memory/start.d.ts

@@ -0,0 +1,24 @@
+import type { Message, ThinkingLevel } from "../types.js";
+import { type Phase1Result } from "./phase1.js";
+import { type Phase2Result } from "./phase2.js";
+export interface MemoryStartupOptions {
+    cwd: string;
+    complete: (messages: Message[], options?: {
+        model?: string;
+        temperature?: number;
+        thinkingLevel?: ThinkingLevel;
+    }) => Promise<string>;
+    model?: string;
+    disabled?: boolean;
+    minEntries?: number;
+}
+export interface MemoryStartupResult {
+    status: "succeeded" | "skipped" | "failed";
+    phase1?: Phase1Result;
+    phase2?: Phase2Result;
+    reason?: string;
+}
+export declare function runMemoryStartupPipeline(options: MemoryStartupOptions): Promise<MemoryStartupResult>;
+export declare function startMemoryStartupTask(options: MemoryStartupOptions): void;
+export declare function formatMemoryStartupResult(result: MemoryStartupResult): string;
+export declare function isMemoryDisabled(): boolean;