使用智能体记忆

默认情况下，每个 Managed Agents 会话都以全新的上下文开始。当会话结束时，智能体积累的任何状态都会消失。“Memory store”（记忆存储）让智能体能够跨会话携带信息：用户偏好、项目约定、先前的错误以及领域上下文。

注意

不要在记忆存储请求中将 agent-memory-2026-07-22 与 managed-agents-2026-04-01 组合使用：同时发送两者会返回 400 错误。如果您的代码显式设置了 beta 请求头，请在记忆存储调用中将 managed-agents-2026-04-01 替换为 agent-memory-2026-07-22，而不是添加第二个值。会话端点（包括将记忆存储附加到会话）仍然使用 managed-agents-2026-04-01。

GET /v1/memory_stores/{memory_store_id}/memories 在任一请求头下的行为相同：结果以稳定的、由服务器定义的顺序返回，并且 path_prefix 和 depth 的应用方式相同。

概述

“memory store”（记忆存储）是一个工作区范围内、针对 Claude 优化的文本文档集合。当您将存储附加到会话时，它会作为目录挂载到会话的沙箱中。智能体使用与文件系统其他部分相同的文件工具来读写它，并且描述每个挂载的说明会自动添加到系统提示中，告诉智能体去哪里查找。这些交互需要 agent toolset（智能体工具集）；请确保在创建智能体时启用它。在自托管沙箱上，该目录不是实时挂载。相反，您的环境 worker 会在智能体的工具运行之前将每个附加的存储下载到您的沙箱中，并使该副本与存储保持同步。

存储中的每条记忆（memory）都通过路径寻址，可以直接通过 API 或 Claude Console 读取和编辑，从而支持调优、导入和导出。

对记忆的每次更改都会创建一个不可变的记忆版本（memory version），为智能体写入的所有内容提供审计跟踪和时间点恢复能力。

创建记忆存储

为存储提供 name (csharp, go: Name) 和 description (csharp, go: Description)。描述会传递给智能体，告诉它该存储包含什么内容。

cURL

curl -s https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{
    "name": "User Preferences",
    "description": "Per-user preferences and project context."
  }'

CLI

ant apply memory_store.yaml

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.

Python

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

TypeScript

const store = await client.beta.memoryStores.create({
  name: "User Preferences",
  description: "Per-user preferences and project context."
});
console.log(store.id); // memstore_01Hx...

C#

var store = await client.Beta.MemoryStores.Create(new()
{
    Name = "User Preferences",
    Description = "Per-user preferences and project context.",
});
Console.WriteLine(store.ID);  // memstore_01Hx...

Go

store, err := client.Beta.MemoryStores.New(ctx, anthropic.BetaMemoryStoreNewParams{
	Name:        "User Preferences",
	Description: anthropic.String("Per-user preferences and project context."),
})
if err != nil {
	panic(err)
}
fmt.Println(store.ID) // memstore_01Hx...

Java

var store = client.beta().memoryStores().create(
    MemoryStoreCreateParams.builder()
        .name("User Preferences")
        .description("Per-user preferences and project context.")
        .build()
);
IO.println(store.id());  // memstore_01Hx...

PHP

use Anthropic\Client;

$client = new Client();

$store = $client->beta->memoryStores->create(
    name: 'User Preferences',
    description: 'Per-user preferences and project context.',
);
echo "{$store->id}\n"; // memstore_01Hx...

Ruby

require "anthropic"

client = Anthropic::Client.new

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

记忆存储的 id (csharp, go: ID)（memstore_...）是您将存储附加到会话时传递的值。

预填充内容（可选）

在任何智能体运行之前，为存储预加载参考资料：

cURL

curl -s "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: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{
    "path": "/formatting_standards.md",
    "content": "All reports use GAAP formatting. Dates are ISO-8601..."
  }'

CLI

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..."

Python

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

TypeScript

await client.beta.memoryStores.memories.create(store.id, {
  path: "/formatting_standards.md",
  content: "All reports use GAAP formatting. Dates are ISO-8601..."
});

C#

await client.Beta.MemoryStores.Memories.Create(store.ID, new()
{
    Path = "/formatting_standards.md",
    Content = "All reports use GAAP formatting. Dates are ISO-8601...",
});

Go

