使用代理記憶

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



概覽

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

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

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



建立記憶儲存庫

為儲存庫指定 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 欄位中回傳；請從該處讀取，而非自行建構。代理使用標準的 agent toolset 讀取和寫入儲存庫。在掛載路徑下的寫入會持久化回儲存庫，並在共用該儲存庫的工作階段之間保持同步；對 /mnt/memory/ 下任何其他路徑的寫入會失敗，因為沙箱以唯讀方式掛載該父目錄。每個掛載點的簡短描述（顯示名稱、掛載路徑、存取模式、儲存庫 description，以及任何 instructions）會自動加入系統提示中。

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

代理的讀取與寫入會在事件串流中，以觸及該掛載點的工具所對應的一般 agent.tool_use 與 agent.tool_result 事件呈現。



檢視與編輯記憶

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



列出記憶

列出儲存庫中的記憶。結果會以穩定的、由伺服器定義的順序回傳。

• path_prefix 將清單範圍限定在一個目錄。它必須以 / 結尾，並比對完整的路徑區段，因此 path_prefix=/notes/ 會回傳 /notes/todo.md，但不會回傳 /notes-archive/todo.md。
• depth 控制清單在 path_prefix 之下深入的層級：省略它（或傳入 0）可列出整個子樹，或傳入 1 僅列出直接子項目。其他值會回傳 400 錯誤。

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

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



讀取記憶

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

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_...）。使用版本端點來稽核誰在何時變更了什麼、檢視或還原先前的快照，以及透過 redact（遮蔽）將敏感內容從歷史記錄中清除。

版本屬於儲存庫（而非個別記憶），即使記憶本身被刪除後仍會保留，因此稽核軌跡保持完整。版本會保留 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)
# `list --format json` 會為每個項目輸出一個 JSON 物件。
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

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



擷取版本

擷取個別版本會回傳與清單回應相同的欄位，外加完整的 content 主體。

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

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



遮蔽版本

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

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

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 刪除過時或多餘的記憶。您也可以執行 dreaming 工作階段，它會將零散的內容整合到一個獨立的新輸出儲存庫中，而非修改原始儲存庫。將您的工作階段切換到該輸出儲存庫，然後封存或刪除原始儲存庫。

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

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