feat(core): add experimental memory manager agent to replace save_memory tool

Add experimental.memoryManager flag that, when enabled, replaces the
built-in save_memory tool with a memory manager subagent. The subagent
supports adding, removing, de-duplicating, and organizing memories
across both global (~/.gemini/GEMINI.md) and project-level GEMINI.md
files.

Users can override the agent by placing a custom save_memory.md in
~/.gemini/agents/ or .gemini/agents/.

Author: SandyTao520

docs/cli/settings.md

@@ -152,6 +152,7 @@ they appear in the UI.
 | Plan                       | `experimental.plan`                      | Enable Plan Mode.                                                                                                                                         | `true`  |
 | Model Steering             | `experimental.modelSteering`             | Enable model steering (user hints) to guide the model during tool execution.                                                                              | `false` |
 | Direct Web Fetch           | `experimental.directWebFetch`            | Enable web fetch behavior that bypasses LLM summarization.                                                                                                | `false` |
+| Memory Manager Agent       | `experimental.memoryManager`             | Replace the built-in save_memory tool with a memory manager subagent that supports adding, removing, de-duplicating, and organizing memories.             | `false` |
 | Topic & Update Narration   | `experimental.topicUpdateNarration`      | Enable the experimental Topic & Update communication model for reduced chattiness and structured progress reporting.                                      | `false` |
 
 ### Skills

docs/reference/configuration.md

@@ -1249,6 +1249,13 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `"gemma3-1b-gpu-custom"`
   - **Requires restart:** Yes
 
+- **`experimental.memoryManager`** (boolean):
+  - **Description:** Replace the built-in save_memory tool with a memory manager
+    subagent that supports adding, removing, de-duplicating, and organizing
+    memories.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 - **`experimental.topicUpdateNarration`** (boolean):
   - **Description:** Enable the experimental Topic & Update communication model
     for reduced chattiness and structured progress reporting.

packages/cli/src/config/config.ts

@@ -813,6 +813,7 @@ export async function loadCliConfig(
     skillsSupport: settings.skills?.enabled ?? true,
     disabledSkills: settings.skills?.disabled,
     experimentalJitContext: settings.experimental?.jitContext,
+    experimentalMemoryManager: settings.experimental?.memoryManager,
     modelSteering: settings.experimental?.modelSteering,
     topicUpdateNarration: settings.experimental?.topicUpdateNarration,
     toolOutputMasking: settings.experimental?.toolOutputMasking,

packages/cli/src/config/settingsSchema.ts

@@ -2018,6 +2018,16 @@ const SETTINGS_SCHEMA = {
           },
         },
       },
