om-memory-system 5.3.0 → 5.4.1

package/README.md

@@ -82,6 +82,10 @@ Each host starts the shared web app when needed, unless it is disabled. Browse
 captured notes on **Project memories**, or ask your agent to search memory for
 an earlier decision.
 
+Each host adds only the memories that match your prompt. An optional setting
+also adds matching memories to the first message of a new session. See
+[Host differences](docs/using-memory.md#host-differences).
+
 ### Terminal command (optional)
 
 A global install puts `om-memory-system` on your `PATH`:

package/dist/adapters/claude-code/hook-client.d.ts

@@ -1,5 +1,5 @@
 import type { EnsureDeps } from "../../services/web-ensure.js";
-export declare const CLAUDE_HOOK_EVENTS: readonly ["session-start", "user-prompt-submit", "stop"];
+export declare const CLAUDE_HOOK_EVENTS: readonly ["session-start", "user-prompt-submit", "subagent-start", "stop"];
 export type ClaudeHookEvent = (typeof CLAUDE_HOOK_EVENTS)[number];
 /** Claude Code caps added context at 10,000 characters; keep a margin. */
 export declare const CLAUDE_CONTEXT_LIMIT = 9500;

package/dist/adapters/claude-code/hook-client.js

@@ -3,7 +3,12 @@ import { AUTH_HEADER } from "../../services/auth-token.js";
 // Claude Code hook client: read the hook input, find or start the OMMS web
 // app, send one request, print the added context, and log one metadata line.
 // It loads no store, embedding model, or engine; the web app does that work.
-export const CLAUDE_HOOK_EVENTS = ["session-start", "user-prompt-submit", "stop"];
+export const CLAUDE_HOOK_EVENTS = [
+    "session-start",
+    "user-prompt-submit",
+    "subagent-start",
+    "stop",
+];
 /** Claude Code caps added context at 10,000 characters; keep a margin. */
 export const CLAUDE_CONTEXT_LIMIT = 9_500;
 /**
@@ -16,11 +21,13 @@ const MAX_INPUT_BYTES = 1024 * 1024;
 const BUDGETS = {
     "session-start": { startMs: 15_000, requestMs: 3_000 },
     "user-prompt-submit": { startMs: 5_000, requestMs: 3_000 },
+    "subagent-start": { startMs: 5_000, requestMs: 3_000 },
     stop: { startMs: 30_000, requestMs: 5_000 },
 };
 const HOOK_EVENT_NAMES = {
     "session-start": "SessionStart",
     "user-prompt-submit": "UserPromptSubmit",
+    "subagent-start": "SubagentStart",
     stop: "Stop",
 };
 /** Read stdin up to a time and size limit. Late, oversized, or broken input is no input. */
@@ -83,6 +90,12 @@ function parseInput(text, event) {
         return null;
     return input;
 }
+/** The one input field each retrieval event adds to the request, beside the common ones. */
+const RETRIEVE_FIELD = {
+    "session-start": "source",
+    "user-prompt-submit": "prompt",
+    "subagent-start": "agent_type",
+};
 function requestFor(event, input) {
     const optional = (key) => (input[key] === undefined ? {} : { [key]: input[key] });
     if (event === "stop")
@@ -103,7 +116,7 @@ function requestFor(event, input) {
             session_id: input.session_id,
             cwd: input.cwd,
             ...optional("transcript_path"),
-            ...optional(event === "session-start" ? "source" : "prompt"),
+            ...optional(RETRIEVE_FIELD[event]),
         },
     };
 }

package/dist/adapters/opencode/tui-recall.js

@@ -11,6 +11,7 @@ import { recallRpc } from "../../v2/recall-rpc.js";
 export const MAX_ROWS = 5;
 const FOLD_STORE_KEY = "omms.recall.fold";
 const SLOT = "session.composer.top";
