Skip to main content
Session management automatically saves your conversation history so you can resume work where you left off, review past interactions, and manage history across different projects.

​
How It Works

1

Automatic Saving

Sessions are recorded automatically as you interact with the model—no manual saving required.
2

Project-Scoped Storage

Sessions are stored in ~/.gemini/tmp/<project_hash>/chats/ where <project_hash> is unique to your project directory.
3

Resume Anytime

Use /resume or --resume flag to browse and restore previous conversations with full context.

​
What Is Saved

Each session automatically captures:

Conversation

Your prompts and the model’s responses

Tool Executions

All tool inputs and outputs

Token Usage

Input, output, cached tokens, and statistics

Reasoning

Assistant thoughts and reasoning summaries
Sessions are project-specific. Switching directories to a different project switches to that project’s session history.

​
Resuming Sessions

Resume previous conversations to continue with all prior context restored.

​
From the Command Line

Use the --resume or -r flag when starting Gemini CLI. 
gemini --resume

​
From the Interactive Interface

While the CLI is running, use the /resume command to open the Session Browser. 
/resume

​
Session Browser Features

Scroll through a list of past sessions with:
  • Session date and timestamp
  • Message count
  • First user prompt for context
  • Session ID
Press / to enter search mode and filter by:
  • Session ID
  • Conversation content
  • Prompts and responses
Sort sessions by:
  • Date (newest/oldest)
  • Message count (most/least)
  • Press Enter to resume the selected session
  • Press Esc to exit without resuming

​
Managing Sessions

Keep your history organized and manage disk space.

​
Listing Sessions

View all available sessions for the current project: 
gemini --list-sessions
Example Output: 
Available sessions for this project (3):

  1. Fix bug in auth (2 days ago) [a1b2c3d4]
  2. Refactor database schema (5 hours ago) [e5f67890]
  3. Update documentation (Just now) [abcd1234]

​
Deleting Sessions

Remove old or unwanted sessions to free up space.
Delete by index or ID:
gemini --delete-session 2
or
gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890
When a session is deleted, Gemini CLI also removes all associated data including implementation plans, task trackers, tool outputs, and activity logs.

​
Configuration

Customize session management behavior in your settings.json file.

​
Session Retention

By default, Gemini CLI automatically cleans up old sessions to prevent indefinite growth. Default Policy: Retain sessions for 30 days

​
Configure Retention

Edit via /settings or manually in settings.json: 
{
  "general": {
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 50,
      "minRetention": "1d"
    }
  }
}

​
Settings Reference

​
enabled
boolean
default:"true"
Master switch for automatic session cleanup.
​
maxAge
string
default:"30d"
Duration to keep sessions. Sessions older than this are deleted.Examples: "24h", "7d", "4w"
​
maxCount
number
default:"undefined"
Maximum number of sessions to retain. Oldest sessions exceeding this count are deleted.Default: Unlimited
​
minRetention
string
default:"1d"
Minimum retention period (safety limit). Sessions newer than this are never deleted by automatic cleanup.

​
Session Limits

Limit the length of individual sessions to control context window size and costs. 
{
  "model": {
    "maxSessionTurns": 100
  }
}
​
model.maxSessionTurns
number
default:"-1"
Maximum number of turns (user and model exchanges) allowed in a single session.Set to -1 for unlimited (default).

​
Behavior When Limit Reached

The CLI shows an informational message and stops sending requests. You must manually start a new session.

​
Storage Locations

​
Session Data

~/.gemini/tmp/<project_hash>/chats/

​
Associated Data

  • Implementation plans: ~/.gemini/tmp/<project_hash>/plans/
  • Task trackers: ~/.gemini/tmp/<project_hash>/tasks/
  • Tool outputs: ~/.gemini/tmp/<project_hash>/outputs/
  • Activity logs: ~/.gemini/tmp/<project_hash>/logs/

​
Manual Checkpoints

Beyond automatic session saving, you can create manual conversation checkpoints with tags.

​
Using /chat Commands

/chat save feature-implementation

​
Checkpoint Storage

Manual checkpoints are stored separately from automatic sessions: 
~/.gemini/tmp/<project_hash>/
Manual /chat checkpoints are for conversation state only. For file modification checkpoints, see Checkpointing.

​
Export Conversations

Export current conversation to Markdown or JSON: 
/chat share conversation.md
/chat share conversation.json
If no filename is provided, the CLI generates one automatically.

​
Best Practices

Use Descriptive Tags

When creating manual checkpoints with /chat save, use descriptive tags like before-refactor or working-auth.

Regular Cleanup

Periodically review and delete old sessions to manage disk space, even with automatic cleanup enabled.

Project Isolation

Remember that sessions are project-scoped. Start the CLI from your project directory to access relevant history.

Limit Long Sessions

Set maxSessionTurns to prevent context windows from becoming too large and expensive.

​
Troubleshooting

Cause: Sessions are project-specific based on the directory where you run the CLI.Solution: Navigate to the project directory where the session was created, then run /resume or gemini --resume.
Cause: No sessions exist for the current project.Solution: Ensure you’re in the correct project directory. Sessions created in other directories won’t appear.
Cause: Automatic cleanup removed the session based on retention policy.Solution: Check general.sessionRetention.maxAge and maxCount settings. Increase retention period or disable automatic cleanup with "enabled": false.
Cause: Multiple projects may share the same hash if directory structure is similar.Solution: Verify you’re in the correct project directory. The project hash is based on the absolute path.

Checkpointing

Automatic snapshots before file modifications with /restore

Memory

Persistent instructional context across sessions

Rewind

Navigate backward through conversation history

​
Next Steps

Commands Overview

Learn about /resume, /chat, and /rewind commands

Configuration

Configure session retention and limits

Build docs developers (and LLMs) love

Get started for freeTalk to us