使用代理記憶

Managed Agents API 會話預設是短暫的。當會話結束時，代理學到的任何內容都會消失。記憶存儲讓代理能夠跨會話保留學習內容：用戶偏好設定、項目約定、先前的錯誤和領域背景。

概述

記憶存儲是一個工作區範圍的文本文檔集合，針對 Claude 進行了優化。當一個或多個記憶存儲附加到會話時，代理會在開始任務前自動檢查存儲，並在完成後寫入持久化的學習內容 - 您無需進行任何額外的提示或配置。

存儲中的每個記憶都可以通過 API 或 Console 直接存取和編輯，允許調整、導入和導出記憶。

對記憶的每次更改都會創建一個不可變的記憶版本以支持審計和回滾記憶更改。

創建記憶存儲

給存儲一個 name 和 description。描述會傳遞給代理，告訴它存儲包含什麼。

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

記憶存儲 id（memstore_...）是您在將存儲附加到會話時傳遞的內容。

用內容進行初始化（可選）

在任何代理運行前，用參考資料預加載存儲：

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

將記憶存儲附加到會話

記憶存儲在會話的 resources[] 陣列中附加。

可選地包含一個 prompt，如果您想為 Claude 提供會話特定的指示，說明如何使用此記憶存儲。它會連同記憶存儲的 name 和 description 一起提供給 Claude，並且上限為 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",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

每個會話最多支持 8 個記憶存儲。當記憶的不同部分有不同的所有者或存取規則時，附加多個存儲。常見原因：

• 共享參考資料 - 一個唯讀存儲附加到許多會話（標準、約定、領域知識），與每個會話自己的讀寫學習內容分開。
• 映射到您的產品結構 - 每個終端用戶、每個團隊或每個項目一個存儲，同時共享單一代理配置。
• 不同的生命週期 - 一個超越任何單一會話的存儲，或您想按自己的時間表進行存檔的存儲。

記憶工具

當記憶存儲附加到會話時，代理會自動獲得對記憶工具的存取權限。代理與記憶存儲的交互在事件流中註冊為 agent.tool_use 事件。

查看和編輯記憶

記憶存儲可以通過 API 直接管理。使用此功能來構建審查工作流、糾正不良記憶或在任何會話運行前初始化存儲。

列出記憶

列表不返回記憶內容，只返回對象元數據。使用 path_prefix 進行目錄範圍的列表（包括尾部斜杠：/notes/ 匹配 /notes/a.md 但不匹配 /notes_backup/old.md）。

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

讀取記憶

獲取單個記憶會返回完整內容。

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

創建記憶

使用 memories.write 通過路徑 upsert 記憶。如果路徑處不存在任何內容，則會創建它；如果記憶已存在，其內容將被替換。要通過 mem_... ID 變更現有記憶（例如，重命名其路徑或安全地應用內容編輯），請改用 memories.update（見下面的更新記憶）。

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

安全寫入（樂觀並發）

將 precondition={"type": "not_exists"} 傳遞給 memories.write 以使其成為僅創建保護。如果路徑處已存在記憶，寫入會返回 409 memory_precondition_failed 而不是替換它。在初始化存儲時使用此功能，當您想避免覆蓋現有內容時。

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

要安全地編輯現有記憶（讀取、修改、寫回而不覆蓋並發更改），請改用帶有 content_sha256 前置條件的 memories.update。見下面的更新記憶。

更新記憶

memories.update() 通過其 mem_... ID 修改現有記憶。您可以在一次調用中更改 content、path（重命名）或兩者。

重命名到已佔用的路徑會返回 409 conflict。調用者必須先刪除或重命名阻擋者，或傳遞 precondition={"type": "not_exists"} 以在目標處已存在任何內容時使重命名成為無操作。

下面的示例將記憶重命名為存檔路徑：

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

安全內容編輯（樂觀並發）

要編輯記憶的內容而不覆蓋並發寫入，請傳遞 content_sha256 前置條件。更新僅在存儲的雜湊仍與您讀取的雜湊匹配時應用；不匹配時會返回 409 memory_precondition_failed，此時您重新讀取記憶並針對新鮮狀態重試。

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,
)

可選地傳遞 expected_content_sha256 進行條件刪除。

審計記憶更改

對記憶的每次變更都會創建一個不可變的記憶版本（memver_...）。版本在父記憶的生命週期內累積，並形成其下的審計和回滾表面。實時 memories.retrieve 調用始終返回當前頭部；版本端點提供完整歷史。

每次變更都會寫入新版本：

• 對路徑的第一個 memories.write 創建一個帶有 operation: "created" 的版本。
• 更改 content、path 或兩者的 memories.update 創建一個帶有 operation: "modified" 的版本。
• memories.delete 創建一個帶有 operation: "deleted" 的版本。

使用版本端點來審計哪個用戶或代理更改了什麼和何時，檢查或恢復先前的快照，以及使用編輯從歷史中清除敏感內容。

列出版本

列出商店的分頁版本元數據，最新優先。按 memory_id、operation（created、modified 或 deleted）、session_id、api_key_id 或 created_at_gte/created_at_lte 時間範圍進行篩選。列表回應不包括 content 主體；當您需要完整內容時，使用 retrieve 取得個別版本。

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

取得版本

取得個別版本會傳回與列表回應相同的欄位，加上完整的 content 主體。

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

編輯版本

編輯會從歷史版本中清除內容，同時保留稽核軌跡（誰做了什麼，何時做的）。將其用於合規工作流程，例如移除洩露的祕密、個人識別資訊或使用者刪除請求。編輯會硬清除 content、content_sha256、content_size_bytes 和 path；所有其他欄位（包括行為者和時間戳記）都會保留。

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