使用記憶 - Claude API Docs

Agent Memory 是一項研究預覽功能。申請訪問權限以試用。

Agent API 會話默認是短暫的。當會話結束時，代理學到的任何內容都會消失。記憶存儲讓代理能夠跨會話進行學習：用戶偏好、項目約定、之前的錯誤和領域背景。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。研究預覽功能需要額外的 beta 標頭。SDK 會自動設置這些 beta 標頭。

概述

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

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

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

創建記憶存儲

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

store=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...

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

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

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

存儲中的單個記憶上限為 100KB（約 25K 個令牌）。將記憶結構化為許多小的聚焦文件，而不是少數幾個大文件。

將記憶附加到會話

記憶存儲在會話的 resources[] 數組中附加。

可選地包含 prompt，如果您想為 Claude 提供會話特定的指令，說明如何使用此記憶存儲。它會連同記憶存儲的 name 和 description 一起提供給 Claude，並且上限為 4,096 個字符。

您也可以配置 access。默認為 read_write，但也支持 read_only（在下面的示例中明確顯示）。

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

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

記憶工具

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

工具	描述
`memory_list`	列出存儲中的文檔，可選地按路徑前綴進行篩選。
`memory_search`	跨文檔內容進行全文搜索。
`memory_read`	讀取文檔的內容。
`memory_write`	在路徑處創建或覆蓋文檔。
`memory_edit`	修改現有文檔。
`memory_delete`	刪除文檔。

檢查和更正記憶

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

列出記憶

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

讀取記憶

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

寫入文檔

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

僅在路徑空閒時創建

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

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

更新

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

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

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

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

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

刪除文檔

可選地傳遞 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 獲取個別版本。

檢索版本

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

編輯版本

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

curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- > /dev/null <<EOF
{
  "path": "/formatting_standards.md",
  "content": "All reports use GAAP formatting. Dates are ISO-8601..."
}
EOF

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "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."
    }
  ]
}
EOF
)

page=$(curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories?path_prefix=/" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
jq -r '.data[] | "\(.path)  (\(.size_bytes) bytes, sha=\(.content_sha256[0:8]))"' <<< "$page"

mem=$(curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$memory_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
jq -r '.content' <<< "$mem"

mem=$(curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "path": "/preferences/formatting.md",
  "content": "Always use tabs, not spaces."
}
EOF
)

curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- > /dev/null <<EOF
{
  "path": "/preferences/formatting.md",
  "content": "Always use 2-space indentation.",
  "precondition": {"type": "not_exists"}
}
EOF

curl -fsS -X PATCH "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"path": "/archive/2026_q1_formatting.md"}' > /dev/null

curl -fsS -X PATCH "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- > /dev/null <<EOF
{
  "content": "CORRECTED: Always use 2-space indentation.",
  "precondition": {"type": "content_sha256", "content_sha256": "$mem_sha"}
}
EOF

curl -fsS -X DELETE "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" > /dev/null

curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions?memory_id=$mem_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "\(.id): \(.operation)"'

curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

curl -fsS -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id/redact" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{}'