+const APP_SLOT = "app";
 const DEFAULT_DEBOUNCE_MS = 150;
 /**
  * Host events that pull the recall list. The server records a recall when a model step starts (the
@@ -32,10 +33,11 @@ const PULL_EVENT_TYPES = new Set([
     "session.step.failed",
     "session.execution.failed",
 ]);
+const SUMMARY_MODES = new Set(["search", "recent", "opening", "restore"]);
 function isSummary(value) {
     const v = value;
     return (!!v &&
-        (v.mode === "search" || v.mode === "recent") &&
+        SUMMARY_MODES.has(v.mode) &&
         Array.isArray(v.items) &&
         v.items.every((item) => !!item && typeof item.headline === "string"));
 }
@@ -196,7 +198,8 @@ export function startTuiRecall(deps) {
         repaintFold();
     };
     // The host owns a keymap layer through the component that created it and removes it when that
-    // component is disposed. A slot remount therefore needs a fresh layer, so this runs once per render.
+    // component is disposed. The row slot unmounts on screen changes, so the layer lives in the
+    // "app" slot instead, which stays mounted for the whole TUI.
     const registerCommand = () => {
         layerHandle = guard(() => deps.keymap.layer(() => ({
             mode: "global",
@@ -261,7 +264,6 @@ export function startTuiRecall(deps) {
                 return id;
             };
             follow();
-            registerCommand();
             return deps.jsx("box", {
                 flexDirection: "column",
                 get children() {
@@ -276,6 +278,13 @@ export function startTuiRecall(deps) {
         }
     };
     const removeSlot = guard(() => deps.ui.slot({ append: SLOT, render }));
+    // Draws nothing. It exists so the command layer is owned by a component that is not disposed
+    // when the session view changes.
+    const renderCommandOwner = () => {
+        registerCommand();
+        return null;
+    };
+    const removeCommandSlot = guard(() => deps.ui.slot({ append: APP_SLOT, render: renderCommandOwner }));
     const offPush = guard(() => rpc?.events.on("recalled", (event) => {
         const id = event?.data?.sessionID;
         if (typeof id === "string" && sessions.has(id))
@@ -297,6 +306,7 @@ export function startTuiRecall(deps) {
         release(offData);
         release(offPush);
         release(removeSlot);
+        release(removeCommandSlot);
         release(layerHandle);
     };
 }

package/dist/adapters/pi/extension.d.ts

@@ -12,6 +12,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
  * - `memory` tool          -> shared add/search/profile/list/forget/help and
  *                             portability operations
  * - `skills` tool          -> shared skill-learning operations (skills-tool.ts)
+ * - `/omms-recall`        -> fold or unfold the recall rows (recall-rows.ts)
  *
  * Pi types are imported type-only: the compiled extension carries no Pi
  * runtime dependency and uses the host Pi runtime provided at load time.

package/dist/adapters/pi/extension.js

@@ -12,7 +12,8 @@ import { createPiLiveModels } from "./live-model.js";
 import { registerPiHistoryImportCommand } from "./import-command.js";
 import { registerPiSkillsTool } from "./skills-tool.js";
 import { performPiProfileLearning } from "./profile.js";
-import { buildRetrievalSection, retrievalWrapperBytes, wrapRetrievalSection, } from "../../core/retrieval.js";
+import { createPiRecallRows } from "./recall-rows.js";
+import { createPiSessionContext } from "./session-context.js";
 import { DEFAULT_RETRIEVAL_MAX_TOKENS, tokensToByteCeiling } from "../../core/context-budget.js";
 import { ommsStatusLabel } from "../../services/status-glyphs.js";
 const GLOBAL_PLUGIN_WARMUP_KEY = Symbol.for("omms.plugin.warmedup");
@@ -67,6 +68,7 @@ function lastSettledUserPrompt(entries) {
  * - `memory` tool          -> shared add/search/profile/list/forget/help and
  *                             portability operations
  * - `skills` tool          -> shared skill-learning operations (skills-tool.ts)
+ * - `/omms-recall`        -> fold or unfold the recall rows (recall-rows.ts)
  *
  * Pi types are imported type-only: the compiled extension carries no Pi
  * runtime dependency and uses the host Pi runtime provided at load time.
@@ -79,6 +81,8 @@ export default function ommsPiExtension(pi) {
     let latestCtx = null;
     let backfillSessionId = null;
     let statusVersion = 0;
+    const recallRows = createPiRecallRows();
+    const sessionContext = createPiSessionContext(recallRows);
     const startStatus = (ctx, status) => {
         const version = ++statusVersion;
         if (ctx.hasUI)
@@ -101,7 +105,7 @@ export default function ommsPiExtension(pi) {
         const level = notification.variant === "success" ? "info" : notification.variant;
         ctx.ui.notify(`${notification.title}: ${notification.message}`, level);
     };
-    pi.on("session_start", async (_event, ctx) => {
+    pi.on("session_start", async (event, ctx) => {
         const status = startStatus(ctx, "warming");
         try {
             latestCtx = ctx;
@@ -221,6 +225,10 @@ export default function ommsPiExtension(pi) {
             else {
                 finishStatus(ctx, status, "connected");
             }
+            if (event.reason === "resume") {
+                sessionContext.markSeen(sessionId);
+                await sessionContext.loadRestore(ctx);
+            }
         }
         catch (error) {
             log("Pi session_start error", { error: String(error) }, "error");
@@ -234,19 +242,13 @@ export default function ommsPiExtension(pi) {
         refreshConfigIfChanged(ctx.cwd);
         // The default guards partial CONFIG stubs in tests.
         const budgetBytes = tokensToByteCeiling(CONFIG.retrievalMaxTokens ?? DEFAULT_RETRIEVAL_MAX_TOKENS);
-        if (!isConfigured() || !CONFIG.chatMessage.enabled)
+        if (!isConfigured() || (!CONFIG.chatMessage.enabled && !CONFIG.compaction?.enabled))
             return;
         const status = startStatus(ctx, "recalling");
         try {
-            // The wrapper counts against the captured allowance, so the packed
-            // section reserves its bytes.
-            const section = await buildRetrievalSection(event.prompt, ctx.cwd, ctx.sessionManager.getSessionId(), { maxBytes: budgetBytes, wrapperBytes: retrievalWrapperBytes() });
+            const extra = await sessionContext.recall(ctx, event.prompt, budgetBytes);
             finishStatus(ctx, status, "connected");
-            if (!section)
-                return;
-            return {
-                systemPrompt: event.systemPrompt + "\n\n" + wrapRetrievalSection(section),
-            };
+            return extra ? { systemPrompt: event.systemPrompt + extra } : undefined;
         }
         catch (error) {
             log("Pi before_agent_start retrieval error", { error: String(error) }, "error");
@@ -254,6 +256,12 @@ export default function ommsPiExtension(pi) {
             return undefined;
         }
     });
+    // OMMS adds memories after compaction; it never replaces Pi's own summary (no
+    // session_before_compact handler).
+    pi.on("session_compact", async (_event, ctx) => {
+        sessionContext.markSeen(ctx.sessionManager.getSessionId());
+        await sessionContext.loadRestore(ctx);
+    });
     pi.on("agent_settled", async (_event, ctx) => {
         if (!isConfigured())
             return;
@@ -301,6 +309,8 @@ export default function ommsPiExtension(pi) {
     });
     pi.on("session_shutdown", async (_event, ctx) => {
         clearStatus(ctx);
+        recallRows.reset(ctx);
+        sessionContext.reset();
         latestCtx = null;
         captureState = createPiCaptureState();
         promptsSinceProfileAnalysis = [];
@@ -350,6 +360,13 @@ export default function ommsPiExtension(pi) {
             };
         },
     });
+    pi.registerCommand("omms-recall", {
+        description: "Unfold or fold the OMMS recall rows",
+        handler: async (_args, ctx) => {
+            refreshConfigIfChanged(ctx.cwd);
+            await recallRows.toggleAll(ctx, CONFIG.visibleRecall !== false);
+        },
+    });
     registerPiSkillsTool(pi);
     registerPiHistoryImportCommand(pi, () => latestCtx);
 }

package/dist/adapters/pi/recall-rows.d.ts

@@ -0,0 +1,31 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type RecallSummary } from "../../core/recall-summary.js";
+/**
+ * Fold rows for OMMS recalls above the Pi editor (change add-pi-visible-recall, TDR-062).
+ *
+ * Rows are drawn only in Pi's interactive terminal (`ctx.mode === "tui"`). RPC, JSON and print
+ * runs, subagent children among them, record and draw nothing. Summaries and fold state live in
+ * memory only: Pi offers no extension store outside the session file, and a session entry would
+ * write memory text into the session file. Logs carry the session id, mode and count only.
+ */
+export declare const RECALL_WIDGET_KEY = "omms-recall";
+/** Latest summaries kept per session. */
+export declare const MAX_RECALL_SUMMARIES = 20;
+/** Most rows shown at once. */
+export declare const MAX_RECALL_ROWS = 5;
+/** Longest query kept per summary. An unfolded row shows at most 300 characters of it. */
+export declare const MAX_RECALL_QUERY_CHARS = 300;
+export interface PiRecallRows {
+    /**
+     * Record one recall and redraw. Does nothing outside the interactive terminal. `query` is the
+     * prompt for a `search` row, the configured query for an `opening` row, and ignored for `restore`.
+     */
+    record(ctx: ExtensionContext, query: string, section: string | null, enabled: boolean, mode?: "search" | "opening" | "restore"): Promise<void>;
+    /** `/omms-recall`: unfold every shown row, or fold them all when all are open. */
+    toggleAll(ctx: ExtensionContext, enabled: boolean): Promise<void>;
+    /** Forget summaries and fold state, and clear the widget. */
+    reset(ctx: ExtensionContext): void;
+    /** Summaries of the current session, oldest first. */
+    summaries(): readonly RecallSummary[];
+}
+export declare function createPiRecallRows(): PiRecallRows;

