Memory management

Memory management 解决的是“Gemini CLI 该长期记住什么”。它和 GEMINI.md 一起决定 agent 下次是否还会遵守你的项目习惯。

常见操作

/memory show
/memory refresh
/memory list
/memory add <fact>

修改 GEMINI.md 或相关上下文文件后，用 /memory refresh 让当前会话重新加载。/memory list 用来确认当前发现了哪些 memory 文件，/memory add 会把一条事实追加到全局 memory。

/memory show 用来查看当前拼接后的上下文，包括全局、项目、子目录 GEMINI.md 和保存的 memory。排查“为什么它不遵守规则”时，先看这里。

适合记住什么

• 项目长期规则。
• 常用验证命令。
• 稳定的目录职责。
• 反复出现的业务约定。
• 用户明确长期偏好。

不适合记住什么

• 一次性报错。
• 还没验证的猜测。
• 临时路径。
• 敏感信息。
• 已经完成的过程记录。

使用建议

长期规则优先写入文件；memory 只保留真正跨任务复用的事实。能写成明确规则的，就不要只靠模型“记得”。

save_memory 边界

Gemini CLI 的 save_memory 工具会把事实追加到全局 ~/.gemini/GEMINI.md 的 ## Gemini Added Memories 区域。它适合保存自我偏好、长期项目事实和稳定配置，但不适合保存密钥、客户数据、一次性 debug 过程。

如果某条事实只对当前仓库有效，优先写项目 GEMINI.md；如果只对某个子目录有效，写子目录规则；如果跨所有项目都成立，才考虑全局 memory。

记忆写错比 prompt 写错更麻烦，因为它会在之后很多任务里持续影响判断。能写成可审查文件的长期规则，优先写文件；只有跨项目、长期稳定、不会泄密的偏好，才适合全局 memory。

Auto Memory

官方还提供 experimental Auto Memory，用来从历史会话中提取 memory patch 和 skill。它适合愿意人工审核长期记忆变化的人，不适合默认全自动写入。记忆一旦失控，会比一次错误 prompt 更难排查。

官方命令边界

Gemini CLI 官方命令把 memory 分成两层：上下文文件和可追加的长期事实。/memory show 解决“当前会话到底读到了什么”，/memory refresh 解决“文件改完当前会话还没生效”，save_memory 解决“把一条长期事实写入全局 ~/.gemini/GEMINI.md”。

这三件事不能混用：

• 只想临时提醒当前任务，用普通 prompt。
• 想让仓库所有成员都遵守，写项目 GEMINI.md。
• 想让自己跨项目长期保留，才写全局 memory。
• 想排查上下文错乱，先 /memory show，不要继续追加新 memory。

save_memory 追加的是事实，不是聊天记录。好的 memory 应该短、稳定、可验证；例如“这个仓库的测试命令是 pnpm test”比“上次我们排查过构建问题”更可用。

记忆维护

建议把 memory 当成需要审查的配置，而不是聊天附属品：

• 新增后立刻用 /memory show 看最终拼接效果。
• 过时的版本号、路径、端口、模型名要删掉或更新。
• 含“总是”“永远”“不要”的规则要谨慎，避免压过项目级指令。
• 从 Auto Memory 产生的 patch 必须人工读过再接受。

如果发现 Gemini CLI 反复遵守一条已经过期的做法，先查 /memory show，再查全局和项目 GEMINI.md。不要只在当前 prompt 里反复纠正，否则下次还会复发。

验收方式

新增 memory 后运行 /memory show，确认内容位置、范围和表述都正确。每隔一段时间清理过期规则，尤其是版本号、端口、临时路径和已经改变的项目约定。

接下来去哪

官方来源

• Gemini CLI memory management tutorial
• Gemini CLI memory tool
• Gemini CLI auto memory