wave-agent-sdk 1.1.5 → 1.3.0

package/dist/managers/slashCommandManager.js

@@ -9,39 +9,14 @@ export class SlashCommandManager {
         this.commands = new Map();
         this.customCommands = new Map();
         this.skillCommandIds = new Set();
+        /** Ids registered by plugins, so they can be dropped per-plugin and are not
+         * mistaken for disk-sourced custom commands. */
+        this.pluginCommandIds = new Set();
         this.currentCommandAbortController = null;
         this.workdir = options.workdir;
     }
     initialize() {
         this.loadCustomCommands();
-        // Builtin /subtask: manual fork subagent (aligned with Claude Code's
-        // /subtask — inherits the parent's full context, runs in the background,
-        // result returns to the main conversation via a task notification).
-        this.registerCommand({
-            id: "subtask",
-            name: "subtask",
-            description: "Start a fork subagent with the current conversation context in the background",
-            handler: async (args, signal) => {
-                const taskDescription = args?.trim();
-                if (!taskDescription) {
-                    this.messageManager.addErrorBlock("Usage: /subtask <task description>");
-                    return;
-                }
-                try {
-                    // The fork snapshots its context synchronously on entry, so the
-                    // transcript echo below never duplicates the prompt inside the fork.
-                    await this.aiManager.runForkSubagent(taskDescription, { description: taskDescription }, signal);
-                    this.messageManager.addUserMessage({
-                        content: `/subtask ${taskDescription}`,
-                    });
-                }
-                catch (error) {
-                    this.aiManager.setIsLoading(false);
-                    logger?.error("Failed to execute /subtask:", error);
-                    this.messageManager.addErrorBlock(`Failed to execute /subtask: ${error instanceof Error ? error.message : String(error)}`);
-                }
-            },
-        });
         // Listen for skill refreshes and update skill commands
         const skillManager = this.container.get("SkillManager");
         if (skillManager) {
@@ -103,6 +78,13 @@ export class SlashCommandManager {
             this.unregisterCommand(commandId);
         }
         this.skillCommandIds.clear();
+        const skillSourceFor = (skill) => {
+            if (skill.pluginName)
+                return "plugin";
+            if (skill.type === "personal")
+                return "user";
+            return skill.type; // "project" | "builtin"
+        };
         for (const skill of skills) {
             if (skill.userInvocable === false) {
                 continue;
@@ -113,6 +95,8 @@ export class SlashCommandManager {
                 id: commandId,
                 name: skill.name,
                 description: `Skill: ${skill.description}`,
+                // UI source tag: plugin skills carry pluginName; personal → 用户
+                skillSource: skillSourceFor(skill),
                 handler: async (args, signal) => {
                     try {
                         // 1. Prepare skill content immediately
@@ -252,6 +236,7 @@ export class SlashCommandManager {
             const namespacedId = `${pluginName}:${command.id}`;
             const namespacedName = `${pluginName}:${command.name}`;
             this.customCommands.set(namespacedId, command);
+            this.pluginCommandIds.add(namespacedId);
             // Generate description: prioritize custom description, otherwise use default description
             const description = command.description ||
                 `Plugin command: ${namespacedName}${hasParameterPlaceholders(command.content) ? " (supports parameters)" : ""}`;
@@ -271,15 +256,43 @@ export class SlashCommandManager {
         }
         logger?.debug(`Registered ${commands.length} commands from plugin '${pluginName}'`);
     }
+    /**
+     * Drop every slash command contributed by a plugin, addressed by its plugin
+     * name. Removes the registry entry and the customCommands source entry.
+     * Called by the in-place plugin reload path before re-registering.
+     * @returns the number of commands removed
+     */
+    unregisterPluginCommands(pluginName) {
+        const prefix = `${pluginName}:`;
+        let removed = 0;
+        for (const commandId of Array.from(this.pluginCommandIds)) {
+            if (!commandId.startsWith(prefix)) {
+                continue;
+            }
+            this.pluginCommandIds.delete(commandId);
+            this.customCommands.delete(commandId);
+            this.unregisterCommand(commandId);
+            removed += 1;
+        }
+        if (removed > 0) {
+            logger?.debug(`Unregistered ${removed} commands from plugin '${pluginName}'`);
+        }
+        return removed;
+    }
     /**
      * Reload custom commands (useful for development)
      */
     reloadCustomCommands() {
-        // Clear existing custom commands
-        for (const commandId of this.customCommands.keys()) {
+        // Reload only disk-sourced custom commands. Plugin commands live in the
+        // same map but are owned by the plugin lifecycle, so re-reading the disk
+        // must not drop them.
+        for (const [commandId] of this.customCommands) {
+            if (this.pluginCommandIds.has(commandId)) {
+                continue;
+            }
             this.unregisterCommand(commandId);
+            this.customCommands.delete(commandId);
         }
-        this.customCommands.clear();
         // Reload
         this.loadCustomCommands();
     }

package/dist/managers/subagentManager.d.ts

@@ -100,6 +100,13 @@ export declare class SubagentManager {
      * for conditional subagent registration (e.g. WAVE_VISION_MODEL).
      */
     private getMergedEnv;
+    /**
+     * Delete a user-level or project-level subagent by removing its markdown
+     * file. Builtin and plugin agents are read-only and cannot be deleted.
+     * @param name - The subagent name as shown in configurations
+     * @returns true if the subagent was deleted
+     */
+    deleteSubagent(name: string): Promise<boolean>;
     /**
      * Get cached configurations synchronously (must call loadConfigurations first)
      */
@@ -113,6 +120,14 @@ export declare class SubagentManager {
      * Names each agent as `pluginName:agentName` to avoid collisions.
      */
     registerPluginAgents(pluginName: string, agents: SubagentConfiguration[]): void;
+    /**
+     * Drop every subagent contributed by a plugin, addressed by its plugin name.
+     * Running instances are deliberately left alone — an in-place reload must not
+     * interrupt work already in flight. Called by the plugin reload path before
+     * re-registering.
+     * @returns the number of configurations removed
+     */
+    unregisterPluginAgents(pluginName: string): number;
     /**
      * Create a new subagent instance with isolated managers
      */

package/dist/managers/subagentManager.js

@@ -107,6 +107,31 @@ export class SubagentManager {
         return (this.configurationService?.getMergedEnv?.() ??
             process.env);
     }
+    /**
+     * Delete a user-level or project-level subagent by removing its markdown
+     * file. Builtin and plugin agents are read-only and cannot be deleted.
+     * @param name - The subagent name as shown in configurations
+     * @returns true if the subagent was deleted
+     */
+    async deleteSubagent(name) {
+        const configs = this.cachedConfigurations ?? [];
+        const config = configs.find((c) => c.name === name);
+        if (!config) {
+            return false;
+        }
+        // Builtin and plugin agents are read-only
+        if (config.scope !== "user" && config.scope !== "project") {
+            return false;
+        }
+        const { unlink } = await import("fs/promises");
+        await unlink(config.filePath);
+        // Drop the deleted agent from the cached configurations immediately.
+        // A later refreshConfigurations() re-scans the filesystem and reflects
+        // the deletion persistently.
+        this.cachedConfigurations = configs.filter((c) => c.name !== name);
+        logger?.debug(`Deleted subagent '${name}' at ${config.filePath}`);
+        return true;
+    }
     /**
      * Get cached configurations synchronously (must call loadConfigurations first)
      */
@@ -158,6 +183,22 @@ export class SubagentManager {
             return a.name.localeCompare(b.name);
         });
     }
+    /**
+     * Drop every subagent contributed by a plugin, addressed by its plugin name.
+     * Running instances are deliberately left alone — an in-place reload must not
+     * interrupt work already in flight. Called by the plugin reload path before
+     * re-registering.
+     * @returns the number of configurations removed
+     */
+    unregisterPluginAgents(pluginName) {
+        if (this.cachedConfigurations === null) {
+            return 0;
+        }
+        const prefix = `${pluginName}:`;
+        const before = this.cachedConfigurations.length;
+        this.cachedConfigurations = this.cachedConfigurations.filter((config) => !config.name.startsWith(prefix));
+        return before - this.cachedConfigurations.length;
+    }
     /**
      * Create a new subagent instance with isolated managers
      */
@@ -207,6 +248,10 @@ export class SubagentManager {
         const subagentPermissionManager = new PermissionManager(subagentContainer, {
             configuredPermissionMode: parameters.permissionModeOverride ??
                 parentPermissionManager?.getConfiguredPermissionMode(),
+            // Inherit the parent session's bypass authorization: the subagent is
+            // created mid-session, so re-deriving it from its own mode would
+            // (wrongly) deny an authorized session's plan-mode subagent.
+            bypassAuthorization: parentPermissionManager?.getBypassAuthorization?.(),
             allowedRules: parentPermissionManager?.getAllowedRules(),
             deniedRules: parentPermissionManager?.getDeniedRules(),
             instanceAllowedRules: parentPermissionManager?.getInstanceAllowedRules?.(),
@@ -339,8 +384,13 @@ export class SubagentManager {
                         const result = await this.internalExecute(instance, prompt, abortSignal);
                         const task = backgroundTaskManager?.getTask(taskId);
                         if (task) {
-                            task.status = "completed";
-                            task.stdout = result;
+                            // internalExecute already recorded the terminal state; only fill
+                            // in a "completed" status when the task was not concurrently
+                            // killed (mirrors the catch branch below).
+                            if (task.status !== "killed") {
+                                task.status = "completed";
+                                task.stdout = result;
+                            }
                             task.endTime = Date.now();
                             task.runtime = task.endTime - startTime;
                         }
@@ -348,9 +398,13 @@ export class SubagentManager {
                     catch (error) {
                         const task = backgroundTaskManager?.getTask(taskId);
                         if (task) {
-                            task.status = "failed";
-                            task.stderr =
-                                error instanceof Error ? error.message : String(error);
+                            // Preserve a "killed" terminal state (internalExecute already
+                            // notified it) instead of flipping the in-map task to failed.
+                            if (task.status !== "killed") {
+                                task.status = "failed";
+                                task.stderr =
+                                    error instanceof Error ? error.message : String(error);
+                            }
                             task.endTime = Date.now();
                             task.runtime = task.endTime - startTime;
                         }
@@ -480,8 +534,13 @@ export class SubagentManager {
                 const task = backgroundTaskManager.getTask(instance.backgroundTaskId);
                 if (task) {
                     const wasAlreadyKilled = task.status === "killed";
-                    task.status = "completed";
-                    task.stdout = response || "Agent completed with no text response";
+                    // Preserve a "killed" terminal state (stopTask already notified it)
+                    // instead of overwriting it with "completed" — mirrors shell exit
+                    // semantics in BackgroundTaskManager.onExit.
+                    if (!wasAlreadyKilled) {
+                        task.status = "completed";
+                        task.stdout = response || "Agent completed with no text response";
+                    }
                     task.endTime = Date.now();
                     if (task.startTime) {
                         task.runtime = task.endTime - task.startTime;
@@ -496,6 +555,11 @@ export class SubagentManager {
                             messageQueue.enqueueNotification(`<task-notification>\n<task-id>${instance.backgroundTaskId}</task-id>\n<task-type>agent</task-type>\n<status>completed</status>\n<summary>${summary}</summary>\n</task-notification>`);
                         }
                     }
+                    // Push a terminal snapshot: SubagentManager mutates the task object in
+                    // place, so without an explicit notify the UI/hosts keep the last
+                    // snapshot — the task created with status "running" — and the IDE
+                    // background-task gate (new chat / history restore) stays locked.
+                    backgroundTaskManager.notifyTasksChange();
                 }
             }
             return response || "Agent completed with no text response";
@@ -512,12 +576,20 @@ export class SubagentManager {
                 const task = backgroundTaskManager.getTask(instance.backgroundTaskId);
                 if (task) {
                     const wasAlreadyKilled = task.status === "killed";
-                    task.status = "failed";
-                    task.stderr = error instanceof Error ? error.message : String(error);
+                    // Preserve a user/agent-initiated "killed" terminal state instead of
+                    // overwriting it with "failed" (mirrors shell exit semantics) — the
+                    // abort that stopped the task surfaces here as a thrown error.
+                    if (!wasAlreadyKilled) {
+                        task.status = "failed";
+                        task.stderr =
+                            error instanceof Error ? error.message : String(error);
+                    }
                     task.endTime = Date.now();
                     if (task.startTime) {
                         task.runtime = task.endTime - task.startTime;
                     }
+                    // Push a terminal snapshot (see the completion branch above).
+                    backgroundTaskManager.notifyTasksChange();
                     // Skip notification if task was already stopped (e.g. by main agent shutdown)
                     if (!wasAlreadyKilled) {
                         const messageQueue = this.container.has("MessageQueue")

package/dist/managers/toolManager.d.ts

@@ -1,4 +1,5 @@
 import type { ToolContext, ToolPlugin, ToolResult } from "../tools/types.js";
+import type { RenderedCatalog } from "../exec/catalog.js";
 import { PermissionManager } from "./permissionManager.js";
 import { ChatCompletionFunctionTool } from "openai/resources.js";
 import type { PermissionMode } from "../types/index.js";
@@ -56,15 +57,21 @@ declare class ToolManager {
     /**
      * Re-evaluate feature-gated built-in tools after a live configuration
      * reload. Currently gates the Artifact tool on settings.json
-     * `enableArtifact`. Safe to call multiple times: gated tools are removed
-     * from the registry first, then initializeBuiltInTools() re-registers them
-     * only if still enabled (so toggling the flag off actually unregisters).
+     * `enableArtifact` and the Exec tool on `enableExec`. Safe to call multiple
+     * times: gated tools are removed from the registry first, then
+     * initializeBuiltInTools() re-registers them only if still enabled (so
+     * toggling a flag off actually unregisters).
      */
     reloadFeatureGatedTools(): void;
     /**
      * Check if a tool should be enabled based on tools configuration and permission rules
      */
     private shouldEnableTool;
+    /**
+     * The auto-memory directory for this session, or undefined when the feature
+     * is off. Consumers (Read) treat "unset" as "not a memory file".
+     */
+    private resolveAutoMemoryDir;
     /**
      * Execute a tool by name with the provided arguments and context
      *
@@ -80,6 +87,25 @@ declare class ToolManager {
      */
     execute(name: string, args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
     list(): ToolPlugin[];
+    /**
+     * Whether `Exec` is declared at all: registered and not denied. Exactly when the
+     * catalog channel is open — an undeclared `Exec` cannot be called, so a catalog
+     * for it would advertise a way in that does not exist.
+     */
+    private isExecDeclared;
+    /** The tools the sandbox may reach — the pool the flat declarations give up. */
+    private execPool;
+    /**
+     * The MCP catalog as the model is meant to see it, or `undefined` when the
+     * catalog channel is closed.
+     *
+     * A function of the pool alone, and computed per call: with the catalog out of
+     * `tools[]` the declaration no longer moves when a server comes or goes, and the
+     * announcement channel diffs this against the history. Caching the rendering would
+     * mean caching pool state, which is exactly the process-side bookkeeping the
+     * channel is built to avoid.
+     */
+    getExecCatalog(): RenderedCatalog | undefined;
     getToolsConfig(options?: {
         availableSubagents?: SubagentConfiguration[];
         availableSkills?: SkillMetadata[];

package/dist/managers/toolManager.js

@@ -10,7 +10,12 @@ import { cronDeleteTool } from "../tools/cronDeleteTool.js";
 import { cronListTool } from "../tools/cronListTool.js";
 import { webFetchTool } from "../tools/webFetchTool.js";
 import { artifactTool } from "../tools/artifactTool.js";
+import { execTool } from "../tools/execTool.js";
 import { isArtifactEnabled } from "../services/artifactAvailability.js";
+import { isExecEnabled } from "../services/execAvailability.js";
+import { buildExecPool, renderCatalog } from "../exec/catalog.js";
+import { EXEC_DEFAULT_CATALOG_TOKENS } from "../exec/constants.js";
+import { EXEC_TOOL_NAME } from "../constants/tools.js";
 // New tools
 import { globTool } from "../tools/globTool.js";
 import { grepTool } from "../tools/grepTool.js";
@@ -102,6 +107,13 @@ class ToolManager {
         if (isArtifactEnabled(this.container.get("Workdir"))) {
             builtInTools.push(artifactTool);
         }
+        // Exec is on by default; enableExec: false restores flat MCP declarations.
+        // Registration is decoupled from declaration: getToolsConfig() only declares
+        // it (and only then collapses the MCP pool) once MCP servers have connected
+        // and yielded a non-empty pool, which cannot be known until then.
+        if (isExecEnabled(this.container.get("Workdir"))) {
+            builtInTools.push(execTool);
+        }
         for (const tool of builtInTools) {
             if (this.shouldEnableTool(tool.name)) {
                 this.toolsRegistry.set(tool.name, tool);
@@ -117,12 +129,14 @@ class ToolManager {
     /**
      * Re-evaluate feature-gated built-in tools after a live configuration
      * reload. Currently gates the Artifact tool on settings.json
-     * `enableArtifact`. Safe to call multiple times: gated tools are removed
-     * from the registry first, then initializeBuiltInTools() re-registers them
-     * only if still enabled (so toggling the flag off actually unregisters).
+     * `enableArtifact` and the Exec tool on `enableExec`. Safe to call multiple
+     * times: gated tools are removed from the registry first, then
+     * initializeBuiltInTools() re-registers them only if still enabled (so
+     * toggling a flag off actually unregisters).
      */
     reloadFeatureGatedTools() {
         this.toolsRegistry.delete(artifactTool.name);
+        this.toolsRegistry.delete(execTool.name);
         this.initializeBuiltInTools();
     }
     /**
@@ -139,6 +153,22 @@ class ToolManager {
         }
         return this.tools.some((toolName) => toolName.toLowerCase() === name.toLowerCase());
     }
+    /**
+     * The auto-memory directory for this session, or undefined when the feature
+     * is off. Consumers (Read) treat "unset" as "not a memory file".
+     */
+    resolveAutoMemoryDir(workdir) {
+        if (!this.container.has("MemoryService"))
+            return undefined;
+        const configuration = this.container.has("ConfigurationService")
+            ? this.container.get("ConfigurationService")
+            : undefined;
+        if (!configuration?.resolveAutoMemoryEnabled?.())
+            return undefined;
+        return this.container
+            .get("MemoryService")
+            ?.getAutoMemoryDirectory?.(workdir);
+    }
     /**
      * Execute a tool by name with the provided arguments and context
      *
@@ -202,6 +232,7 @@ class ToolManager {
                     .get("ConfigurationService")
                     ?.getMergedEnv?.()
                 : undefined,
+            autoMemoryDir: this.resolveAutoMemoryDir(context.workdir),
             sessionId: context.sessionId,
             toolCallId: context.toolCallId,
         };
@@ -287,10 +318,53 @@ class ToolManager {
             .filter((tool) => !permissionManager?.isToolDenied(tool.name));
         return [...builtInTools, ...mcpTools];
     }
+    /**
+     * Whether `Exec` is declared at all: registered and not denied. Exactly when the
+     * catalog channel is open — an undeclared `Exec` cannot be called, so a catalog
+     * for it would advertise a way in that does not exist.
+     */
+    isExecDeclared() {
+        return (this.toolsRegistry.has(EXEC_TOOL_NAME) &&
+            !this.getPermissionManager()?.isToolDenied(EXEC_TOOL_NAME));
+    }
+    /** The tools the sandbox may reach — the pool the flat declarations give up. */
+    execPool() {
+        return buildExecPool(this.mcpManager, this.getPermissionManager());
+    }
+    /**
+     * The MCP catalog as the model is meant to see it, or `undefined` when the
+     * catalog channel is closed.
+     *
+     * A function of the pool alone, and computed per call: with the catalog out of
+     * `tools[]` the declaration no longer moves when a server comes or goes, and the
+     * announcement channel diffs this against the history. Caching the rendering would
+     * mean caching pool state, which is exactly the process-side bookkeeping the
+     * channel is built to avoid.
+     */
+    getExecCatalog() {
+        if (!this.isExecDeclared())
+            return undefined;
+        return renderCatalog(this.execPool(), EXEC_DEFAULT_CATALOG_TOKENS);
+    }
     getToolsConfig(options) {
-        const permissionManager = this.container.get("PermissionManager");
+        const permissionManager = this.getPermissionManager();
+        // Exec either replaces the flat MCP declarations or is absent: the two must
+        // never coexist, or the model would see the same tool twice while the
+        // catalog claimed to be the only way in. Both halves are derived from the
+        // same pool, and the pool is exactly what the agent could already call
+        // directly, so collapsing it cannot widen access.
+        const execPool = this.execPool();
+        // No minimum pool size: any catalogable tool collapses the pool, matching
+        // opencode. The switch (`enableExec`), not a count, decides whether Exec is
+        // used at all.
+        const collapseMcp = this.isExecDeclared() && execPool.length > 0;
         const builtInToolsConfig = Array.from(this.toolsRegistry.values())
             .filter((tool) => {
+            // With an empty pool there is nothing to collapse, so Exec stays
+            // registered but undeclared rather than declaring an empty catalog.
+            if (tool.name === EXEC_TOOL_NAME && !collapseMcp) {
+                return false;
+            }
             // If tool is explicitly denied by name in permission rules, filter it out
             if (permissionManager?.isToolDenied(tool.name)) {
                 return false;
@@ -307,18 +381,18 @@ class ToolManager {
             };
             // Override description with prompt if available
             if (tool.prompt) {
-                config.function.description = tool.prompt(options);
+                config.function.description = tool.prompt({ ...options });
             }
             return config;
         });
-        const mcpToolsConfig = this.mcpManager
-            .getMcpToolsConfig()
-            .filter((tool) => {
-            if (permissionManager?.isToolDenied(tool.function.name)) {
-                return false;
-            }
-            return true;
-        });
+        const mcpToolsConfig = collapseMcp
+            ? []
+            : this.mcpManager.getMcpToolsConfig().filter((tool) => {
+                if (permissionManager?.isToolDenied(tool.function.name)) {
+                    return false;
+                }
+                return true;
+            });
         return [...builtInToolsConfig, ...mcpToolsConfig];
     }
     /**

package/dist/managers/workflowManager.js

@@ -207,6 +207,10 @@ export class WorkflowManager {
                     task.status = "completed";
                     task.endTime = Date.now();
                 }
+                // Push the terminal snapshot: without it the last snapshot holds the
+                // "running" registration and UI consumers (background-task gate) never
+                // see the workflow finish.
+                this.backgroundTaskManager.notifyTasksChange();
                 // Enqueue completion notification
                 const journalPath = journal.filePath;
                 this.messageQueue.enqueueNotification(taskNotificationToXml({
@@ -244,6 +248,8 @@ export class WorkflowManager {
                     task.stderr = run.error || "";
                     task.endTime = Date.now();
                 }
+                // Push the terminal snapshot (see the completion branch above).
+                this.backgroundTaskManager.notifyTasksChange();
                 this.messageQueue.enqueueNotification(taskNotificationToXml({
                     type: "task_notification",
                     taskId: runId,

package/dist/prompts/autoMemory.d.ts

@@ -1 +1,10 @@
+/**
+ * Build the main agent's auto-memory prompt. The section order mirrors Claude
+ * Code's `buildMemoryLines()` (individual-only variant). The index content of
+ * `MEMORY.md` is appended separately by the system prompt builder, so this
+ * function only produces the behavioral instructions.
+ *
+ * Every section except the directory line is shared with the extraction fork
+ * prompt (`autoMemoryExtraction.ts`) — see `memoryTypes.ts` for why.
+ */
 export declare function buildAutoMemoryPrompt(memoryDir: string): string;

package/dist/prompts/autoMemory.js

@@ -1,33 +1,32 @@
+import { DIR_EXISTS_GUIDANCE, MEMORY_AND_OTHER_PERSISTENCE_SECTION, TYPES_SECTION, TRUSTING_RECALL_SECTION, WHAT_NOT_TO_SAVE_SECTION, WHEN_TO_ACCESS_SECTION, buildHowToSaveSection, } from "./memoryTypes.js";
+/**
+ * Build the main agent's auto-memory prompt. The section order mirrors Claude
+ * Code's `buildMemoryLines()` (individual-only variant). The index content of
+ * `MEMORY.md` is appended separately by the system prompt builder, so this
+ * function only produces the behavioral instructions.
+ *
+ * Every section except the directory line is shared with the extraction fork
+ * prompt (`autoMemoryExtraction.ts`) — see `memoryTypes.ts` for why.
+ */
 export function buildAutoMemoryPrompt(memoryDir) {
-    return `
-# auto memory
-
-You have a persistent auto memory directory at \`${memoryDir}\`. Its contents persist across conversations.
-
-As you work, consult your memory files to build on previous experience.
-
-## How to save memories:
-- Organize memory semantically by topic, not chronologically
-- Use the Write and Edit tools to update your memory files
-- \`MEMORY.md\` is always loaded into your conversation context — lines after 200 will be truncated, so keep it concise
-- Create separate topic files (e.g., \`debugging.md\`, \`patterns.md\`) for detailed notes and link to them from MEMORY.md
-- Update or remove memories that turn out to be wrong or outdated
-- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.
-
-## What to save:
-- Stable patterns and conventions confirmed across multiple interactions
-- Key architectural decisions, important file paths, and project structure
-- User preferences for workflow, tools, and communication style
-- Solutions to recurring problems and debugging insights
-
-## What NOT to save:
-- Session-specific context (current task details, in-progress work, temporary state)
-- Information that might be incomplete — verify against project docs before writing
-- Anything that duplicates or contradicts existing AGENTS.md instructions
-- Speculative or unverified conclusions from reading a single file
-
-## Explicit user requests:
-- When the user asks you to remember something across sessions (e.g., "always use bun", "never auto-commit"), save it — no need to wait for multiple interactions
-- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files
-`;
+    return [
+        "# auto memory",
+        "",
+        `You have a persistent, file-based memory system at \`${memoryDir}\`. ${DIR_EXISTS_GUIDANCE}`,
+        "",
+        "You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.",
+        "",
+        "If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.",
+        "",
+        ...TYPES_SECTION,
+        ...WHAT_NOT_TO_SAVE_SECTION,
+        "",
+        ...buildHowToSaveSection(),
+        "",
+        ...WHEN_TO_ACCESS_SECTION,
+        "",
+        ...TRUSTING_RECALL_SECTION,
+        "",
+        ...MEMORY_AND_OTHER_PERSISTENCE_SECTION,
+    ].join("\n");
 }

package/dist/prompts/autoMemoryExtraction.d.ts

@@ -1,4 +1,8 @@
 /**
  * Build the auto-memory extraction prompt for the background agent.
+ *
+ * The taxonomy, the "what not to save" list, and the save procedure are shared
+ * with the main agent's memory prompt (`memoryTypes.ts`): the fork reuses the
+ * main system prompt, so both texts are in the same request.
  */
 export declare function buildAutoMemoryExtractionPrompt(newMessageCount: number, existingMemoriesManifest: string): string;