package/dist/adapters/pi/recall-rows.js

@@ -0,0 +1,148 @@
+import { buildRecallSummary, callTitle, unfoldLines, } from "../../core/recall-summary.js";
+import { log } from "../../services/logger.js";
+/**
+ * Fold rows for OMMS recalls above the Pi editor (change add-pi-visible-recall, TDR-062).
+ *
+ * Rows are drawn only in Pi's interactive terminal (`ctx.mode === "tui"`). RPC, JSON and print
+ * runs, subagent children among them, record and draw nothing. Summaries and fold state live in
+ * memory only: Pi offers no extension store outside the session file, and a session entry would
+ * write memory text into the session file. Logs carry the session id, mode and count only.
+ */
+export const RECALL_WIDGET_KEY = "omms-recall";
+/** Latest summaries kept per session. */
+export const MAX_RECALL_SUMMARIES = 20;
+/** Most rows shown at once. */
+export const MAX_RECALL_ROWS = 5;
+/** Longest query kept per summary. An unfolded row shows at most 300 characters of it. */
+export const MAX_RECALL_QUERY_CHARS = 300;
+/** Cut by code point. Used only when Pi's own width helper cannot load. */
+function plainCut(text, width) {
+    const chars = Array.from(text);
+    if (chars.length <= width)
+        return text;
+    if (width <= 3)
+        return chars.slice(0, Math.max(0, width)).join("");
+    return `${chars.slice(0, width - 3).join("")}...`;
+}
+// Pi resolves its own packages for an extension, so this import works inside Pi without a
+// dependency (TDR-062). It stays dynamic so the extension carries no static Pi runtime import.
+let cutLoad;
+function loadCut() {
+    cutLoad ??= import("@earendil-works/pi-tui").then((tui) => (text, width) => tui.truncateToWidth(text, width), () => plainCut);
+    return cutLoad;
+}
+function paint(theme, text) {
+    try {
+        return theme.fg("muted", text);
+    }
+    catch {
+        return text;
+    }
+}
+function errorCode(error) {
+    return error instanceof Error ? error.name : "unknown";
+}
+export function createPiRecallRows() {
+    let sessionID = null;
+    let ring = [];
+    let lastSeq = 0;
+    const open = new Set();
+    const forget = () => {
+        sessionID = null;
+        ring = [];
+        lastSeq = 0;
+        open.clear();
+    };
+    const shown = () => ring.slice(-MAX_RECALL_ROWS);
+    const rowLines = () => shown().flatMap((summary) => {
+        const unfolded = open.has(summary.seq ?? 0);
+        const title = `${unfolded ? "▾" : "▸"} ● ${callTitle(summary)}`;
+        return unfolded ? [title, ...unfoldLines(summary).map((line) => `  ${line}`)] : [title];
+    });
+    const setWidget = (ctx, lines, cut) => {
+        try {
+            if (!lines) {
+                ctx.ui.setWidget(RECALL_WIDGET_KEY, undefined);
+                return;
+            }
+            ctx.ui.setWidget(RECALL_WIDGET_KEY, (_tui, theme) => ({
+                render(width) {
+                    try {
+                        return lines.map((line) => paint(theme, cut(line, width)));
+                    }
+                    catch {
+                        return [];
+                    }
+                },
+                invalidate() { },
+            }), { placement: "aboveEditor" });
+        }
+        catch (error) {
+            log("Pi recall: could not draw rows", { sessionID, code: errorCode(error) }, "error");
+        }
+    };
+    const draw = async (ctx, enabled) => {
+        const cut = await loadCut();
+        setWidget(ctx, enabled && ring.length > 0 ? rowLines() : undefined, cut);
+    };
+    return {
+        async record(ctx, query, section, enabled, mode = "search") {
+            try {
+                if (ctx.mode !== "tui" || !section)
+                    return;
+                const built = buildRecallSummary(section, mode, query.slice(0, MAX_RECALL_QUERY_CHARS));
+                if (!built)
+                    return;
+                const id = ctx.sessionManager.getSessionId();
+                if (id !== sessionID) {
+                    forget();
+                    sessionID = id;
+                }
+                const summary = { ...built, seq: ++lastSeq };
+                ring = [...ring, summary].slice(-MAX_RECALL_SUMMARIES);
+                for (const seq of open)
+                    if (!ring.some((kept) => kept.seq === seq))
+                        open.delete(seq);
+                log("Pi recall: summary recorded", {
+                    sessionID: id,
+                    mode: summary.mode,
+                    count: summary.items.length,
+                });
+                await draw(ctx, enabled);
+            }
+            catch (error) {
+                log("Pi recall: could not record summary", { sessionID, code: errorCode(error) }, "error");
+            }
+        },
+        async toggleAll(ctx, enabled) {
+            try {
+                if (ctx.mode !== "tui")
+                    return;
+                const seqs = shown().map((summary) => summary.seq ?? 0);
+                const unfold = seqs.some((seq) => !open.has(seq));
+                for (const seq of seqs) {
+                    if (unfold)
+                        open.add(seq);
+                    else
+                        open.delete(seq);
+                }
+                await draw(ctx, enabled);
+            }
+            catch (error) {
+                log("Pi recall: could not toggle rows", { sessionID, code: errorCode(error) }, "error");
+            }
+        },
+        reset(ctx) {
+            const hadRows = ring.length > 0;
+            forget();
+            try {
+                if (hadRows && ctx.mode === "tui")
+                    ctx.ui.setWidget(RECALL_WIDGET_KEY, undefined);
+            }
+            catch (error) {
+                log("Pi recall: could not clear rows", { code: errorCode(error) }, "error");
+            }
+        },
+        summaries: () => ring,
+    };
+}