+      memoryManager: {
+        type: 'boolean',
+        label: 'Memory Manager Agent',
+        category: 'Experimental',
+        requiresRestart: true,
+        default: false,
+        description:
+          'Replace the built-in save_memory tool with a memory manager subagent that supports adding, removing, de-duplicating, and organizing memories.',
+        showInDialog: true,
+      },
       topicUpdateNarration: {
         type: 'boolean',
         label: 'Topic & Update Narration',

packages/core/src/agents/memory-manager-agent.test.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { MemoryManagerAgent } from './memory-manager-agent.js';
+
+describe('MemoryManagerAgent', () => {
+  it('should have the correct name "save_memory"', () => {
+    const agent = MemoryManagerAgent();
+    expect(agent.name).toBe('save_memory');
+  });
+
+  it('should be a local agent', () => {
+    const agent = MemoryManagerAgent();
+    expect(agent.kind).toBe('local');
+  });
+
+  it('should have a description', () => {
+    const agent = MemoryManagerAgent();
+    expect(agent.description).toBeTruthy();
+    expect(agent.description).toContain('memory');
+  });
+
+  it('should have a system prompt with memory management instructions', () => {
+    const agent = MemoryManagerAgent();
+    const prompt = agent.promptConfig.systemPrompt;
+    expect(prompt).toContain('Global (~/.gemini/)');
+    expect(prompt).toContain('Project (.gemini/)');
+    expect(prompt).toContain('Table of Contents');
+    expect(prompt).toContain('De-duplicating');
+    expect(prompt).toContain('Adding');
+    expect(prompt).toContain('Removing stale');
+    expect(prompt).toContain('Organizing');
+    expect(prompt).toContain('Routing');
+  });
+
+  it('should have file-management and search tools', () => {
+    const agent = MemoryManagerAgent();
+    expect(agent.toolConfig).toBeDefined();
+    expect(agent.toolConfig!.tools).toEqual(
+      expect.arrayContaining([
+        'read_file',
+        'replace',
+        'write_file',
+        'grep_search',
+      ]),
+    );
+  });
+
+  it('should require a "request" input parameter', () => {
+    const agent = MemoryManagerAgent();
+    const schema = agent.inputConfig.inputSchema as Record<string, unknown>;
+    expect(schema).toBeDefined();
+    expect(schema['properties']).toHaveProperty('request');
+    expect(schema['required']).toContain('request');
+  });
+
+  it('should inherit the model from the parent agent', () => {
+    const agent = MemoryManagerAgent();
+    expect(agent.modelConfig.model).toBe('inherit');
+  });
+});

packages/core/src/agents/memory-manager-agent.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import type { LocalAgentDefinition } from './types.js';
+
+const MemoryManagerSchema = z.object({
+  response: z
+    .string()
+    .describe('A summary of the memory operations performed.'),
+});
+
+const MEMORY_MANAGER_SYSTEM_PROMPT = `
+You are a memory management agent. You maintain the user's memories stored in
+GEMINI.md files.
+
+# Memory Hierarchy
+
+## Global (~/.gemini/)
+- \`~/.gemini/GEMINI.md\` — Cross-project user preferences, key personal info,
+  and habits that apply everywhere.
+
+## Project (.gemini/)
+- \`.gemini/GEMINI.md\` — **Table of Contents** for project-specific context:
+  architecture decisions, conventions, key contacts, and references to
+  subdirectory GEMINI.md files for detailed context.
+- Subdirectory GEMINI.md files (e.g. \`src/GEMINI.md\`, \`docs/GEMINI.md\`) —
+  detailed, domain-specific context for that part of the project. Reference
+  these from the root \`.gemini/GEMINI.md\`.
+
+## Routing
+
+When adding a memory, route it to the right store:
+- User preferences, personal info, tool aliases, cross-project habits → **global**
+- Project architecture, conventions, workflows, team info → **project root**
+- Detailed context about a specific module or directory → **subdirectory
+  GEMINI.md**, with a reference added to the project root
+
+# Operations
+
+Always read the target file(s) before writing. When editing any memory file,
+use \`grep_search\` to scan related files for duplicates before finishing.
+
+1. **Adding** — Route to the correct store and file. Check for duplicates first.
+2. **Removing stale entries** — Delete outdated or unwanted entries. Clean up
+   dangling references.
+3. **De-duplicating** — Search across related memory files for semantically
+   equivalent entries. Keep the most informative version.
+4. **Organizing** — Restructure for clarity. Update references between files.
+
+# Guidelines
+
+- Keep GEMINI.md files lean — they are loaded into context every session.
+- Keep entries concise.
+- Edit surgically — preserve existing structure and user-authored content.
+- Always read before write to avoid overwriting concurrent changes.
+`.trim();
+
+/**
+ * A memory management agent that replaces the built-in save_memory tool.
+ * It provides richer memory operations: adding, removing, de-duplicating,
+ * and organizing memories in the global GEMINI.md file.
+ *
+ * Users can override this agent by placing a custom save_memory.md
+ * in ~/.gemini/agents/ or .gemini/agents/.
+ */
+export const MemoryManagerAgent = (): LocalAgentDefinition<
+  typeof MemoryManagerSchema
+> => ({
+  kind: 'local',
+  name: 'save_memory',
+  displayName: 'Memory Manager',
+  description:
+    'Manages the global memory file (~/.gemini/GEMINI.md). Use this agent to add, remove, de-duplicate, and organize persistent user memories. It replaces the built-in save_memory tool with structured memory management including categorization and a table of contents.',
+  inputConfig: {
+    inputSchema: {
+      type: 'object',
+      properties: {
+        request: {
+          type: 'string',
+          description:
+            'The memory operation to perform. Examples: "Remember that I prefer tabs over spaces", "Clean up stale memories", "De-duplicate my memories", "Organize my memories".',
+        },
+      },
+      required: ['request'],
+    },
+  },
+  outputConfig: {
+    outputName: 'result',
+    description: 'A summary of the memory operations performed.',
+    schema: MemoryManagerSchema,
+  },
+  modelConfig: {
+    model: 'inherit',
+  },
+  toolConfig: {
+    tools: [
+      'read_file',
+      'replace',
+      'write_file',
+      'list_directory',
+      'glob',
+      'grep_search',
+    ],
+  },
+  promptConfig: {
+    systemPrompt: MEMORY_MANAGER_SYSTEM_PROMPT,
+    query: '${request}',
+  },
+  runConfig: {
+    maxTimeMinutes: 5,
+    maxTurns: 10,
+  },
+});

packages/core/src/agents/registry.ts

@@ -13,6 +13,7 @@ import { CodebaseInvestigatorAgent } from './codebase-investigator.js';
 import { CliHelpAgent } from './cli-help-agent.js';
 import { GeneralistAgent } from './generalist-agent.js';
 import { BrowserAgentDefinition } from './browser/browserAgentDefinition.js';
+import { MemoryManagerAgent } from './memory-manager-agent.js';
 import { A2AClientManager } from './a2a-client-manager.js';
 import { A2AAuthProviderFactory } from './auth-provider/factory.js';
 import type { AuthenticationHandler } from '@a2a-js/sdk/client';
@@ -250,6 +251,11 @@ export class AgentRegistry {
     if (browserConfig.enabled) {
       this.registerLocalAgent(BrowserAgentDefinition(this.config));
     }
+
+    // Register the memory manager agent as a replacement for the save_memory tool.
+    if (this.config.isMemoryManagerEnabled()) {
+      this.registerLocalAgent(MemoryManagerAgent());
+    }
   }
 
   private async refreshAgents(): Promise<void> {

packages/core/src/config/config.test.ts

@@ -3086,6 +3086,35 @@ describe('Config JIT Initialization', () => {
     expect(config.getUserMemory()).toBe('Initial Memory');
   });
 
+  describe('isMemoryManagerEnabled', () => {
+    it('should default to false', () => {
+      const params: ConfigParameters = {
+        sessionId: 'test-session',
+        targetDir: '/tmp/test',
+        debugMode: false,
+        model: 'test-model',
+        cwd: '/tmp/test',
+      };
+
+      config = new Config(params);
+      expect(config.isMemoryManagerEnabled()).toBe(false);
+    });
+
+    it('should return true when experimentalMemoryManager is true', () => {
+      const params: ConfigParameters = {
+        sessionId: 'test-session',
+        targetDir: '/tmp/test',
+        debugMode: false,
+        model: 'test-model',
+        cwd: '/tmp/test',
+        experimentalMemoryManager: true,
+      };
+
+      config = new Config(params);
+      expect(config.isMemoryManagerEnabled()).toBe(true);
+    });
+  });
+
   describe('reloadSkills', () => {
     it('should refresh disabledSkills and re-register ActivateSkillTool when skills exist', async () => {
       const mockOnReload = vi.fn().mockResolvedValue({

packages/core/src/config/config.ts

@@ -623,6 +623,7 @@ export interface ConfigParameters {
   disabledSkills?: string[];
   adminSkillsEnabled?: boolean;
   experimentalJitContext?: boolean;
+  experimentalMemoryManager?: boolean;
   topicUpdateNarration?: boolean;
   toolOutputMasking?: Partial<ToolOutputMaskingConfig>;
   disableLLMCorrection?: boolean;
@@ -845,6 +846,7 @@ export class Config implements McpContext, AgentLoopContext {
   private readonly adminSkillsEnabled: boolean;
 
   private readonly experimentalJitContext: boolean;
+  private readonly experimentalMemoryManager: boolean;
   private readonly topicUpdateNarration: boolean;
   private readonly disableLLMCorrection: boolean;
   private readonly planEnabled: boolean;
@@ -994,6 +996,7 @@ export class Config implements McpContext, AgentLoopContext {
     );
 
     this.experimentalJitContext = params.experimentalJitContext ?? false;
+    this.experimentalMemoryManager = params.experimentalMemoryManager ?? false;
     this.topicUpdateNarration = params.topicUpdateNarration ?? false;
     this.modelSteering = params.modelSteering ?? false;
     this.userHintService = new UserHintService(() =>
@@ -2065,6 +2068,10 @@ export class Config implements McpContext, AgentLoopContext {
     return this.experimentalJitContext;
   }
 
+  isMemoryManagerEnabled(): boolean {
+    return this.experimentalMemoryManager;
+  }
+
   isTopicUpdateNarrationEnabled(): boolean {
     return this.topicUpdateNarration;
   }
@@ -3088,9 +3095,11 @@ export class Config implements McpContext, AgentLoopContext {
     maybeRegister(ShellTool, () =>
       registry.registerTool(new ShellTool(this, this.messageBus)),
     );
-    maybeRegister(MemoryTool, () =>
-      registry.registerTool(new MemoryTool(this.messageBus)),
-    );
+    if (!this.isMemoryManagerEnabled()) {
+      maybeRegister(MemoryTool, () =>
+        registry.registerTool(new MemoryTool(this.messageBus)),
+      );
+    }
     maybeRegister(WebSearchTool, () =>
       registry.registerTool(new WebSearchTool(this, this.messageBus)),
     );

packages/core/src/core/prompts.test.ts

@@ -96,6 +96,7 @@ describe('Core System Prompt (prompts.ts)', () => {
       isInteractive: vi.fn().mockReturnValue(true),
       isInteractiveShellEnabled: vi.fn().mockReturnValue(true),
       isTopicUpdateNarrationEnabled: vi.fn().mockReturnValue(false),
+      isMemoryManagerEnabled: vi.fn().mockReturnValue(false),
       isAgentsEnabled: vi.fn().mockReturnValue(false),
       getPreviewFeatures: vi.fn().mockReturnValue(true),
       getModel: vi.fn().mockReturnValue(DEFAULT_GEMINI_MODEL_AUTO),
@@ -410,6 +411,7 @@ describe('Core System Prompt (prompts.ts)', () => {
         isInteractive: vi.fn().mockReturnValue(false),
         isInteractiveShellEnabled: vi.fn().mockReturnValue(false),
         isTopicUpdateNarrationEnabled: vi.fn().mockReturnValue(false),
+        isMemoryManagerEnabled: vi.fn().mockReturnValue(false),
         isAgentsEnabled: vi.fn().mockReturnValue(false),
         getModel: vi.fn().mockReturnValue('auto'),
         getActiveModel: vi.fn().mockReturnValue(PREVIEW_GEMINI_MODEL),