@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/memory/index.ts

@@ -7,20 +7,29 @@
  */
 
 import * as fs from "node:fs";
+import * as os from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
 import {
   UNIPI_EVENTS,
   MODULES,
   emitEvent,
   getPackageVersion,
+  type KitTheme,
+  formatTokens,
+  harnessMetadata,
 } from "@pi-unipi/core";
 
 import { createSessionBackend, type SessionBackend } from "./session.js";
-import { registerMemoryTools, MEMORY_TOOLS, memoryCard } from "./tools.js";
+import { registerMemoryTools, MEMORY_TOOLS, memoryCard, type RailRow } from "./tools.js";
 import { registerMemoryCommands, type SessionOverrides } from "./commands.js";
+import {
+  SAVE_CARD_TYPE,
+  shouldRunSideSave,
+  startMemorySave,
+  type MemorySaveRun,
+} from "./save-session.js";
 import { readMemoryConfig, agentHooksEnabled } from "./settings.js";
 import { replayPending, pendingCount, type PendingOp } from "./pending.js";
 import { adoptLooseFiles, needsMigration, runConversion, readConversionState } from "./convert.js";
@@ -45,6 +54,42 @@ const RECALL_CUSTOM_TYPE = "unipi-memory-recall-reminder";
 const RETRO_CUSTOM_TYPE = "unipi-memory-retro-reminder";
 const CARD_CUSTOM_TYPE = "unipi-memory-session-card";
 
