Workers API

使用 Workers API 从您的 Worker 访问 Agent Memory。此绑定将您的 Worker 连接到一个包含配置文件的命名空间 (Namespace)，配置文件是为您 Agent 提供的隔离内存存储。

在您的 Wrangler 配置中添加一个 agent_memory 项。binding 字段是您在 Worker 代码中使用的变量名称，而 namespace 字段是绑定的 Agent Memory 命名空间。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "agent_memory": [
    {
      "binding": "MEMORY",
      "namespace": "<NAMESPACE_NAME>"
    }
  ]
}

[[agent_memory]]
binding = "MEMORY"
namespace = "<NAMESPACE_NAME>"

要绑定多个命名空间，请向 agent_memory 数组中添加多个项。

运行 npx wrangler types 在 worker-configuration.d.ts 中生成绑定类型：

interface Env {
	MEMORY: AgentMemoryNamespace;
}

使用绑定上的命名空间方法来访问和管理内存配置文件。

按名称获取内存配置文件。如果该配置文件不存在，Agent Memory 会自动创建它。

• profileName stringrequired: 要访问的配置文件名称。最大 100 个字符。
• 返回 Promise<AgentMemoryProfile>

对于新配置文件的第一次 getProfile() 调用可能会花费较长时间，因为 Agent Memory 正在创建该配置文件。

将一个配置文件及其所有的内存和消息标记为删除。

• profileName stringrequired: 要删除的配置文件名称。最大 100 个字符。
• 返回 Promise<void>

在从绑定中获取配置文件后调用这些配置文件方法。

type AgentMemoryMemory = {
	id: string;
	type: "fact" | "event" | "instruction" | "task";
	summary: string;
	content: string;
	sessionId: string | null;
	createdAt: Date;
	updatedAt: Date;
};

处理对话并从中提取结构化内存。Agent Memory 会自动识别事实、事件、指令和任务，因此您无需指定要记住的内容。

• messages Iterable<AgentMemoryMessage>required: 要处理的对话消息。
• options.sessionId string | nulloptional: 对话会话的标识符。最大 64 个字符。如果省略，Agent Memory 会根据消息内容派生一个。
• 返回 Promise<void>

type AgentMemoryMessage = {
	role: "system" | "user" | "assistant";
	content: string; // 最大 32 KB
	timestamp?: Date;
};

ingest() 是幂等的。重新摄取相同的对话不会创建重复的内存。

显式存储单个内存。当您的应用程序或 Agent 已经知道什么应该被存储时，使用 remember()，而不是将对话传递给 ingest() 进行提取。

• memory.content stringrequired: 要存储的内存内容。该服务会自动进行分类和总结。
• memory.sessionId string | nulloptional: 相关对话会话的标识符。
• 返回 Promise<AgentMemoryMemory>

搜索配置文件中存储的内存，并返回基于所存储内容合成的回答。

• query stringrequired: 自然语言问题或搜索查询。最大 1 KB (1,024 字节 UTF-8)。
• options.thinkingLevel "low" | "medium" | "high"optional (default: "low"): 控制检索宽度。更高的级别会搜索更多的候选，但用时较长。
• options.responseLength "short" | "medium" | "long"optional (default: "medium"): 控制合成回答的详细程度。
• options.referenceDate Date | stringoptional: 日期相对查询的时间锚点。
• 返回 Promise<AgentMemoryRecallResult>

type AgentMemoryRecallResult = {
	count: number;
	answer: string;
	candidates: AgentMemoryScoredCandidate[];
};

type AgentMemoryScoredCandidate = {
	id: string;
	summary: string;
	sessionId: string | null;
	score: number;
};

如果没有内存与查询相匹配，recall() 会返回一个空回答。

列出配置文件中存储的内存。返回所存储内存的分页、可过滤视图。使用返回的 cursor（存在时）来获取下一页。

• options.limit numberoptional (default: 20, max: 500): 要返回的内存的最大数量。
• options.cursor stringoptional: 来自上一页的不透明游标。
• options.sessionId stringoptional: 精确匹配的会话过滤器。
• options.type "fact" | "event" | "instruction" | "task"optional: 精确匹配的内存类型过滤器。
• 返回 Promise<AgentMemoryListMemoriesResult>

type AgentMemoryMemoryListEntry = Omit<AgentMemoryMemory, "content">;

type AgentMemoryListMemoriesResult = {
	memories: AgentMemoryMemoryListEntry[];
	cursor?: string;
};

列表条目省略了 content。使用 get(memoryId) 来检索完整的内存。

通过 ID 检索一条内存。

• memoryId stringrequired: 内存 ID。
• 返回 Promise<AgentMemoryMemory>

如果内存不存在，则抛出错误。

通过 ID 删除一条内存。删除该内存以及与其链接的任何源消息。返回被删除的内存。

• memoryId stringrequired: 内存 ID。
• 返回 Promise<AgentMemoryMemory>

如果内存不存在，则抛出错误。

将配置文件中所有标记有给定会话 ID 的内存和消息标记为删除。同一个配置文件中其他会话的行不受影响。幂等：删除没有行的会话 ID 是一个空操作。

• sessionId stringrequired: 要删除的会话 ID。最大 64 个字符。
• 返回 Promise<void>

生成一个存储在内存配置文件中的所有内容的结构化 Markdown 摘要。使用它来检查 Agent Memory 记住了关于配置文件的哪些内容。

• options.sessionId string | nulloptional: 限制摘要“上一次会话 (Last Session)”部分范围的会话 ID。如果省略，Agent Memory 会使用最近的会话。
• 返回 Promise<AgentMemoryGetSummaryResponse>

type AgentMemoryGetSummaryResponse = {
	summary: string;
};

请参阅限制以查看完整的约束列表。