---
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="/zh-Hant/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
  <Card title="GEMINI.md" description="需要團隊共享的長期規則，優先寫專案上下文檔案。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Terms & Privacy" description="涉及長期記憶和資料使用時，繼續核對隱私與服務條款邊界。" href="/zh-Hant/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)