_, err = client.Beta.MemoryStores.Memories.New(ctx, store.ID, anthropic.BetaMemoryStoreMemoryNewParams{
	Path:    "/formatting_standards.md",
	Content: anthropic.String("All reports use GAAP formatting. Dates are ISO-8601..."),
})
if err != nil {
	panic(err)
}

Java

client.beta().memoryStores().memories().create(
    store.id(),
    MemoryCreateParams.builder()
        .path("/formatting_standards.md")
        .content("All reports use GAAP formatting. Dates are ISO-8601...")
        .build()
);

PHP

$client->beta->memoryStores->memories->create(
    $store->id,
    path: '/formatting_standards.md',
    content: 'All reports use GAAP formatting. Dates are ISO-8601...',
);

Ruby

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

提示

存储中的单条记忆上限为 100 kB（约 25k 令牌）。一个存储最多可容纳 10,000 条记忆。请将记忆组织为许多小而专注的文件，而不是少数几个大文件。

将记忆存储附加到会话

记忆存储在创建会话时通过会话的 resources (csharp, go: Resources) 数组附加。与文件资源不同，记忆存储只能在创建会话时附加；不支持在运行中的会话中添加或移除记忆存储。对于云端环境和自托管环境上的会话，附加记忆存储的方式相同；自托管环境仅接受 memory_store 资源。

您可以选择包含 instructions (csharp, go: Instructions)，为智能体应如何使用此存储提供特定于会话的指导。它会与存储的 name (csharp, go: Name) 和 description (csharp, go: Description) 一起展示给智能体，上限为 4,096 个字符。

您还可以配置 access (csharp, go: Access)。它默认为 read_write（在以下示例中显式展示），但也支持 read_only。

cURL

curl -s 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" \
  -d '{
    "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."
      }
    ]
  }'

CLI

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

Python

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.",
        }
    ],
)

TypeScript

const session = await 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."
    }
  ]
});

C#

var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Resources =
    [
        new BetaManagedAgentsMemoryStoreResourceParam
        {
            MemoryStoreID = store.ID,
            Access = "read_write",
            Instructions = "User preferences and project context. Check before starting any task.",
        },
    ],
});

Go

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
		OfMemoryStore: &anthropic.BetaManagedAgentsMemoryStoreResourceParam{
			MemoryStoreID: store.ID,
			Access:        anthropic.BetaManagedAgentsMemoryStoreResourceParamAccessReadWrite,
			Instructions:  anthropic.String("User preferences and project context. Check before starting any task."),
		},
	}},
})
if err != nil {
	panic(err)
}

Java

var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addResource(
            BetaManagedAgentsMemoryStoreResourceParam.builder()
                .memoryStoreId(store.id())
                .access(BetaManagedAgentsMemoryStoreResourceParam.Access.READ_WRITE)
                .instructions("User preferences and project context. Check before starting any task.")
                .build()
        )
        .build()
);

PHP

$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $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.',
        ],
    ],
);

Ruby

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."
    }
  ]
)

警告

记忆存储默认以 read_write 访问权限附加。如果智能体处理不受信任的输入（用户提供的提示、抓取的网页内容或第三方工具输出），一次成功的提示注入可能会将恶意内容写入存储。之后的会话会将该内容作为受信任的记忆读取。对于参考资料、共享查询数据以及智能体不需要修改的任何存储，请使用 read_only。

每个会话最多支持 8 个记忆存储。当记忆的不同部分有不同的所有者或访问规则时，请附加多个存储。常见原因包括：

• 共享参考资料：一个附加到许多会话的只读存储（标准、约定、领域知识），与每个会话自己的读写存储分开
• 映射到您产品的结构：为每个最终用户、团队或项目各设一个存储，同时共享单一的智能体配置
• 不同的生命周期：一个比任何单个会话存续更久的存储，或者您希望按其自身计划进行归档的存储

智能体如何访问记忆

每个附加的存储都作为 /mnt/memory/ 下的一个目录挂载到会话的沙箱中。目录名是存储的显示名称经过清理后得到的文件系统安全 slug（转为小写；连续的非字母数字字符变为单个连字符），因此名为 “Demo Memory” 的存储会挂载在 /mnt/memory/demo-memory/。确切路径会在会话的记忆存储资源的 mount_path (java, php: mountPath; csharp, go: MountPath) 字段中返回；请从该字段读取，而不要自行构造。智能体使用标准的智能体工具集读写存储。挂载路径下的写入会持久化回存储，并在共享该存储的会话之间保持同步；写入 /mnt/memory/ 下任何其他路径都会失败，因为沙箱以只读方式挂载该父目录。每个挂载的简短描述（显示名称、挂载路径、访问模式、存储的 description (csharp, go: Description) 以及任何 instructions (csharp, go: Instructions)）会自动添加到系统提示中。

