使用代理記憶

每個 Managed Agents 工作階段預設都會以全新的上下文開始。當工作階段結束時，代理建立的任何狀態都會消失。「Memory store」（記憶儲存庫）讓代理能夠跨工作階段保留資訊：使用者偏好、專案慣例、先前的錯誤以及領域上下文。



概述

記憶儲存庫是一個工作區範圍的文字文件集合，專為 Claude 最佳化。當您將儲存庫附加到工作階段時，它會被掛載為工作階段沙箱內的一個目錄。代理使用與操作檔案系統其餘部分相同的檔案工具來讀取和寫入它，並且描述每個掛載點的說明會自動加入系統提示中，告訴代理該去哪裡查找。這些互動需要代理工具集；請確保在建立代理時啟用它。

儲存庫中的每個記憶都透過路徑定址，可以直接透過 API 或 Console 讀取和編輯，方便進行調整、匯入和匯出。

對記憶的每次變更都會建立一個不可變的記憶版本，為代理寫入的所有內容提供稽核軌跡和時間點復原功能。



建立記憶儲存庫

為儲存庫提供 name 和 description。描述會傳遞給代理，告訴它儲存庫包含什麼內容。

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

記憶儲存庫的 id（memstore_...）是您在將儲存庫附加到工作階段時需要傳遞的值。



預先填入內容（選用）

在任何代理執行之前，預先載入參考資料到儲存庫中：

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null



將記憶儲存庫附加到工作階段

記憶儲存庫在建立工作階段時透過工作階段的 resources[] 陣列附加。與檔案和儲存庫資源不同，記憶儲存庫只能在工作階段建立時附加；不支援在執行中的工作階段新增或移除記憶儲存庫。

您可以選擇性地包含 instructions，為代理應如何使用此儲存庫提供工作階段特定的指引。它會與儲存庫的 name 和 description 一起顯示給代理，上限為 4,096 個字元。

您也可以設定 access。它預設為 read_write（在以下範例中明確顯示），但也支援 read_only。

ant beta:sessions create <<YAML
agent: $agent_id
environment_id: $environment_id
resources:
  - type: memory_store
    memory_store_id: $store_id
    access: read_write
    instructions: User preferences and project context. Check before starting any task.
YAML

每個工作階段最多支援 8 個記憶儲存庫。當記憶的不同部分有不同的擁有者或存取規則時，請附加多個儲存庫。常見原因包括：

• **共用參考資料：**一個唯讀儲存庫附加到多個工作階段（標準、慣例、領域知識），與每個工作階段自己的讀寫儲存庫分開。
• **對應到您產品的結構：**每個終端使用者、每個團隊或每個專案各一個儲存庫，同時共用單一代理設定。
• **不同的生命週期：**一個存續時間超過任何單一工作階段的儲存庫，或一個您想要按自己的排程封存的儲存庫。



代理如何存取記憶

每個附加的儲存庫都會掛載在工作階段沙箱內 /mnt/memory/ 下的一個目錄中。目錄名稱是儲存庫的顯示名稱經過清理後的檔案系統安全 slug（轉為小寫；連續的非英數字元會變成單一連字號），因此名為「Demo Memory」的儲存庫會掛載在 /mnt/memory/demo-memory/。確切路徑會在工作階段的記憶儲存庫資源的 mount_path 欄位中回傳；請從該處讀取，而非自行建構。代理使用標準代理工具集讀取和寫入儲存庫。對掛載路徑下的寫入會持久化回儲存庫，並在共用該儲存庫的工作階段之間保持同步；對 /mnt/memory/ 下任何其他路徑的寫入會落在容器本機暫存區，並在工作階段結束時遺失。每個掛載點的簡短描述（顯示名稱、掛載路徑、存取模式、儲存庫 description 以及任何 instructions）會自動加入系統提示中。

access 在檔案系統層級強制執行：read_only 掛載會拒絕寫入，而對 read_write 掛載的寫入會產生歸屬於該工作階段的記憶版本。

代理的讀取和寫入會在事件串流中顯示為一般的 agent.tool_use 和 agent.tool_result 事件，對應於觸及該掛載點的任何工具。



檢視和編輯記憶

記憶儲存庫可以直接透過 API 管理。使用此功能來建立審查工作流程、修正錯誤的記憶，或在任何工作階段執行之前預先填入儲存庫。



列出記憶

列出儲存庫中的記憶，可選擇性地透過 path_prefix 篩選，以像瀏覽目錄一樣瀏覽路徑：

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/" --order-by path --depth 2

請參閱列出記憶參考文件以取得完整參數和回應結構描述。



讀取記憶

擷取個別記憶會回傳完整內容。

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

請參閱擷取記憶參考文件以取得完整參數和回應結構描述。



建立記憶

memories.create 在指定的 path 建立記憶。建立不會覆寫；若要變更現有記憶，請使用 memories.update。

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

