From f17cfb2a71da973d47bd72abb8435a4eed29a082 Mon Sep 17 00:00:00 2001 From: Sandy Tao Date: Tue, 5 May 2026 12:39:32 -0700 Subject: [PATCH] docs: clarify Auto Memory proposes memory updates and skills (#26527) --- docs/cli/auto-memory.md | 96 +++++++++++++++---------- docs/cli/tutorials/memory-management.md | 2 +- 2 files changed, 60 insertions(+), 38 deletions(-) diff --git a/docs/cli/auto-memory.md b/docs/cli/auto-memory.md index 8b3f5379da..d4472bdc1e 100644 --- a/docs/cli/auto-memory.md +++ b/docs/cli/auto-memory.md @@ -1,9 +1,10 @@ # Auto Memory Auto Memory is an experimental feature that mines your past Gemini CLI sessions -in the background and turns recurring workflows into reusable -[Agent Skills](./skills.md). You review, accept, or discard each extracted skill -before it becomes available to future sessions. +in the background and proposes durable memory updates and reusable +[Agent Skills](./skills.md). You review each candidate before it becomes +available to future sessions: apply memory updates, promote skills, or discard +anything you do not want. > [!NOTE] @@ -12,28 +13,33 @@ before it becomes available to future sessions. ## Overview Every session you run with Gemini CLI is recorded locally as a transcript. Auto -Memory scans those transcripts for procedural patterns that recur across -sessions, then drafts each pattern as a `SKILL.md` file in a project-local -inbox. You inspect the draft, decide whether it captures real expertise, and -promote it to your global or workspace skills directory if you want it. +Memory scans those transcripts for durable facts, preferences, workflow +constraints, and procedural patterns that recur across sessions. It can draft +memory updates as unified diff `.patch` files and draft reusable procedures as +`SKILL.md` files. All candidates are held in a project-local inbox until you +approve or discard them. You'll use Auto Memory when you want to: - **Capture team workflows** that you find yourself walking the agent through more than once. +- **Preserve durable project context** such as repeated verification commands, + local constraints, or personal project notes. - **Codify hard-won fixes** for project-specific landmines so future sessions avoid them. - **Bootstrap a skills library** without writing every `SKILL.md` by hand. Auto Memory complements—but does not replace—the [`save_memory` tool](../tools/memory.md), which captures single facts into -`GEMINI.md`. Auto Memory captures multi-step procedures into skills. +`GEMINI.md` when the agent explicitly calls it. Auto Memory infers candidates +from past sessions, writes reviewable patches or skill drafts, and never applies +them without your approval. ## Prerequisites - Gemini CLI installed and authenticated. -- At least 10 user messages across recent, idle sessions in the project. Auto - Memory ignores active or trivial sessions. +- At least one idle project session with 10 or more user messages. Auto Memory + ignores active, trivial, and sub-agent sessions. ## How to enable Auto Memory @@ -66,36 +72,45 @@ UI, consume your interactive turns, or surface tool prompts. been idle for at least three hours and contain at least 10 user messages. 2. **Lock acquisition.** A lock file in the project's memory directory coordinates across multiple CLI instances so extraction runs at most once at - a time. -3. **Sub-agent extraction.** A specialized sub-agent (named `confucius`) - reviews the session index, reads any sessions that look like they contain - repeated procedural workflows, and drafts new `SKILL.md` files. Its - instructions tell it to default to creating zero skills unless the evidence - is strong, so most runs produce no inbox items. -4. **Patch validation.** If the sub-agent proposes edits to skills outside the - inbox (for example, an existing global skill), it writes a unified diff - `.patch` file. Auto Memory dry-runs each patch and discards any that do not - apply cleanly. -5. **Notification.** When a run produces new skills or patches, Gemini CLI - surfaces an inline message telling you how many items are waiting. + a time. A state file records processed session versions, and extraction is + throttled so short back-to-back CLI launches do not repeatedly scan history. +3. **Candidate extraction.** A background extraction agent reviews the session + index, reads any sessions that look like they contain durable memory or + repeated procedural workflows, and drafts candidates. It defaults to + creating no artifacts unless the evidence is strong, so many runs produce no + inbox items. +4. **Safety boundaries.** Auto Memory writes candidates to a review inbox. It + cannot directly edit active memory files, settings, credentials, or project + `GEMINI.md` files. +5. **Patch validation.** Skill update patches are parsed and dry-run before + they are surfaced. Memory patches are parsed, target-allowlisted, and + applied atomically only when you approve them from the inbox. +6. **Notification.** When a run produces new candidates, Gemini CLI surfaces an + inline message telling you how many items are waiting. -## How to review extracted skills +## How to review extracted items Use the `/memory inbox` slash command to open the inbox dialog at any time: **Command:** `/memory inbox` -The dialog lists each draft skill with its name, description, and source -sessions. From there you can: +The dialog groups pending items into new skills, skill updates, and memory +updates. From there you can: - **Read** the full `SKILL.md` body before deciding. - **Promote** a skill to your user (`~/.gemini/skills/`) or workspace (`.gemini/skills/`) directory. - **Discard** a skill you do not want. - **Apply** or reject a `.patch` proposal against an existing skill. +- **Review** memory diffs before they touch active files. +- **Apply** or dismiss private and global memory patches. Private patches target + the project memory directory; global patches target only your personal + `~/.gemini/GEMINI.md` file. Promoted skills become discoverable in the next session and follow the standard -[skill discovery precedence](./skills.md#skill-discovery-tiers). +[skill discovery precedence](./skills.md#skill-discovery-tiers). Applied memory +patches update the underlying memory files and reload memory for the current +session. ## How to disable Auto Memory @@ -117,19 +132,26 @@ start. Existing inbox items remain on disk; you can either drain them with ## Data and privacy - Auto Memory only reads session files that already exist locally on your - machine. Nothing is uploaded to Gemini outside the normal API calls the - extraction sub-agent makes during its run. -- The sub-agent is instructed to redact secrets, tokens, and credentials it - encounters and to never copy large tool outputs verbatim. -- Drafted skills live in your project's memory directory until you promote or - discard them. They are not automatically loaded into any session. + machine. +- Auto Memory uses model calls to analyze selected local transcript content + during extraction. No candidates are applied automatically, but transcript + excerpts may be sent to the configured model as part of those calls. +- The extraction agent is instructed to redact secrets, tokens, and credentials + it encounters and to never copy large tool outputs verbatim. +- Drafted skills and memory patches live in your project's memory directory + until you promote, apply, dismiss, or discard them. They are not automatically + loaded into any session. ## Limitations -- The sub-agent runs on a preview Gemini Flash model. Extraction quality depends - on the model's ability to recognize durable patterns versus one-off incidents. -- Auto Memory does not extract skills from the current session. It only - considers sessions that have been idle for three hours or more. +- The extraction agent runs on a preview Gemini Flash model. Extraction quality + depends on the model's ability to recognize durable patterns versus one-off + incidents. +- Auto Memory does not extract memory or skills from the current session. It + only considers sessions that have been idle for three hours or more. +- Project or workspace shared instructions in project `GEMINI.md` files are not + auto-extractable. Auto Memory can propose private project memory, global + personal memory, and skills. - Inbox items are stored per project. Skills extracted in one workspace are not visible from another until you promote them to the user-scope skills directory. @@ -138,6 +160,6 @@ start. Existing inbox items remain on disk; you can either drain them with - Learn how skills are discovered and activated in [Agent Skills](./skills.md). - Explore the [memory management tutorial](./tutorials/memory-management.md) for - the complementary `save_memory` and `GEMINI.md` workflows. + the complementary explicit-memory and `GEMINI.md` workflows. - Review the experimental settings catalog in [Settings](./settings.md#experimental). diff --git a/docs/cli/tutorials/memory-management.md b/docs/cli/tutorials/memory-management.md index aa0423157f..5b2d4be7dc 100644 --- a/docs/cli/tutorials/memory-management.md +++ b/docs/cli/tutorials/memory-management.md @@ -125,4 +125,4 @@ immediately. Force a reload with: `/memory` options. - Read the technical spec for [Project context](../../cli/gemini-md.md). - Try the experimental [Auto Memory](../auto-memory.md) feature to extract - reusable skills from your past sessions automatically. + memory updates and reusable skills from your past sessions automatically.