access (csharp, go: Access) 在文件系统层面强制执行：read_only 挂载会拒绝写入，而对 read_write 挂载的写入会生成归属于该会话的记忆版本。

注意

在自托管沙箱上，每个存储的目录是由 worker 管理的本地副本，而不是实时挂载。worker 会在工具调用之后将每个副本与其存储进行协调，每个同步间隔（默认 15 秒）最多一次，并在会话结束时再进行一次。智能体的 write 和 edit 工具只更改本地副本；worker 会在下一次同步时上传这些更改，因此在自托管沙箱上运行的另一个会话只有在两个 worker 都完成同步后才能看到更改。在那里，/mnt/memory/ 下存储目录之外的路径不是临时空间：worker 的文件工具会拒绝写入这些路径，而 shell 命令写入那里的任何内容都不会同步到存储。

对于 read_only 存储，worker 的 write 和 edit 工具会拒绝该目录下的更改，并且 worker 永远不会从中上传任何内容。要了解 worker 如何解决写入冲突，以及 bash 工具仍然可以在只读存储的本地副本中更改什么，请参阅只读存储和冲突。

智能体的读写操作会在事件流中显示为普通的 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 错误。

cURL

curl -s "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: agent-memory-2026-07-22"

CLI

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/"

Python

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

TypeScript

const page = await client.beta.memoryStores.memories.list(store.id, {
  path_prefix: "/"
});
for (const item of page.data) {
  console.log(item.type, item.path);
}

C#

var page = await client.Beta.MemoryStores.Memories.List(store.ID, new()
{
    PathPrefix = "/",
});
await foreach (var item in page.Paginate())
{
    var line = item.Match(
        memoryItem => $"memory  {memoryItem.Path}",
        prefixItem => $"memory_prefix  {prefixItem.Path}");
    Console.WriteLine(line);
}

Go

page, err := client.Beta.MemoryStores.Memories.List(ctx, store.ID, anthropic.BetaMemoryStoreMemoryListParams{
	PathPrefix: anthropic.String("/"),
})
if err != nil {
	panic(err)
}
for _, item := range page.Data {
	fmt.Println(item.Type, item.Path)
}

Java

var page = client.beta().memoryStores().memories().list(
    store.id(),
    MemoryListParams.builder()
        .pathPrefix("/")
        .build()
);
for (var item : page.data()) {
    item.memory().ifPresent(memoryItem -> IO.println("memory  " + memoryItem.path()));
    item.memoryPrefix().ifPresent(prefixItem -> IO.println("memory_prefix  " + prefixItem.path()));
}

PHP

$page = $client->beta->memoryStores->memories->list(
    $store->id,
    pathPrefix: '/',
);
foreach ($page->data as $item) {
    echo "{$item->type}  {$item->path}\n";
}

Ruby

page = client.beta.memory_stores.memories.list(
  store.id,
  path_prefix: "/"
)
page.data.each do |entry|
  puts "#{entry.type}  #{entry.path}"
end

有关完整参数和响应结构，请参阅列出记忆参考文档。

读取记忆

获取单条记忆会返回完整内容。

cURL

curl -s "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: agent-memory-2026-07-22"

CLI

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Python

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

TypeScript

const retrieved = await client.beta.memoryStores.memories.retrieve(mem.id, {
  memory_store_id: store.id
});
console.log(retrieved.content);

C#

var retrieved = await client.Beta.MemoryStores.Memories.Retrieve(mem.ID, new()
{
    MemoryStoreID = store.ID,
});
Console.WriteLine(retrieved.Content);

Go

retrieved, err := client.Beta.MemoryStores.Memories.Get(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryGetParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}
fmt.Println(retrieved.Content)

Java

var retrieved = client.beta().memoryStores().memories().retrieve(
    mem.id(),
    MemoryRetrieveParams.builder()
        .memoryStoreId(store.id())
        .build()
);
IO.println(retrieved.content().orElseThrow());

PHP