+/** Human-readable save-pass usage line (UI only — persisted usage stays raw). */
+export function saveUsageLine(usage: {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+  output: number;
+}): string {
+  return `save pass · input ${formatTokens(usage.input)} · cache read ${formatTokens(usage.cacheRead)} / write ${formatTokens(usage.cacheWrite)} · output ${formatTokens(usage.output)} tokens`;
+}
+
+/** ~/.unipi/logs/memory.log lines when UNIPI_DEBUG_MEMORY=1 (silent otherwise). */
+export function memoryDebug(line: string): void {
+  if (process.env.UNIPI_DEBUG_MEMORY !== "1") return;
+  try {
+    const dir = join(os.homedir(), ".unipi", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(join(dir, "memory.log"), `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // best-effort
+  }
+}
+
+/** True when the branch segment AFTER the last compaction already carries the
+ *  recall reminder — a /reload or resume must not inject it twice. */
+export function branchHasRecallReminder(
+  branch: Array<{ type: string; customType?: string }>,
+): boolean {
+  let lastCompact = -1;
+  branch.forEach((entry, index) => {
+    if (entry.type === "compaction") lastCompact = index;
+  });
+  return branch
+    .slice(lastCompact + 1)
+    .some((entry) => entry.type === "custom_message" && entry.customType === RECALL_CUSTOM_TYPE);
+}
+
 export function buildMemoryRecallReminder(input: {
   projectName: string;
   memories: Array<{ title: string }>;
@@ -84,6 +129,23 @@ export function buildMemoryRecallReminder(input: {
   return lines.join("\n");
 }
 
+/** One-queued-reminder guard (exported for tests): queue() latches until the
+ * reminder lands (clear on before_agent_start). */
+export function retroReminderGuard(): { readonly queued: boolean; queue(): void; clear(): void } {
+  let queued = false;
+  return {
+    get queued() {
+      return queued;
+    },
+    queue() {
+      queued = true;
+    },
+    clear() {
+      queued = false;
+    },
+  };
+}
+
 export default function (pi: ExtensionAPI) {
   let backend: SessionBackend | null = null;
   let recallDone = false;
@@ -121,15 +183,14 @@ export default function (pi: ExtensionAPI) {
 
   // Render the recall/end reminders as small badges (UI-only).
   try {
-    const badge = (icon: string, label: string) =>
-      (message: { content?: unknown }, _options: unknown, theme: { bg?: (c: string, t: string) => string; fg?: (c: string, t: string) => string; bold?: (t: string) => string }) => {
-        const text = String(message.content ?? "").split("\n")[0] ?? label;
-        const inner = theme.fg?.("syntaxKeyword", theme.bold?.(` ${icon} ${label} `) ?? ` ${icon} ${label} `) ?? ` ${label} `;
-        const b = theme.bg?.("customMessageBg", inner) ?? inner;
-        return new Text(`${b} ${theme.fg?.("dim", text.replace(/[*#🧠]/gu, "").trim()) ?? text}`, 0, 0);
+    // Same rail as every memory surface: `▌ Memory recall  <first line>`.
+    const reminder = (label: string) =>
+      (message: { content?: unknown }, _options: unknown, theme: KitTheme) => {
+        const text = (String(message.content ?? "").split("\n")[0] ?? "").replace(/[*#🧠]/gu, "").trim();
+        return memoryCard(theme, [`${theme.bold(label)} ${theme.fg("dim", text)}`]);
       };
-    pi.registerMessageRenderer?.(RECALL_CUSTOM_TYPE, badge("◈", "memory recall") as never);
-    pi.registerMessageRenderer?.(RETRO_CUSTOM_TYPE, badge("◈", "memory save?") as never);
+    pi.registerMessageRenderer?.(RECALL_CUSTOM_TYPE, reminder("Memory recall") as never);
+    pi.registerMessageRenderer?.(RETRO_CUSTOM_TYPE, reminder("Memory save?") as never);
   } catch { /* renderer registration is UI-dependent */ }
 
   // Session card (UI-only entry + renderer).
@@ -142,16 +203,17 @@ export default function (pi: ExtensionAPI) {
         const cfg = readMemoryConfig();
         const recall = cfg.recallAtStart && overrides.recall !== false ? "on" : "off";
         const write = cfg.write && overrides.write !== false ? "on" : "off";
-        const lines = [
-          `◈ memory palace · ${d.project}`,
-          `${d.count} memories · recall ${recall} · write ${write}${d.wakeUp ? " · wake-up ready (expand)" : ""}`,
-          ...(d.issue ? [d.issue] : []),
-          ...(d.needsMigrate ? ["v2 memories found — run /unipi:memory migrate"] : []),
+        const t = theme as unknown as KitTheme;
+        const rows: RailRow[] = [
+          { left: `${t.bold("Memory palace")} ${d.project}`, right: t.fg("dim", `${String(d.count)} ${d.count === 1 ? "memory" : "memories"}`) },
+          t.fg("dim", `recall ${recall} · write ${write}${d.wakeUp ? " · wake-up ready (expand)" : ""}`),
+          ...(d.issue ? [t.fg("warning", d.issue)] : []),
+          ...(d.needsMigrate ? [t.fg("warning", "v2 memories found — run /unipi:memory migrate")] : []),
         ];
         if ((_options as { expanded?: boolean } | undefined)?.expanded && d.wakeUp) {
-          lines.push("", ...d.wakeUp.split("\n"));
+          rows.push("", ...d.wakeUp.split("\n").map((l) => t.fg("muted", l)));
         }
-        return memoryCard(theme as never, lines);
+        return memoryCard(t, rows, d.issue ? "warning" : "memory");
       },
     );
   } catch { /* UI-dependent */ }
@@ -159,6 +221,13 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     recallDone = false;
     storeDone = false;
+    // Reload/resume: the reminder is already in this branch's context tail —
+    // injecting again would just repeat it.
+    try {
+      if (branchHasRecallReminder(ctx.sessionManager.getBranch())) recallDone = true;
+    } catch {
+      // branch read is best-effort
+    }
     overrides.recall = undefined;
     overrides.write = undefined;
     wakeUpPromise = null;
@@ -410,6 +479,9 @@ export default function (pi: ExtensionAPI) {
         ])) ?? undefined;
     }
 
+    // Injected once per session (and once after each compaction — the
+    // session_compact / COMPACTOR_COMPACTED handlers below reset the flag).
+    recallDone = true;
     return {
       message: {
         customType: RECALL_CUSTOM_TYPE,
@@ -421,36 +493,142 @@ export default function (pi: ExtensionAPI) {
           wakeUp: wake,
         }),
         display: true,
+        details: { unipiHarness: harnessMetadata({ source: "Memory", title: "Memory recall", synopsis: "Recalled at session start" }, "before_agent_start") },
       },
     };
   });
 
-  pi.on("agent_end", async (_event, _ctx) => {
-    if (storeDone || !recallDone) return;
-    if (!readMemoryConfig().write || overrides.write === false) return;
-    if (!agentHooksEnabled()) return;
-    if (!pi.getActiveTools().includes(MEMORY_TOOLS.STORE)) return;
-    pi.sendMessage(
-      {
-        customType: RETRO_CUSTOM_TYPE,
-        content: [
-          "**🧠 Memory reminder:** If you learned something non-obvious in this task,",
-          "call `memory_store` to save it as a memory for future sessions.",
-          "Update existing memories instead of creating duplicates.",
-        ].join(" "),
-        display: true,
+  // Save pass outcome card — UI-only entry, never model context.
+  try {
+    pi.registerEntryRenderer?.<{ titles?: string[]; usage?: { input: number; cacheRead: number; cacheWrite: number; output: number } }>(
+      SAVE_CARD_TYPE,
+      (entry, _options, theme) => {
+        const d = entry.data;
+        if (!d?.titles?.length) return undefined;
+        const t = theme as unknown as KitTheme;
+        const rows: RailRow[] = [
+          { left: `${t.bold("Memory saved")} ${d.titles.join(", ")}` },
+        ];
+        if (d.usage) {
+          rows.push(t.fg("dim", saveUsageLine(d.usage)));
+        }
+        return memoryCard(t, rows);
       },
-      { deliverAs: "nextTurn" },
     );
+  } catch { /* UI-dependent */ }
+
+  // Two agent runs can end before the next user prompt (e.g. a background-task
+  // completion triggers a follow-up turn) — keep at most one queued reminder.
+  const retro = retroReminderGuard();
+
+  pi.on("before_agent_start", () => {
+    retro.clear();
+  });
+
+  // Per-run activity for the side save pass: reset on agent_start, counted on
+  // tool_call. The side session runs on its own AgentSession — its calls never
+  // reach these handlers.
+  let runToolCalls = 0;
+  let runHadWrite = false;
+  let runStoredMemory = false;
+  let saveRun: MemorySaveRun | null = null;
+
+  pi.on("agent_start", () => {
+    runToolCalls = 0;
+    runHadWrite = false;
+    runStoredMemory = false;
+  });
+  pi.on("tool_call", (event) => {
+    runToolCalls += 1;
+    if (event.toolName === "edit" || event.toolName === "write") runHadWrite = true;
+    if (event.toolName === MEMORY_TOOLS.STORE || event.toolName === MEMORY_TOOLS.DELETE) {
+      runStoredMemory = true;
+    }
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    const cfg = readMemoryConfig(ctx.cwd);
+    const mode = cfg.saveMode;
+
+    if (mode === "reminder") {
+      // Exactly the pre-side behaviour: one nextTurn nudge per finished run.
+      if (storeDone || !recallDone) return;
+      if (retro.queued) return;
+      if (!cfg.write || overrides.write === false) return;
+      if (!agentHooksEnabled()) return;
+      if (!pi.getActiveTools().includes(MEMORY_TOOLS.STORE)) return;
+      retro.queue();
+      pi.sendMessage(
+        {
+          customType: RETRO_CUSTOM_TYPE,
+          content: [
+            "**🧠 Memory reminder:** If you learned something non-obvious in this task,",
+            "call `memory_store` to save it as a memory for future sessions.",
+            "Update existing memories instead of creating duplicates.",
+          ].join(" "),
+          display: true,
+          details: { unipiHarness: harnessMetadata({ source: "Memory", title: "Memory save?", synopsis: "Save reminder after a finished run" }, "nextTurn") },
+        },
+        { deliverAs: "nextTurn" },
+      );
+      return;
+    }
+
+    if (mode !== "side") return; // "off"
+    if (
+      !shouldRunSideSave({
+        write: cfg.write,
+        writeOverride: overrides.write,
+        hooksEnabled: agentHooksEnabled(),
+        storeActive: pi.getActiveTools().includes(MEMORY_TOOLS.STORE),
+        runToolCalls,
+        runHadWrite,
+        runStoredMemory,
+        running: saveRun !== null,
+      })
+    ) {
+      return;
+    }
+
+    const run = startMemorySave(pi, ctx, () => backend);
+    saveRun = run;
+    void run.finished
+      .then((outcome) => {
+        const usage = outcome.usage;
+        memoryDebug(
+          `save: stored=[${outcome.stored.join(", ")}]` +
+            (usage ? ` usage in=${usage.input} cacheRead=${usage.cacheRead} cacheWrite=${usage.cacheWrite} out=${usage.output}` : "") +
+            (outcome.error ? ` error=${outcome.error}` : ""),
+        );
+        if (outcome.stored.length > 0) {
+          // A store happened — a later reminder-mode switch shouldn't re-nag.
+          storeDone = true;
+          try {
+            pi.appendEntry(SAVE_CARD_TYPE, { titles: outcome.stored, usage });
+          } catch {
+            // card is cosmetic
+          }
+        }
+      })
+      .catch((error) => memoryDebug(`save: ${error instanceof Error ? error.message : String(error)}`))
+      .finally(() => {
+        if (saveRun === run) saveRun = null;
+      });
   });
 
   pi.on("session_compact", async () => {
     recallDone = false;
   });
+  // Boundary compactions (compactor's percentage trigger) skip session_compact.
+  pi.events?.on?.(UNIPI_EVENTS.COMPACTOR_COMPACTED, () => {
+    recallDone = false;
+  });
 
   pi.on("session_shutdown", async () => {
     if (pendingTimer) { clearInterval(pendingTimer); pendingTimer = null; }
     replayKick = () => {};
+    saveRun?.abort();
+    saveRun = null;
     backend?.close();
     backend = null;
   });

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/memory",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "Persistent cross-session memory on MemPalace (auto-installed): daemon-routed writes, shared palace with other agents, for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -42,8 +42,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2",
-    "@pi-unipi/info-screen": "3.0.0-alpha.2",
+    "@pi-unipi/core": "3.0.0-alpha.21",
+    "@pi-unipi/info-screen": "3.0.0-alpha.21",
     "js-yaml": "^4.1.0"
   },
   "peerDependencies": {

package/packages/memory/save-session.ts

@@ -0,0 +1,264 @@
+/**
+ * @unipi/memory — background save session (saveMode "side")
+ *
+ * On agent_end a one-shot AgentSession is seeded from the main session's
+ * current branch (SessionManager.inMemory — the same path /unipi:btw uses)
+ * and asked to store anything durable. Nothing reaches the main context:
+ * no sendMessage, only a UI-only appendEntry card when something was stored.
+ *
+ * Prefix-cache parity is the point: same model, same thinking level, the
+ * verbatim system prompt (ctx.getSystemPrompt(), no appends, no stripping),
+ * and the same tool list — every ACTIVE tool is re-exposed as a customTools
+ * stub carrying the identical name/description/parameters from
+ * pi.getAllTools(). Non-memory stubs refuse; the memory tools call the real
+ * executors from tools.ts.
+ */
+
+import {
+  createAgentSession,
+  createExtensionRuntime,
+  SessionManager,
+  type AgentSession,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type FileEntry,
+  type ModelRuntime,
+  type ResourceLoader,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { SessionBackend } from "./session.js";
+import { MEMORY_TOOLS, memoryExecutors } from "./tools.js";
+
+export const SAVE_CARD_TYPE = "unipi-memory-save-card";
+export const SAVE_PROMPT =
+  "Memory save pass. Review the task that just finished in this conversation. " +
+  "If you learned something non-obvious and durable (decision, pitfall + fix, project pattern, user preference), " +
+  "call memory_search to check for an existing memory, then memory_store (update rather than duplicate). " +
+  "If nothing qualifies, reply exactly NONE. Do not call any other tool.";
+
+const MAX_SAVE_TOOL_CALLS = 8;
+
+export interface SaveUsage {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+  output: number;
+}
+
+export interface MemorySaveOutcome {
+  /** Titles stored or updated during the pass. */
+  stored: string[];
+  /** Summed usage across the side session's assistant messages. */
+  usage?: SaveUsage;
+  error?: string;
+}
+
+export interface MemorySaveRun {
+  abort(): void;
+  finished: Promise<MemorySaveOutcome>;
+}
+
+/** Whether a finished main-session run qualifies for the background save pass. */
+export function shouldRunSideSave(input: {
+  write: boolean;
+  writeOverride?: boolean;
+  hooksEnabled: boolean;
+  storeActive: boolean;
+  /** Tool calls in the run that just ended (all tools). */
+  runToolCalls: number;
+  /** Any edit/write in the run that just ended. */
+  runHadWrite: boolean;
+  /** The main agent stored/deleted a memory itself during the run. */
+  runStoredMemory: boolean;
+  /** A save session is already in flight. */
+  running: boolean;
+}): boolean {
+  if (!input.write || input.writeOverride === false) return false;
+  if (!input.hooksEnabled) return false;
+  if (!input.storeActive) return false;
+  if (input.runStoredMemory) return false;
+  if (input.runToolCalls < 3 && !input.runHadWrite) return false;
+  if (input.running) return false; // one at a time — skip, never queue
+  return true;
+}
+
+/** Tool names that reach the real implementations inside the save session.
+ *  memory_delete stays a stub: a background pass may add knowledge, never
+ *  remove it. */
+const REAL_MEMORY_EXECUTES = new Set<string>([
+  MEMORY_TOOLS.STORE,
+  MEMORY_TOOLS.SEARCH,
+  MEMORY_TOOLS.LIST,
+  MEMORY_TOOLS.GLOBAL_SEARCH,
+  MEMORY_TOOLS.GLOBAL_LIST,
+]);
+
+const STUB_REFUSAL = "Not available in the memory save session.";
+
+/**
+ * customTools mirroring the main session's active tools: identical names,
+ * descriptions and parameter schemas so the serialized request prefix matches
+ * what the main agent just sent. Order follows pi.getAllTools() (builtins keep
+ * their positions — a same-named customTool overrides in place).
+ */
+export function buildSaveTools(
+  pi: Pick<ExtensionAPI, "getAllTools" | "getActiveTools">,
+  backend: () => SessionBackend | null,
+  onStored?: (title: string) => void,
+): ToolDefinition[] {
+  const active = new Set(pi.getActiveTools());
+  const ex = memoryExecutors(pi as never, backend);
+  const real = (name: string) => {
+    switch (name) {
+      case MEMORY_TOOLS.STORE:
+        return async (_id: string, params: { title: string; content: string; tags?: string[]; type?: string }, _s: unknown, _o: unknown, ctx: { cwd: string }) => {
+          const res = await ex.store(params, ctx);
+          const action = (res.details as { action?: string } | undefined)?.action;
+          if (action === "created" || action === "updated") onStored?.(params.title);
+          return res;
+        };
+      case MEMORY_TOOLS.SEARCH:
+        return async (_id: string, params: { query: string; limit?: number; scope?: string }) => ex.search(params);
+      case MEMORY_TOOLS.GLOBAL_SEARCH:
+        return async (_id: string, params: { query: string; limit?: number }) =>
+          ex.search({ query: params.query, limit: params.limit, scope: "all" });
+      case MEMORY_TOOLS.LIST:
+        return async () => ex.list();
+      case MEMORY_TOOLS.GLOBAL_LIST:
+        return async () => ex.globalList();
+      default:
+        return undefined;
+    }
+  };
+  return pi
+    .getAllTools()
+    .filter((info) => active.has(info.name))
+    .map(
+      (info): ToolDefinition => ({
+        name: info.name,
+        label: info.name,
+        description: info.description,
+        promptGuidelines: info.promptGuidelines,
+        parameters: info.parameters,
+        execute:
+          real(info.name) ??
+          (async () => ({
+            content: [{ type: "text" as const, text: STUB_REFUSAL }],
+            details: {},
+          })),
+      }),
+    );
+}
+
+/** Header + current branch, verbatim — the seeded side session sees exactly
+ *  the context the main agent just worked in (max prefix overlap). */
+export function buildSeedEntries(ctx: {
+  sessionManager: {
+    getHeader(): { type: string } | null;
+    getBranch(): Array<{ type: string; customType?: string }>;
+  };
+}): FileEntry[] {
+  const header = ctx.sessionManager.getHeader();
+  const branch = ctx.sessionManager.getBranch();
+  return header
+    ? [header as FileEntry, ...(branch as FileEntry[])]
+    : (branch as FileEntry[]);
+}
+
+/** Identical system prompt to the main session — no append, no stripping. */
+function createSaveResourceLoader(ctx: ExtensionContext): ResourceLoader {
+  const extensionsResult = { extensions: [], errors: [], runtime: createExtensionRuntime() };
+  const systemPrompt = ctx.getSystemPrompt();
+  return {
+    getExtensions: () => extensionsResult,
+    getSkills: () => ({ skills: [], diagnostics: [] }),
+    getPrompts: () => ({ prompts: [], diagnostics: [] }),
+    getThemes: () => ({ themes: [], diagnostics: [] }),
+    getAgentsFiles: () => ({ agentsFiles: [] }),
+    getSystemPrompt: () => systemPrompt,
+    getSystemPromptSource: () => undefined,
+    getAppendSystemPrompt: () => [],
+    getAppendSystemPromptSources: () => [],
+    extendResources: () => {},
+    reload: async () => {},
+  };
+}
+
+function sumUsage(session: AgentSession): SaveUsage | undefined {
+  let usage: SaveUsage | undefined;
+  for (const message of session.state.messages) {
+    if (message.role !== "assistant") continue;
+    const u = (message as AssistantMessage).usage;
+    if (!u) continue;
+    usage ??= { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+    usage.input += u.input;
+    usage.cacheRead += u.cacheRead;
+    usage.cacheWrite += u.cacheWrite;
+    usage.output += u.output;
+  }
+  return usage;
+}
+
+/**
+ * Start the background save pass. Caller owns gating (shouldRunSideSave) and
+ * the one-at-a-time check — this just runs.
+ */
+export function startMemorySave(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  backend: () => SessionBackend | null,
+): MemorySaveRun {
+  let session: AgentSession | null = null;
+  const stored: string[] = [];
+
+  const finished = (async (): Promise<MemorySaveOutcome> => {
+    const model = ctx.model;
+    if (!model) return { stored, error: "no active model" };
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok || !auth.apiKey) {
+      return { stored, error: auth.ok ? "no credentials" : (auth.error ?? "no credentials") };
+    }
+    try {
+      const seeded = await createAgentSession({
+        sessionManager: SessionManager.inMemory(ctx.cwd, undefined, buildSeedEntries(ctx)),
+        model,
+        modelRuntime: (ctx.modelRegistry as unknown as { runtime: ModelRuntime }).runtime,
+        thinkingLevel: ctx.thinkingLevel ?? pi.getThinkingLevel(),
+        customTools: buildSaveTools(pi, backend, (title) => stored.push(title)),
+        tools: pi.getActiveTools(),
+        resourceLoader: createSaveResourceLoader(ctx),
+      });
+      session = seeded.session;
+      let toolCalls = 0;
+      const unsubscribe = session.subscribe((event) => {
+        if (event.type === "tool_execution_start") {
+          toolCalls += 1;
+          if (toolCalls >= MAX_SAVE_TOOL_CALLS) void session?.abort().catch(() => {});
+        }
+      });
+      try {
+        await session.prompt(SAVE_PROMPT, { source: "extension" });
+      } finally {
+        unsubscribe();
+      }
+      return { stored, usage: sumUsage(session) };
+    } catch (error) {
+      return { stored, error: error instanceof Error ? error.message : String(error) };
+    } finally {
+      try {
+        session?.dispose();
+      } catch {
+        /* already disposed */
+      }
+      session = null;
+    }
+  })();
+
+  return {
+    abort() {
+      void session?.abort().catch(() => {});
+    },
+    finished,
+  };
+}

package/packages/memory/settings.ts

@@ -18,6 +18,9 @@ export interface MemoryConfig {
   write: boolean;
   /** Include `mempalace wake-up` output in the start reminder. */
   wakeUp: boolean;
+  /** How the end-of-task save happens: a background side session, the inline
+   *  nextTurn reminder, or nothing. */
+  saveMode: "side" | "reminder" | "off";
   /** Start the MemPalace daemon automatically when it isn't running. */
   autoStartDaemon: boolean;
   /** Keep the MemPalace install current via a daily PyPI check + uv upgrade. */
@@ -28,6 +31,7 @@ export const DEFAULT_MEMORY_CONFIG: MemoryConfig = {
   recallAtStart: true,
   write: true,
   wakeUp: true,
+  saveMode: "side",
   autoStartDaemon: false,
   mempalaceAutoUpdate: true,
 };
@@ -58,6 +62,19 @@ registerSettings({
           label: "Wake-up summary at start",
           description: "Include `mempalace wake-up --wing <project>` output in the start reminder.",
         },
+        {
+          key: "saveMode",
+          type: "enum",
+          label: "Save mode",
+          description:
+            "side: a background side session reviews the finished run and stores what's worth keeping (nothing enters the conversation). " +
+            "reminder: an end-of-task note asks the agent to save. off: no save pass at all.",
+          options: [
+            { value: "side", label: "side agent" },
+            { value: "reminder", label: "reminder" },
+            { value: "off", label: "off" },
+          ],
+        },
         {
           key: "autoStartDaemon",
           type: "boolean",