docs/tools/memory.md

Memory files

Gemini CLI persists durable facts, user preferences, and project details by editing Markdown memory files directly.

Technical reference

The agent routes memories to the appropriate Markdown file: shared project instructions go in repository GEMINI.md files, private project notes go in the per-project private memory folder, and cross-project personal preferences go in the global ~/.gemini/GEMINI.md file.

Technical behavior

• Storage: Edits Markdown files with write_file or replace.
• Loading: The stored facts are automatically included in the hierarchical context system for all future sessions.
• Format: Keeps durable instructions concise and avoids duplicating the same fact across multiple memory tiers.

Use cases

• Persisting user preferences (for example, "I prefer functional programming").
• Saving project-wide architectural decisions.
• Storing frequently used aliases or system configurations.

Next steps

• Follow the Memory management guide for practical examples.
• Learn how the Project context (GEMINI.md) system loads this information.