$retrieved = $client->beta->memoryStores->memories->retrieve($mem->id, memoryStoreID: $store->id);
echo "{$retrieved->content}\n";

Ruby

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

有关完整参数和响应结构，请参阅检索记忆参考文档。

创建记忆

POST /v1/memory_stores/{memory_store_id}/memories (python, ruby: client.beta.memory_stores.memories.create(); typescript: client.beta.memoryStores.memories.create(); go: client.Beta.MemoryStores.Memories.New(); java: client.beta().memoryStores().memories().create(); csharp: client.Beta.MemoryStores.Memories.Create(); php: $client->beta->memoryStores->memories->create(); cli: ant beta:memory-stores:memories create) 会在给定的 path (csharp, go: Path) 处创建一条记忆。创建操作不会覆盖已有内容；要更新现有记忆，请使用 POST /v1/memory_stores/{memory_store_id}/memories/{memory_id} (python, ruby: client.beta.memory_stores.memories.update(); typescript: client.beta.memoryStores.memories.update(); go, csharp: client.Beta.MemoryStores.Memories.Update(); java: client.beta().memoryStores().memories().update(); php: $client->beta->memoryStores->memories->update(); cli: ant beta:memory-stores:memories update)。

cURL

curl -s "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: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{
    "path": "/preferences/formatting.md",
    "content": "Always use tabs, not spaces."
  }'

CLI

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces."

Python

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

TypeScript

const mem = await client.beta.memoryStores.memories.create(store.id, {
  path: "/preferences/formatting.md",
  content: "Always use tabs, not spaces."
});

C#

var mem = await client.Beta.MemoryStores.Memories.Create(store.ID, new()
{
    Path = "/preferences/formatting.md",
    Content = "Always use tabs, not spaces.",
});

Go

mem, err := client.Beta.MemoryStores.Memories.New(ctx, store.ID, anthropic.BetaMemoryStoreMemoryNewParams{
	Path:    "/preferences/formatting.md",
	Content: anthropic.String("Always use tabs, not spaces."),
})
if err != nil {
	panic(err)
}

Java

var mem = client.beta().memoryStores().memories().create(
    store.id(),
    MemoryCreateParams.builder()
        .path("/preferences/formatting.md")
        .content("Always use tabs, not spaces.")
        .build()
);

PHP

$mem = $client->beta->memoryStores->memories->create(
    $store->id,
    path: '/preferences/formatting.md',
    content: 'Always use tabs, not spaces.',
);

Ruby

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

有关完整参数和响应结构，请参阅创建记忆参考文档。

更新记忆

POST /v1/memory_stores/{memory_store_id}/memories/{memory_id} (python, ruby: client.beta.memory_stores.memories.update(); typescript: client.beta.memoryStores.memories.update(); go, csharp: client.Beta.MemoryStores.Memories.Update(); java: client.beta().memoryStores().memories().update(); php: $client->beta->memoryStores->memories->update(); cli: ant beta:memory-stores:memories update) 按 ID 修改现有记忆。您可以更改 content (csharp, go: Content)、path (csharp, go: Path)（即重命名），或两者都更改。以下示例将一条记忆重命名到归档路径：

cURL

curl -s -X POST "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: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{"path": "/archive/2026_q1_formatting.md"}'

CLI

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md"

Python

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

TypeScript

await client.beta.memoryStores.memories.update(mem.id, {
  memory_store_id: store.id,
  path: "/archive/2026_q1_formatting.md"
});

C#

await client.Beta.MemoryStores.Memories.Update(mem.ID, new()
{
    MemoryStoreID = store.ID,
    Path = "/archive/2026_q1_formatting.md",
});

Go

_, err = client.Beta.MemoryStores.Memories.Update(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryUpdateParams{
	MemoryStoreID: store.ID,
	Path:          anthropic.String("/archive/2026_q1_formatting.md"),
})
if err != nil {
	panic(err)
}

Java

client.beta().memoryStores().memories().update(
    mem.id(),
    MemoryUpdateParams.builder()
        .memoryStoreId(store.id())
        .path("/archive/2026_q1_formatting.md")
        .build()
);

PHP

$client->beta->memoryStores->memories->update(
    $mem->id,
    memoryStoreID: $store->id,
    path: '/archive/2026_q1_formatting.md',
);

Ruby

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

