---
title: "Memory management"
description: "Gemini CLI memory management、auto memory、/memory reload 的用途，以及记忆、上下文文件和临时 prompt 的边界。"
verifiedAt: "2026-05-09"
---

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

> [!IMPORTANT]
> **记忆不是垃圾桶**：只沉淀稳定事实和长期偏好，不要把每次任务过程都写进去。

## 常见操作

```text
/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。

| 信息类型 | 推荐落点 | 原因 |
| --- | --- | --- |
| 项目目录职责 | 项目或子目录 `GEMINI.md` | 和仓库结构绑定 |
| 个人长期偏好 | 全局 memory | 跨项目复用 |
| 验证命令 | 项目 `GEMINI.md` | 团队成员也需要一致 |
| 一次性错误现场 | 当前 session | 任务结束就过期 |
| 密钥、账号、客户数据 | 不写入 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`，确认内容位置、范围和表述都正确。每隔一段时间清理过期规则，尤其是版本号、端口、临时路径和已经改变的项目约定。

## 接下来去哪

<Cards>
  <Card title=".geminiignore" description="继续看哪些文件不该进入 Gemini CLI 上下文。" href="/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
  <Card title="GEMINI.md" description="需要团队共享的长期规则，优先写项目上下文文件。" href="/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Terms & Privacy" description="涉及长期记忆和数据使用时，继续核对隐私与服务条款边界。" href="/docs/gemini-cli/official/06-security-enterprise/65-terms-privacy" />
</Cards>

## 官方来源

- [Gemini CLI memory management tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/memory-management.md)
- [Gemini CLI memory tool](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/memory.md)
- [Gemini CLI auto memory](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/auto-memory.md)
