使用代理記憶

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

概覽

記憶儲存庫是一個以工作區為範圍、針對 Claude 最佳化的文字文件集合。當您將儲存庫附加到工作階段時，它會以目錄的形式掛載在工作階段的沙箱內。代理使用與檔案系統其餘部分相同的檔案工具來讀取和寫入它，並且描述每個掛載的說明會自動新增到「system prompt」（系統提示）中，告訴代理該去哪裡查找。這些互動需要代理工具集；請確保在建立代理時啟用它。在自行託管的沙箱上，該目錄並非即時掛載。取而代之的是，SDK 的環境工作程式會在代理的工具執行之前將每個附加的儲存庫下載到您的沙箱中，並使該副本與儲存庫保持同步。

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

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

建立記憶儲存庫

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

ant apply memory_store.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.

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

預先填入內容（選用）

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

client.beta.memory_stores.memories.create(
    store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

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

記憶儲存庫在建立工作階段時附加於工作階段的 resources[] 陣列中。與檔案資源不同，記憶儲存庫只能在建立工作階段時附加；不支援在執行中的工作階段新增或移除記憶儲存庫。對於雲端和自行託管環境上的工作階段，附加記憶儲存庫的方式相同；自行託管環境僅接受 memory_store 資源。

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

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

session = client.beta.sessions.create(
    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.",
        }
    ],
)

每個工作階段最多支援 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 錯誤。

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for item in page.data:
    print(item.type, item.path)

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

讀取記憶

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

retrieved = client.beta.memory_stores.memories.retrieve(
    mem.id,
    memory_store_id=store.id,
)
print(retrieved.content)

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

建立記憶

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

mem = client.beta.memory_stores.memories.create(
    store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

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

更新記憶

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

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

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

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

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

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)

刪除記憶

client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id=store.id,
)

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

稽核記憶變更

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

版本屬於儲存庫（而非個別記憶），且在記憶本身被刪除時不會被刪除，因此稽核軌跡也涵蓋已刪除的記憶，但受下述保留規則約束。版本在寫入後會保留 30 天；然而，現存記憶的近期版本無論存在多久都會一律保留，因此不常變更的記憶可能會保留超過 30 天的歷史記錄。即時的 memories.retrieve 呼叫一律回傳最新版本；版本端點則提供您所保留的歷史記錄。

沒有專用的還原端點；若要回復，請擷取您想要的版本，並使用 memories.update 將其 content 寫回（若父記憶已被刪除，則使用 memories.create，前提是您想要的版本仍被保留）。

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

列出版本

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

versions = client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
)
for version in versions:
    print(f"{version.id}: {version.operation}")

version_id = versions.data[1].id

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

擷取版本

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

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

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

遮蔽版本

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

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

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)

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

管理記憶儲存庫

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

列出儲存庫

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

for memory_store in client.beta.memory_stores.list(include_archived=True):
    print(memory_store.id, memory_store.name, memory_store.archived_at)

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

封存儲存庫

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

client.beta.memory_stores.archive(store.id)

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

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

記憶管理的最佳實務

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

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

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

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

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