有关完整参数和响应结构，请参阅更新记忆参考文档。

安全的内容编辑（乐观并发）

为避免覆盖并发写入，请传入 content_sha256 前置条件。只有当存储的内容哈希仍与您读取时的哈希匹配时，更新才会生效；如果不匹配，请重新读取记忆，并基于最新状态重试。

cURL

curl -s -X POST "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: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{
    "content": "CORRECTED: Always use 2-space indentation.",
    "precondition": {"type": "content_sha256", "content_sha256": "'"$mem_sha"'"}
  }'

CLI

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}"

Python

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

TypeScript

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

C#

await client.Beta.MemoryStores.Memories.Update(mem.ID, new()
{
    MemoryStoreID = store.ID,
    Content = "CORRECTED: Always use 2-space indentation.",
    Precondition = new BetaManagedAgentsPrecondition { ContentSha256 = mem.ContentSha256 },
});

Go

_, err = client.Beta.MemoryStores.Memories.Update(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryUpdateParams{
	MemoryStoreID: store.ID,
	Content:       anthropic.String("CORRECTED: Always use 2-space indentation."),
	Precondition: anthropic.BetaManagedAgentsPreconditionParam{
		ContentSha256: anthropic.String(mem.ContentSha256),
	},
})
if err != nil {
	panic(err)
}

Java

client.beta().memoryStores().memories().update(
    mem.id(),
    MemoryUpdateParams.builder()
        .memoryStoreId(store.id())
        .content("CORRECTED: Always use 2-space indentation.")
        .precondition(
            BetaManagedAgentsPrecondition.builder()
                .contentSha256(mem.contentSha256())
                .build()
        )
        .build()
);

PHP

$client->beta->memoryStores->memories->update(
    $mem->id,
    memoryStoreID: $store->id,
    content: 'CORRECTED: Always use 2-space indentation.',
    precondition: ['type' => 'content_sha256', 'content_sha256' => $mem->contentSha256],
);

Ruby

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

删除记忆

cURL

curl -s -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: agent-memory-2026-07-22"

CLI

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Python

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

TypeScript

await client.beta.memoryStores.memories.delete(mem.id, {
  memory_store_id: store.id
});

C#

await client.Beta.MemoryStores.Memories.Delete(mem.ID, new()
{
    MemoryStoreID = store.ID,
});

Go

_, err = client.Beta.MemoryStores.Memories.Delete(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryDeleteParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}

Java

client.beta().memoryStores().memories().delete(
    mem.id(),
    MemoryDeleteParams.builder()
        .memoryStoreId(store.id())
        .build()
);

PHP

$client->beta->memoryStores->memories->delete($mem->id, memoryStoreID: $store->id);

Ruby

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

有关完整参数和响应结构，请参阅删除记忆参考文档。

审计记忆更改

对记忆的每次变更都会创建一个不可变的记忆版本（memver_...）。使用版本端点可以审计谁在何时更改了什么、检查或恢复先前的快照，以及通过脱敏（redact）从历史记录中清除敏感内容。

版本属于存储（而非单条记忆），并且在记忆本身被删除时不会被删除，因此审计跟踪也涵盖已删除的记忆，但须遵守后文所述的保留规则。版本在写入后保留 30 天；不过，活动记忆的近期版本无论时间多久都会始终保留，因此不常更改的记忆可能会保留超过 30 天的历史记录。实时的 GET /v1/memory_stores/{memory_store_id}/memories/{memory_id} (python, ruby: client.beta.memory_stores.memories.retrieve(); typescript: client.beta.memoryStores.memories.retrieve(); go: client.Beta.MemoryStores.Memories.Get(); java: client.beta().memoryStores().memories().retrieve(); csharp: client.Beta.MemoryStores.Memories.Retrieve(); php: $client->beta->memoryStores->memories->retrieve(); cli: ant beta:memory-stores:memories retrieve) 调用始终返回最新版本；版本端点则为您提供保留的历史记录。

