Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
每個 Managed Agents 工作階段預設都以全新的上下文開始。當工作階段結束時，代理建立的任何狀態都會消失。記憶儲存庫讓代理能夠跨工作階段攜帶資訊：使用者偏好、專案慣例、先前的錯誤以及領域上下文。
記憶儲存庫（memory store）是一個以工作區為範圍、針對 Claude 最佳化的文字文件集合。當您將儲存庫附加到工作階段時，它會被掛載為工作階段沙箱內的一個目錄。代理使用與檔案系統其餘部分相同的檔案工具來讀取和寫入它，並且描述每個掛載點的說明會自動新增到系統提示中，告訴代理該去哪裡查看。這些互動需要代理工具集；請確保在代理建立期間啟用它。
儲存庫中的每個記憶（memory）都由一個路徑定址，並且可以直接透過 API 或 Console 讀取和編輯，以便進行調整、匯入和匯出。
對記憶的每次變更都會建立一個不可變的記憶版本（memory version），為代理寫入的所有內容提供稽核軌跡和時間點復原。
為儲存庫提供 name 和 description。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 將列表範圍限定在一個目錄。它必須以 / 結尾並比對完整的路徑區段，因此 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/nullant 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 刪除過時或冗餘的記憶。您也可以執行夢境工作階段，它會將零散的內容整合到一個獨立的新輸出儲存庫中，而不是修改原始儲存庫。將您的工作階段切換到該輸出儲存庫，然後封存或刪除原始儲存庫。
**在合理的情況下附加新的儲存庫。**如果儲存庫已超出其有用範圍，請為新內容附加一個全新的儲存庫，並以 read_only 存取權限附加原始儲存庫。代理可以從兩者讀取，但只寫入新的儲存庫。
**在適當的情況下限制寫入存取權限。**只讀取共享參考資料的工作階段不需要 read_write。將寫入存取權限限定在實際新增記憶的工作階段，可以更容易追蹤成長的來源。
Was this page helpful?