請參閱建立記憶參考文件以取得完整參數和回應結構描述。



更新記憶

memories.update 透過 ID 修改現有記憶。您可以變更 content、path（重新命名）或兩者。此範例將記憶重新命名為封存路徑：

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

請參閱更新記憶參考文件以取得完整參數和回應結構描述。



安全的內容編輯（樂觀並行控制）

為避免覆蓋並行寫入，請傳遞 content_sha256 前置條件。只有當儲存的內容雜湊仍與您讀取的雜湊相符時，更新才會套用；若不相符，請重新讀取記憶並針對最新狀態重試。

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null



刪除記憶

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

請參閱刪除記憶參考文件以取得完整參數和回應結構描述。



稽核記憶變更

對記憶的每次變更都會建立一個不可變的記憶版本（memver_...）。使用版本端點來稽核誰在何時變更了什麼、檢查或還原先前的快照，以及透過遮蔽功能從歷史記錄中清除敏感內容。

版本屬於儲存庫（而非個別記憶），即使記憶本身被刪除後仍會保留，因此稽核軌跡保持完整。版本會保留 30 天；但是，無論時間長短，最近的版本始終會保留，因此不常變更的記憶可能會保留超過 30 天的歷史記錄。即時的 memories.retrieve 呼叫始終回傳最新版本；版本端點則提供保留的歷史記錄。

沒有專用的還原端點；若要回復，請擷取您想要的版本，並使用 memories.update 將其 content 寫回（如果父記憶已被刪除，則使用 memories.create，因為版本的存續時間超過其父記憶）。

過去的記憶版本可能會在 30 天後被刪除。若要保留更長時間的記憶歷史記錄，請透過 API 匯出版本。



列出版本

列出儲存庫的版本歷史記錄，最新的排在最前面。此範例篩選為單一記憶的歷史記錄：

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

請參閱列出記憶版本參考文件以取得完整參數和回應結構描述。



擷取版本

擷取個別版本會回傳與列表回應相同的欄位，外加完整的 content 內容。

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

請參閱擷取記憶版本參考文件以取得完整參數和回應結構描述。



遮蔽版本

遮蔽會從歷史版本中清除內容，同時保留稽核軌跡（誰在何時做了什麼）。將其用於合規工作流程，例如移除洩漏的機密、個人識別資訊（PII）或使用者刪除請求。

作為即時記憶當前最新版本的版本無法被遮蔽。請先寫入新版本（或刪除該記憶），然後再遮蔽舊版本。

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

請參閱遮蔽記憶版本參考文件以取得完整參數和回應結構描述。



管理記憶儲存庫

除了 create 之外，記憶儲存庫還支援 retrieve、update、list、archive 和 delete。



列出儲存庫

列出工作區中的儲存庫。預設會排除已封存的儲存庫；傳遞 include_archived: true 以包含它們。

ant beta:memory-stores list --include-archived

請參閱列出記憶儲存庫參考文件以取得完整參數和回應結構描述。



封存儲存庫

封存會使儲存庫變為唯讀，並防止其被附加到新的工作階段。封存是單向的；沒有取消封存的功能。

ant beta:memory-stores archive --memory-store-id "$store_id"

請參閱封存記憶儲存庫參考文件以取得完整參數和回應結構描述。

若要永久移除儲存庫及其所有記憶和版本，請使用 memory_stores.delete。



記憶管理的最佳實務

當儲存庫達到 2,000 個記憶的上限時，對新記憶的寫入會失敗：包括直接的 memories.create 呼叫和代理對未對應路徑的檔案寫入。現有記憶仍可讀取和編輯。以下實務可協助您保持遠低於上限，並在達到上限時順利復原。

• **使用專注的儲存庫。**與其使用一個大型通用儲存庫，不如使用較小的專用儲存庫——每個使用者一個、共用領域知識一個、專案特定上下文一個。每個儲存庫都有自己的 2,000 個記憶上限，因此保持儲存庫範圍明確可降低任何單一儲存庫填滿的機率。

• **在儲存庫填滿之前進行壓縮或清理。**使用 memories.delete 刪除過時或冗餘的記憶。您也可以執行夢境工作階段，它會將零散的內容整合到一個獨立的新輸出儲存庫中，而非修改原始儲存庫。將您的工作階段切換到該輸出儲存庫，然後封存或刪除原始儲存庫。

• **在合適時附加新儲存庫。**如果儲存庫已超出其有用範圍，請為新內容附加一個全新的儲存庫，並以 read_only 存取權限附加原始儲存庫。代理可以從兩者讀取，但只寫入新的儲存庫。

• **在適當情況下限制寫入存取。**只讀取共用參考資料的工作階段不需要 read_write。將寫入存取限制在實際新增記憶的工作階段，可以更容易追蹤成長的來源。