没有专门的恢复端点；要回滚，请检索您想要的版本，并使用 POST /v1/memory_stores/{memory_store_id}/memories/{memory_id} (python, ruby: client.beta.memory_stores.memories.update(); typescript: client.beta.memoryStores.memories.update(); go, csharp: client.Beta.MemoryStores.Memories.Update(); java: client.beta().memoryStores().memories().update(); php: $client->beta->memoryStores->memories->update(); cli: ant beta:memory-stores:memories update) 将其 content (csharp, go: Content) 写回（如果父记忆已被删除，则使用 POST /v1/memory_stores/{memory_store_id}/memories (python, ruby: client.beta.memory_stores.memories.create(); typescript: client.beta.memoryStores.memories.create(); go: client.Beta.MemoryStores.Memories.New(); java: client.beta().memoryStores().memories().create(); csharp: client.Beta.MemoryStores.Memories.Create(); php: $client->beta->memoryStores->memories->create(); cli: ant beta:memory-stores:memories create)，前提是您想要的版本仍被保留）。

过去的记忆版本可能会在 30 天后被删除。要更长时间地保留记忆历史，请通过 API 导出版本。

列出版本

列出存储的版本历史，最新的在前。以下示例筛选出单条记忆的历史：

cURL

curl -s "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: agent-memory-2026-07-22"

CLI

ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json

Python

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

TypeScript

const versions = await client.beta.memoryStores.memoryVersions.list(store.id, {
  memory_id: mem.id
});
for await (const memoryVersion of versions) {
  console.log(`${memoryVersion.id}: ${memoryVersion.operation}`);
}

const versionId = versions.data[1].id;

C#

var versions = await client.Beta.MemoryStores.MemoryVersions.List(store.ID, new()
{
    MemoryID = mem.ID,
});
var versionIds = new List<string>();
await foreach (var memoryVersion in versions.Paginate())
{
    Console.WriteLine($"{memoryVersion.ID}: {memoryVersion.Operation.Raw()}");
    versionIds.Add(memoryVersion.ID);
}

var versionId = versionIds[1];

Go

versions := client.Beta.MemoryStores.MemoryVersions.ListAutoPaging(ctx, store.ID, anthropic.BetaMemoryStoreMemoryVersionListParams{
	MemoryID: anthropic.String(mem.ID),
})
for versions.Next() {
	memoryVersion := versions.Current()
	fmt.Printf("%s: %s\n", memoryVersion.ID, memoryVersion.Operation)
}
if err := versions.Err(); err != nil {
	panic(err)
}

vpage, err := client.Beta.MemoryStores.MemoryVersions.List(ctx, store.ID, anthropic.BetaMemoryStoreMemoryVersionListParams{
	MemoryID: anthropic.String(mem.ID),
})
if err != nil {
	panic(err)
}
versionID := vpage.Data[1].ID

Java

var versions = client.beta().memoryStores().memoryVersions().list(
    store.id(),
    MemoryVersionListParams.builder()
        .memoryId(mem.id())
        .build()
);
for (var memoryVersion : versions.autoPager()) {
    IO.println(memoryVersion.id() + ": " + memoryVersion.operation());
}

var versionId = versions.data().get(1).id();

PHP

$versions = $client->beta->memoryStores->memoryVersions->list(
    $store->id,
    memoryID: $mem->id,
);
foreach ($versions->pagingEachItem() as $memoryVersion) {
    echo "{$memoryVersion->id}: {$memoryVersion->operation}\n";
}

$versionId = $versions->data[1]->id;

Ruby

versions = client.beta.memory_stores.memory_versions.list(
  store.id,
  memory_id: mem.id
)
versions.auto_paging_each do |version|
  puts "#{version.id}: #{version.operation}"
end

version_id = versions.data[1].id

有关完整参数和响应结构，请参阅列出记忆版本参考文档。

检索版本

获取单个版本会返回与列表响应相同的字段，外加完整的 content (csharp, go: Content) 正文。

cURL

curl -s "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: agent-memory-2026-07-22"

CLI

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Python

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

TypeScript

const version = await client.beta.memoryStores.memoryVersions.retrieve(versionId, {
  memory_store_id: store.id
});
console.log(version.content);

C#

var version = await client.Beta.MemoryStores.MemoryVersions.Retrieve(versionId, new()
{
    MemoryStoreID = store.ID,
});
Console.WriteLine(version.Content);

Go

version, err := client.Beta.MemoryStores.MemoryVersions.Get(ctx, versionID, anthropic.BetaMemoryStoreMemoryVersionGetParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}
fmt.Println(version.Content)

Java

var version = client.beta().memoryStores().memoryVersions().retrieve(
    versionId,
    MemoryVersionRetrieveParams.builder()
        .memoryStoreId(store.id())
        .build()
);
IO.println(version.content().orElseThrow());

