Gemini CLI 会话管理：自动保存和恢复你的 AI 对话上下文

Gemini CLI 提供了强大的会话管理功能，能够自动保存所有对话历史，并支持随时恢复。这篇文章将详细介绍如何使用这些功能。

自动保存：无需手动操作

Gemini CLI 提供了完全自动的会话保存机制。不需要记住任何保存命令，也不需要担心忘记保存，每次交互都会自动记录。

保存的内容

每个会话中会自动保存以下内容：

• 完整的对话历史：你的所有提示词和模型的响应
• 工具执行记录：所有工具调用的输入和输出
• Token 使用统计：输入、输出、缓存的 Token 数量
• 推理过程摘要：Assistant 的思考过程（如果可用）

存储位置和范围

会话数据存储在本地目录：

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

这里有一个重要特性：会话是项目特定的。<project_hash> 是根据当前工作目录生成的哈希值，这意味着：

• 在 /home/user/project-a 运行 Gemini CLI 的会话历史
• 和在 /home/user/project-b 运行的会话历史是完全独立的
• 切换目录会自动切换到对应项目的会话历史

这个设计避免了不同项目的上下文混淆，非常实用。

恢复会话

Gemini CLI 提供了灵活的会话恢复方式，既可以从命令行启动时恢复，也可以在交互界面中选择。

方式 1：命令行恢复最新会话

最简单的方式是使用 --resume（或 -r）标志：

gemini --resume

这会立即加载最近的一次会话，恢复所有对话历史。

方式 2：按索引恢复特定会话

如果你想恢复某个特定的历史会话，首先需要列出所有可用的会话：

gemini --list-sessions

输出示例：

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]

然后使用索引号恢复：

gemini --resume 1

这会恢复第一个会话（Fix bug in auth）。

方式 3：按会话 ID 恢复

如果你记录了会话的完整 UUID，也可以直接使用：

gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

这种方式在脚本或自动化场景中特别有用。

交互式会话浏览器

Gemini CLI 还提供了一个非常直观的交互式界面来管理会话。在运行中的 CLI 会话里，输入：

/resume

这会打开会话浏览器（Session Browser），提供以下功能：

浏览和预览

在浏览器中，你可以：

• 滚动查看所有历史会话列表
• 预览详情：查看会话日期、消息数量、第一个用户提示等信息
• 快速识别：通过会话 ID 和简短描述找到目标会话

搜索功能

支持输入关键词来过滤会话。这在有很多历史会话时特别有用。

选择和恢复

使用方向键导航到想要的会话，按 Enter 即可立即恢复该会话的完整上下文。

删除不需要的会话

随着时间推移，你可能会积累很多会话记录。Gemini CLI 提供了删除功能来清理不需要的历史。

从命令行删除

使用 --delete-session 标志加上索引号或会话 ID：

gemini --delete-session 2

这会删除第二个会话。

从会话浏览器删除

1. 使用 /resume 打开会话浏览器
2. 导航到要删除的会话
3. 按 x 键

配置会话管理

你可以在 settings.json 中配置会话管理的行为，包括自动清理策略和会话长度限制。

自动清理旧会话

为了防止会话历史无限增长，可以启用自动清理策略：

{
  "general": {
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 50
    }
  }
}

配置说明：

• enabled：是否启用自动清理（默认 false）
• maxAge：会话保留时长，支持格式如 “24h”、“7d”、“4w”
• maxCount：最多保留的会话数量，超过此数量会删除最老的会话
• minRetention：最小保留期（安全限制），默认 “1d”，新于此期限的会话永远不会被自动删除

例如，上面的配置表示：

• 保留最近 30 天的会话
• 或最多保留 50 个会话（以先触发的为准）
• 但至少保留最近 1 天的会话（即使超过 50 个）

限制单个会话长度

还可以限制单个会话的轮次（turn）数，防止上下文窗口过长导致成本过高：

{
  "model": {
    "maxSessionTurns": 100
  }
}

• maxSessionTurns：单个会话允许的最大轮次数（一轮 = 一次用户输入 + 一次模型响应）
• 设置为 -1 表示不限制（默认）

达到限制时的行为：

• 交互模式：CLI 显示提示信息，停止发送请求，你需要手动开始新会话
• 非交互模式：CLI 退出并返回错误码

最佳实践

1. 善用项目目录隔离

为不同的任务或项目创建独立的目录，充分利用项目特定会话：

~/projects/feature-auth/     # 认证功能相关讨论
~/projects/bug-memory-leak/  # 内存泄漏调试
~/projects/refactor-db/      # 数据库重构

2. 定期清理历史

即使启用了自动清理，我也建议定期手动检查：

gemini --list-sessions

删除明显不需要的会话，保持列表简洁。

3. 合理设置保留策略

根据工作习惯配置清理策略：

• 短期项目："maxAge": "7d" + "maxCount": 20
• 长期项目："maxAge": "60d" + "maxCount": 100
• 实验性工作："maxAge": "3d" + "maxCount": 10

4. 控制会话长度

对于复杂的长期讨论，主动管理会话长度：

• 达到 30-50 轮对话时，考虑总结当前进展
• 开始新会话时，简要说明上下文和目标
• 避免单个会话变成"万能对话"

5. 使用描述性的初始提示

会话列表会显示第一个用户提示，所以让它有意义：

好的示例：

"重构 auth.js 模块，解决性能问题"
"调查 /api/users 端点的内存泄漏"

不好的示例：

"hi"
"帮我看看这个"

数据隐私和安全

本地存储

所有会话数据都存储在本地 ~/.gemini/ 目录：

• 不会自动上传到云端
• 文件权限默认仅当前用户可读写

清理敏感信息

如果会话中包含敏感信息（密钥、密码等），项目结束后记得清理：

团队协作注意事项

如果需要在团队中共享会话（例如用于培训或问题复现），注意：

1. 会话文件是 JSON 格式，可以手动复制
2. 检查内容是否包含敏感信息
3. 考虑编辑会话文件，移除敏感部分

总结

Gemini CLI 的会话管理系统通过自动保存、灵活恢复和智能清理，解决了 AI 辅助编程中的上下文持久化问题。关键特性如下：

1. 自动保存：无需手动操作，所有对话自动记录
2. 项目隔离：不同目录的会话完全独立，避免上下文混淆
3. 灵活恢复：支持命令行快速恢复和交互式浏览器选择
4. 智能清理：可配置的自动清理策略，平衡历史保留和存储空间
5. 会话控制：可限制单个会话长度，控制成本和复杂度

合理使用这些功能，能让多日、多项目的 AI 辅助开发工作流变得更加流畅和高效。

参考资料

• Gemini CLI Session Management 官方文档
• Gemini CLI 命令参考