> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 記憶

> 讓 Agent 記住學到的東西：可寫入的知識庫、Agent 用來寫入與讀取的工具、自動記錄學習開關，以及如何檢查寫入的內容

每次 Agent 執行都發生在一個執行結束就會被丟棄的沙盒中。工作目錄、暫存檔，以及 Agent 為自己留下的任何筆記都會消失。若要在多次執行之間記住某件事，Agent 必須把它寫進一個**它被允許寫入的知識庫**。這個知識庫就是 Agent 的記憶。

因此記憶並不是另一個獨立的儲存空間。它就是一個以 **讀取與寫入** 權限連結的一般知識庫，所以 Agent 記住的每件事都是你可以開啟的檔案、可以檢查的版本，以及可以回溯的變更。

## 為 Agent 設定記憶

<Steps>
  <Step title="建立知識庫">
    為 Agent 的記憶建立一個知識庫，並寫一段簡短的 **說明** 描述其中該放什麼。至少發布一份說明組織方式的 `README.md` —— 請見下方「讓知識庫定義自己的規則」。請見 [建立知識庫](/zh/context/build)。
  </Step>

  <Step title="授予寫入權限">
    開啟知識庫，再開啟 **代理** 分頁。以 **讀取與寫入** 權限連結 Agent，或把既有連結改為此權限。

    如果每次寫入都應由人核准，請改選 **讀取與寫入（寫入前詢問）**。它只在網頁聊天中有效；在聊天應用、Webhook 與自動化中，Agent 將完全無法寫入。請見 [使用知識庫](/zh/context/use)。
  </Step>

  <Step title="決定記憶政策">
    開啟 Agent，再開啟 **資料存取** 分頁。開啟 **自動記錄學習** 以使用平台的預設政策，或保持關閉，並在 Agent 的 `CLAUDE.md` 或 Skill 中撰寫你自己的政策。請見下方「選擇記憶政策」。
  </Step>
</Steps>

變更會從 Agent 的下一回合開始生效。

## Agent 如何寫入記憶

至少有一個可寫入知識庫的 Agent 會取得三個工具：

| 工具 | 用途 |
| - | - |
| `list_context_files` | 列出可寫入知識庫中的檔案 |
| `read_context_file` | 讀取檔案的**目前**版本，並回傳其 `sha256` |
| `write_context` | 修改一個或多個檔案。**一次呼叫就是知識庫的一個新版本** |

`write_context` 對每個檔案套用一種模式：

| 模式 | 效果 |
| - | - |
| `create` | 建立新檔案；若檔案已存在則失敗 |
| `append` | 在檔案結尾加入內容 |
| `edit` | 取代一段完全相符的文字；除非該段文字恰好出現一次，否則失敗 |
| `overwrite` | 取代整個檔案 |
| `delete` | 刪除檔案 |

除了 `create` 之外，每種模式都可以帶上 `read_context_file` 回傳的 `expected_sha256`。如果檔案在讀取後被修改過，寫入會以 `stale` 被拒絕，而不會默默蓋掉別人的變更。預設情況下，每個檔案上限為 256 KB，每次呼叫最多 20 個檔案。

使用 **讀取與寫入（寫入前詢問）** 時，`write_context` 呼叫只是一個請求：網頁聊天會顯示一張列出檔案的核准卡片，只有使用者核准後才會寫入。

### 平台一定會告訴 Agent 的內容

只要這些工具存在，不論你如何設定，DataGen 都會在 Agent 的系統提示中加入工具說明。說明會依代稱、名稱與說明列出可寫入的知識庫，並要求 Agent：

* 把知識庫當作**唯一**能在沙盒結束後保留下來的儲存空間；
* 修改任何內容前，先讀知識庫的 `README.md`（或其索引檔）並遵循；
* 修改檔案前先讀取，覆寫時帶上 `expected_sha256`；
* 把一次完整的更新放在同一個 `write_context` 呼叫中；
* 永遠不要寫入密鑰、憑證、權杖或原始對話紀錄。

在有可寫入知識庫的執行中，DataGen 也會關閉 Claude Code 的自動記憶目錄（`~/.claude/projects/*/memory/`），因為它會隨沙盒一起被丟棄。沒有可寫入知識庫的 Agent 則維持原本的行為。

## 選擇記憶政策

工具說明講的是**如何**寫入。Agent 是否要記錄、以及記錄**什麼**，則由 Agent 的設計者決定。