package/dist/adapters/pi/session-context.d.ts

@@ -0,0 +1,22 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PiRecallRows } from "./recall-rows.js";
+/**
+ * What Pi adds to the system prompt of one run beyond the prompt's own recall (change
+ * align-recall-host-parity, design D1d, D4, D5): the opening section on the first prompt of a
+ * main session, and the session's own memories after a compaction or a resume. In memory only.
+ */
+/** Session ids remembered as seen, and restored sessions kept. The oldest is dropped first. */
+export declare const MAX_TRACKED_SESSIONS = 500;
+/** A Pi child started by om-pi-subagents (`--mode rpc --no-session --no-extensions`). */
+export declare function isPiChild(): boolean;
+export interface PiSessionContext {
+    /** Note that the session has had a prompt, so a later prompt is not its first. */
+    markSeen(sessionId: string): void;
+    /** Load the session's own memories for restore, replacing any earlier load. */
+    loadRestore(ctx: ExtensionContext): Promise<void>;
+    /** Text to append to the system prompt for this run, or null. */
+    recall(ctx: ExtensionContext, prompt: string, budgetBytes: number): Promise<string | null>;
+    /** Forget every restored session. */
+    reset(): void;
+}
+export declare function createPiSessionContext(rows: PiRecallRows): PiSessionContext;