PHP

$version = $client->beta->memoryStores->memoryVersions->retrieve(
    $versionId,
    memoryStoreID: $store->id,
);
echo "{$version->content}\n";

Ruby

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

有关完整参数和响应结构，请参阅检索记忆版本参考文档。

脱敏版本

脱敏会从历史版本中清除内容，同时保留审计跟踪（谁在何时做了什么）。可将其用于合规工作流，例如移除泄露的密钥、个人身份信息（PII）或处理用户删除请求。

作为活动记忆当前头部的版本无法被脱敏。请先写入一个新版本（或删除该记忆），然后再对旧版本进行脱敏。

cURL

curl -s -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: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{}'

CLI

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Python

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

TypeScript

await client.beta.memoryStores.memoryVersions.redact(versionId, {
  memory_store_id: store.id
});

C#

await client.Beta.MemoryStores.MemoryVersions.Redact(versionId, new()
{
    MemoryStoreID = store.ID,
});

Go

_, err = client.Beta.MemoryStores.MemoryVersions.Redact(ctx, versionID, anthropic.BetaMemoryStoreMemoryVersionRedactParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}

Java

client.beta().memoryStores().memoryVersions().redact(
    versionId,
    MemoryVersionRedactParams.builder()
        .memoryStoreId(store.id())
        .build()
);

PHP

$client->beta->memoryStores->memoryVersions->redact(
    $versionId,
    memoryStoreID: $store->id,
);

Ruby

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

有关完整参数和响应模式，请参阅脱敏记忆版本参考。

管理记忆存储

除了 create 之外，记忆存储还支持 retrieve、update、list、archive 和 delete。

列出存储

列出工作区中的存储。默认情况下不包括已归档的存储；将 include_archived (java, php: includeArchived; csharp, go: IncludeArchived) 设置为 true 即可包含它们。

cURL

curl -s "https://api.anthropic.com/v1/memory_stores?include_archived=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22"

CLI

ant beta:memory-stores list --include-archived

Python

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

TypeScript

for await (const memoryStore of client.beta.memoryStores.list({ include_archived: true })) {
  console.log(memoryStore.id, memoryStore.name, memoryStore.archived_at);
}

C#

var stores = await client.Beta.MemoryStores.List(new() { IncludeArchived = true });
await foreach (var memoryStore in stores.Paginate())
{
    Console.WriteLine($"{memoryStore.ID} {memoryStore.Name} {memoryStore.ArchivedAt}");
}

Go

stores := client.Beta.MemoryStores.ListAutoPaging(ctx, anthropic.BetaMemoryStoreListParams{
	IncludeArchived: anthropic.Bool(true),
})
for stores.Next() {
	memoryStore := stores.Current()
	fmt.Println(memoryStore.ID, memoryStore.Name, memoryStore.ArchivedAt)
}
if err := stores.Err(); err != nil {
	panic(err)
}

Java

for (var memoryStore : client.beta().memoryStores().list(
    MemoryStoreListParams.builder()
        .includeArchived(true)
        .build()
).autoPager()) {
    IO.println(memoryStore.id() + " " + memoryStore.name() + " " + memoryStore.archivedAt());
}

PHP

foreach ($client->beta->memoryStores->list(includeArchived: true)->pagingEachItem() as $memoryStore) {
    // archivedAt 仅在已归档的存储上设置。
    $archivedAt = isset($memoryStore->archivedAt) ? $memoryStore->archivedAt->format(DATE_ATOM) : '';
    echo "{$memoryStore->id} {$memoryStore->name} {$archivedAt}\n";
}

Ruby

client.beta.memory_stores.list(include_archived: true).auto_paging_each do |memory_store|
  puts "#{memory_store.id} #{memory_store.name} #{memory_store.archived_at}"
end

有关完整参数和响应结构，请参阅列出记忆存储参考文档。

归档存储

归档会使存储变为只读，并阻止其被附加到新会话。归档是单向的；没有取消归档操作。

cURL

curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22"

CLI

ant beta:memory-stores archive --memory-store-id "$store_id"

Python

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

TypeScript

await client.beta.memoryStores.archive(store.id);

C#

await client.Beta.MemoryStores.Archive(store.ID);

Go