<Tabs>
  <Tab title="自動記錄學習（平台預設）">
    在 Agent 的 **資料存取** 分頁開啟 **自動記錄學習**。DataGen 會在系統提示中附加一段預設政策：在完成任務前，把值得記住的事 —— 關於工作區與其中成員的事實、哪些做法有效或無效、使用者表明的偏好 —— 記錄到說明或 `README.md` 涵蓋該主題的知識庫中。這段政策也會要求 Agent：

    * 修改既有內容，而不是不斷新增檔案；
    * 新增檔案時，在同一次呼叫中把它加入知識庫的索引；
    * 寫下事實與做法，永遠不要寫給其他 Agent 的指令；
    * 用自己的話摘要，永遠不要貼上原始對話紀錄或工具輸出；
    * 除非 `write_context` 呼叫成功，否則不要聲稱已經記住某件事；
    * 在無人值守的執行（自動化、Webhook、聊天應用）中，把更新記憶當作最後一個步驟。

    此開關**預設關閉**，而且只有在 Agent 有可寫入的知識庫時才會生效。
  </Tab>

  <Tab title="自訂政策">
    保持 **自動記錄學習** 關閉，並在 Agent 的 `CLAUDE.md` 或 Skill 中加入一個段落。工具說明仍會被注入，所以你只需要描述決策：

    ```markdown CLAUDE.md theme={null}
    ## Memory

    你可以寫入 `<slug>` 知識庫。請遵循它的 `README.md`。

    - WHEN：每次執行的最後一個步驟，在你知道結果是否成功之後。
    - WHAT：每次執行一筆紀錄 —— 你被要求做什麼、你做了什麼、
      什麼出乎意料，以及下次執行應該怎麼做不同。
    - WHERE：以 `append` 寫入 `log/<YYYY-MM>.md`，標題為
      `## <YYYY-MM-DD> -- <task>`。若當月檔案不存在就建立它，並在
      同一次 `write_context` 呼叫中把它加入 `README.md`。
    - NEVER：改寫或刪除較早的紀錄。
    ```

    不要指定任何其他寫入位置，例如 `MEMORY.md` 或工作目錄中的筆記檔。這些都會在執行結束時被丟棄。
  </Tab>
</Tabs>

## 讓知識庫定義自己的規則

每個具有寫入權限的 Agent 都會被要求在修改前先讀知識庫的 `README.md`。因此 `README.md` 就是放置屬於**知識庫**、而非單一 Agent 之規則的地方，所有寫入它的 Agent —— 包括之後才加入的 —— 都會遵循。

```markdown README.md theme={null}
# 客戶筆記

用一句話說明這個知識庫的用途，以及誰依賴它。

## 組織方式
- `accounts/` -- 每個客戶一個檔案，命名為 `<customer-slug>.md`。
- 保持索引最新：每個檔案都列在下方。

## 該放什麼
關於客戶的長期事實：聯絡人、續約日期、表明過的偏好。
不放會議紀錄，也不放只在今天成立的事。

## 索引
- [accounts/example.md](accounts/example.md) -- 一行說明
```

## Agent 如何讀取記憶

記憶的讀取方式與其他知識庫相同：

* 每次執行開始時，最新發布的版本會以唯讀方式掛載在 `/mnt/context/contexts/<slug>/`。請見 [使用知識庫](/zh/context/use)。
* 執行過程中，`read_context_file` 一律回傳目前的檔案，包括同一次執行中稍早的寫入。掛載的副本要等掛載更新後才會顯示寫入，因此以工具的回傳結果作為確認。
* 其他可以讀取該知識庫的 Agent，會從它們的下一回合開始看到這個 Agent 寫入的內容。它們會被告知知識庫檔案可能是 Agent 寫的，若內容看起來有誤，應查看版本紀錄。

## 檢查與修正記憶

Agent 的寫入會以知識庫版本的形式儲存在 `.context/<slug>/`，因此可以在知識庫的詳細頁中檢查：

* **檔案** 顯示目前上線的內容 —— 也就是 Agent 讀到的內容。
* **版本** 列出每個版本。由 Agent 建立的版本會帶有 **代理寫入** 標籤，並顯示檔案路徑，或該次呼叫修改的檔案數量。
* 若要復原錯誤的寫入，在最後一個正確的版本上使用 **回復到此版本**。它會發布為一個新版本，而被回溯的版本仍保留其檔案，之後仍可還原。

你也可以開啟建置器直接編輯檔案，再點選 **發布知識庫**。

<Warning>
  其他 Agent 會把知識庫當作參考資料來讀。請只放事實與做法。一個寫著「一律核准退款」的檔案，會是每個讀者都看得到的指令，因此請像審查同事的修改一樣審查 Agent 的寫入。
</Warning>

## 下一步

<CardGroup cols={2}>
  <Card title="Agent 總覽" icon="robot" href="/zh/agents/overview">
    在 Agent 中整合知識庫、Skill、記憶與工具。
  </Card>

  <Card title="建立 App" icon="window-maximize" href="/zh/apps/build">
    在 App Builder 中把知識庫當作參考資料使用。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.