package/dist/adapters/pi/session-context.js

@@ -0,0 +1,125 @@
+import { CONFIG } from "../../config.js";
+import { buildFirstPromptSections, openingQueryFor } from "../../core/opening-context.js";
+import { buildRetrievalSection, formatMemoriesForCompaction, retrievalWrapperBytes, wrapRetrievalSection, } from "../../core/retrieval.js";
+import { memoryClient } from "../../services/client.js";
+import { log } from "../../services/logger.js";
+import { getTags } from "../../services/tags.js";
+import { utf8ByteLength } from "../../utils/context-limit.js";
+/** The blank line before each section. The budget counts it for the second section on. */
+const SECTION_SEPARATOR = "\n\n";
+const SECTION_SEPARATOR_BYTES = 2;
+/**
+ * What Pi adds to the system prompt of one run beyond the prompt's own recall (change
+ * align-recall-host-parity, design D1d, D4, D5): the opening section on the first prompt of a
+ * main session, and the session's own memories after a compaction or a resume. In memory only.
+ */
+/** Session ids remembered as seen, and restored sessions kept. The oldest is dropped first. */
+export const MAX_TRACKED_SESSIONS = 500;
+const HOST = "pi";
+/** A Pi child started by om-pi-subagents (`--mode rpc --no-session --no-extensions`). */
+export function isPiChild() {
+    return process.env.OMPS_CHILD === "1";
+}
+function hasEarlierUserEntry(branch) {
+    return (Array.isArray(branch) &&
+        branch.some((entry) => entry?.type === "message" && entry.message?.role === "user"));
+}
+function remember(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > MAX_TRACKED_SESSIONS)
+        map.delete(map.keys().next().value);
+}
+export function createPiSessionContext(rows) {
+    const seen = new Map();
+    const restored = new Map();
+    const restoreEnabled = () => !isPiChild() && CONFIG.compaction?.enabled === true;
+    async function loadRestore(ctx) {
+        if (!restoreEnabled())
+            return;
+        const sessionId = ctx.sessionManager.getSessionId();
+        try {
+            const result = await memoryClient.searchMemoriesBySessionID(sessionId, getTags(ctx.cwd).project.tag, CONFIG.compaction.memoryLimit);
+            const own = result.success
+                ? result.results.filter((memory) => memory.metadata?.host === HOST)
+                : [];
+            if (own.length > 0)
+                remember(restored, sessionId, { memories: own, announced: false });
+            else
+                restored.delete(sessionId);
+        }
+        catch (error) {
+            log("Pi restore load failed", { code: error instanceof Error ? error.name : "unknown" }, "error");
+        }
+    }
+    return {
+        markSeen(sessionId) {
+            remember(seen, sessionId, true);
+        },
+        loadRestore,
+        async recall(ctx, prompt, budgetBytes) {
+            const sessionId = ctx.sessionManager.getSessionId();
+            const child = isPiChild();
+            const visible = CONFIG.visibleRecall !== false;
+            const budget = { maxBytes: budgetBytes, wrapperBytes: retrievalWrapperBytes() };
+            // A session this process has not seen: first prompt when its branch holds no user entry,
+            // else a resumed session.
+            const unseen = !child && !seen.has(sessionId);
+            if (unseen)
+                remember(seen, sessionId, true);
+            const resumed = unseen && hasEarlierUserEntry(ctx.sessionManager.getBranch());
+            const openingQuery = unseen && !resumed
+                ? openingQueryFor({
+                    openingContext: CONFIG.openingContext,
+                    openingContextQuery: CONFIG.openingContextQuery,
+                })
+                : null;
+            let promptSection = null;
+            let openingSection = null;
+            if (CONFIG.chatMessage.enabled && (!child || CONFIG.subagentMemory)) {
+                if (openingQuery) {
+                    ({ promptSection, openingSection } = await buildFirstPromptSections({
+                        prompt,
+                        openingQuery,
+                        directory: ctx.cwd,
+                        sessionId,
+                        budget,
+                        openingReserveBytes: SECTION_SEPARATOR_BYTES,
+                    }));
+                }
+                else {
+                    const section = await buildRetrievalSection(prompt, ctx.cwd, sessionId, budget);
+                    promptSection = section ? wrapRetrievalSection(section) : null;
+                }
+            }
+            if (resumed)
+                await loadRestore(ctx);
+            let restoredSection = null;
+            const entry = restoreEnabled() ? restored.get(sessionId) : undefined;
+            if (entry) {
+                const left = budgetBytes -
+                    (promptSection ? utf8ByteLength(promptSection) + SECTION_SEPARATOR_BYTES : 0);
+                const text = left > budget.wrapperBytes
+                    ? formatMemoriesForCompaction(entry.memories, {
+                        maxBytes: left,
+                        wrapperBytes: budget.wrapperBytes,
+                    })
+                    : "";
+                restoredSection = text ? wrapRetrievalSection(text) : null;
+            }
+            // Screen-only rows; the returned text stays the same with them on or off.
+            await rows.record(ctx, prompt, promptSection, visible);
+            if (openingSection)
+                await rows.record(ctx, openingQuery ?? "", openingSection, visible, "opening");
+            if (restoredSection && entry && !entry.announced) {
+                entry.announced = true;
+                await rows.record(ctx, "", restoredSection, visible, "restore");
+            }
+            const parts = [promptSection, openingSection, restoredSection].filter(Boolean);
+            return parts.length > 0 ? SECTION_SEPARATOR + parts.join(SECTION_SEPARATOR) : null;
+        },
+        reset() {
+            restored.clear();
+        },
+    };
+}