使用记忆 - Claude API Docs

智能体记忆是一项研究预览功能。申请访问权限以试用。

智能体 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 tokens）。请将记忆组织为多个小型的专注文件，而非少数几个大文件。

将记忆附加到会话

记忆存储在会话的 resources[] 数组中附加。

如果您希望为 Claude 提供关于如何使用此记忆存储的会话特定指令，可以选择包含 prompt。它会连同记忆存储的 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（参见下方的更新）。

仅在路径空闲时创建

向 memories.write 传入 precondition={"type": "not_exists"} 可将其设为仅创建保护。如果该路径已存在文档，写入操作将返回 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" 的版本。

使用版本端点可以审计哪个用户或智能体在何时更改了什么内容，检查或恢复先前的快照，以及通过 redact 从历史记录中清除敏感内容。

列出版本

列出存储的分页版本元数据，按最新优先排序。可按 memory_id、operation（created、modified 或 deleted）、session_id、api_key_id 或 created_at_gte/created_at_lte 时间范围进行筛选。列表响应不包含 content 正文；如需完整内容，请使用 retrieve 获取单个版本。

获取单个版本

获取单个版本时，返回的字段与列表响应相同，并额外包含完整的 content 正文。

编辑版本

编辑操作会清除历史版本中的内容，同时保留审计跟踪（谁在何时做了什么）。可用于合规工作流，例如删除泄露的密钥、个人身份信息（PII）或用户删除请求。编辑操作会硬清除 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 '{}'