Skip to main content
The save_memory tool allows the Gemini agent to persist specific facts, user preferences, and project details across sessions by saving them to your global GEMINI.md file.

​
Overview

When Gemini needs to remember something for future sessions—like your coding preferences, project conventions, or frequently referenced information—it uses the save_memory tool to append that information to your global context file.
Memory is automatically loaded in all future sessions as part of the hierarchical context system.

​
How It Works

1

Agent identifies important information

During conversation, Gemini recognizes facts worth preserving (e.g., “User prefers functional programming”)
2

Tool is called

The agent calls save_memory with the fact to preserve
3

Fact is appended

The information is added to ## Gemini Added Memories section in ~/.gemini/GEMINI.md
4

Available in future sessions

Next time you start Gemini CLI, the saved memories are automatically loaded

​
Technical Reference

​
fact
string
required
A clear, self-contained statement in natural language describing the information to remember
Storage location: ~/.gemini/GEMINI.md (global context file) Format: Bulleted list items under the ## Gemini Added Memories heading Loading: Automatically included in the hierarchical context for all future sessions

​
Use Cases

User Preferences

“I prefer functional programming over OOP”“Always use TypeScript for new projects”

Project Conventions

“This codebase uses React hooks exclusively”“Follow the company’s security review checklist”

Environment Details

“Database runs on port 5433, not default 5432”“Use staging API key for testing”

Aliases & Shortcuts

“User’s git alias: ‘gp’ means ‘git push’”“npm run dev:local includes hot reload”

​
Examples

​
Saving a preference

> I prefer using async/await over promises
Gemini might respond: 
I'll remember that you prefer async/await. Let me save this preference.
The tool saves to ~/.gemini/GEMINI.md: 
## Gemini Added Memories
- User prefers using async/await over promises

​
Saving project information

> Our team uses Conventional Commits for all commit messages
Saved memory: 
## Gemini Added Memories
- Team uses Conventional Commits for all commit messages

​
Managing Saved Memories

You can view and edit saved memories by:
  1. Viewing with /memory show 
    /memory show
    This displays the full hierarchical context including saved memories
  2. Editing directly Open ~/.gemini/GEMINI.md in your editor and modify the ## Gemini Added Memories section
  3. Refreshing context After manual edits, use /memory refresh to reload the context

​
Best Practices

Each memory should be a single, clear statement. Avoid long paragraphs.Good: “User prefers tabs over spaces (4-space width)”Bad: “The user mentioned they like tabs better than spaces, and specifically they want 4 spaces worth of width when tabs are displayed…”
Gemini usually checks before saving duplicate information, but you can manually clean up the GEMINI.md file if needed.
Don’t save temporary task details. Use checkpoints or chat history instead.

GEMINI.md Reference

Learn about the hierarchical context system

Context Management

Understand how context files work

Memory Command

View and manage memories with /memory

Checkpointing

Save conversation state for later

Build docs developers (and LLMs) love

Get started for freeTalk to us