_, err = client.Beta.MemoryStores.Archive(ctx, store.ID, anthropic.BetaMemoryStoreArchiveParams{})
if err != nil {
	panic(err)
}

Java

client.beta().memoryStores().archive(store.id());

PHP

$client->beta->memoryStores->archive($store->id);

Ruby

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

有关完整参数和响应结构，请参阅归档记忆存储参考文档。

要永久删除存储及其所有记忆和版本，请调用 DELETE /v1/memory_stores/{memory_store_id} (python, ruby: client.beta.memory_stores.delete(); typescript: client.beta.memoryStores.delete(); go, csharp: client.Beta.MemoryStores.Delete(); java: client.beta().memoryStores().delete(); php: $client->beta->memoryStores->delete(); cli: ant beta:memory-stores delete)。

记忆管理最佳实践

当存储达到 10,000 条记忆的上限时，写入新记忆的操作会失败：包括直接的 POST /v1/memory_stores/{memory_store_id}/memories (python, ruby: client.beta.memory_stores.memories.create(); typescript: client.beta.memoryStores.memories.create(); go: client.Beta.MemoryStores.Memories.New(); java: client.beta().memoryStores().memories().create(); csharp: client.Beta.MemoryStores.Memories.Create(); php: $client->beta->memoryStores->memories->create(); cli: ant beta:memory-stores:memories create) 调用，以及智能体对未映射路径的文件写入。现有记忆仍可读取和编辑。以下实践可帮助您远低于该上限，并在达到上限时从容恢复。

• 使用专注的存储。与其使用一个大型通用存储，不如使用更小的专用存储：每个用户一个，共享领域知识一个，项目特定上下文一个。每个存储都有各自 10,000 条记忆的上限，因此限定存储范围可以降低任何单个存储被填满的可能性。

• 在存储填满之前进行精简或清理。使用 DELETE /v1/memory_stores/{memory_store_id}/memories/{memory_id} (python, ruby: client.beta.memory_stores.memories.delete(); typescript: client.beta.memoryStores.memories.delete(); go, csharp: client.Beta.MemoryStores.Memories.Delete(); java: client.beta().memoryStores().memories().delete(); php: $client->beta->memoryStores->memories->delete(); cli: ant beta:memory-stores:memories delete) 删除过时或冗余的记忆。您还可以运行一个梦境会话，它会将零散的内容整合到一个单独的新输出存储中，而不是修改原始存储。将您的会话切换到该输出存储，然后归档或删除原始存储。

• 在合适的时候附加新存储。如果某个存储已经超出其有用范围，请为新内容附加一个全新的存储，并以 read_only 访问权限附加原始存储。智能体可以从两者读取，同时只写入新存储。

• 在适当的情况下限制写入权限。仅读取共享参考资料的会话不需要 read_write。将写入权限限定在实际添加新记忆的会话上，可以更容易地追踪增长的来源。

可用性

记忆存储在所有模型上处于 beta 阶段。

API 支持

Managed Agents

• 可用性：可用

状态	云平台
Beta1	Claude API
Beta2	Claude Platform on AWS
Beta3	Claude Models on Google Cloud (Anthropic managed)

1. 在记忆存储调用中同时发送 managed-agents-2026-04-01 和 agent-memory-2026-07-22 会返回 400 错误。
2. 在 Claude Platform on AWS 上，自托管环境中的会话无法附加记忆存储。在记忆存储调用中同时发送 managed-agents-2026-04-01 和 agent-memory-2026-07-22 会返回 400 错误。
3. 在 Claude Models on Google Cloud (Anthropic managed) 上，自托管环境中的会话不支持记忆存储。在记忆存储调用中同时发送 managed-agents-2026-04-01 和 agent-memory-2026-07-22 会返回 400 错误。

所需的 beta 请求头

Beta 请求头概览

Beta 请求头让您可以在实验性功能和新模型能力成为标准 API 的一部分之前访问它们。

• agent-memory-2026-07-22

数据处理

数据处理概览

项目	零数据保留	HIPAA
状态	不具备资格	不具备资格
详细信息	会话是有状态的资源；对话记录会一直保留，直到您将其删除。适用于所有 Managed Agents 子功能，包括自托管沙箱。	适用于所有 Managed Agents 子功能，包括自托管沙箱。

适用的端点：

• /v1/agents
• /v1/sessions
• /v1/environments