HTTP API

使用 HTTP API 从不在 Cloudflare Workers 内部运行的服务中调用 Agent Memory。对于 Workers 应用程序，请通过 agent_memory 绑定使用 Workers API。

HTTP API 使用命名空间和配置文件。命名空间限制了您的应用程序配置文件的范围，每个配置文件都是一个隔离的内存存储。当您第一次写入配置文件时，它们会自动创建。

身份验证

所有请求都需要一个带有适当 Agent Memory 权限的 API 令牌。

在 Authorization 标头中包含您的 API 令牌：

Authorization: Bearer <API_TOKEN>

有关调用 Cloudflare API 的详细信息，请参阅发起 API 调用。

命名空间管理

命名空间 (Namespace) 是范围限定您应用程序的内存配置文件的顶级容器。

创建命名空间

为给定的账户创建一个新的命名空间。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "support-agent"}'

响应中包含您在 Worker 绑定和 HTTP API 调用中使用的命名空间名称。

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"name": "support-agent",
		"created_at": "2026-04-21T00:00:00.000Z",
		"updated_at": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

列出命名空间

列出给定账户的所有命名空间。结果分页返回。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces?per_page=50" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": [
		{
			"id": "01JSGCEXAMPLE000000000000",
			"name": "support-agent",
			"created_at": "2026-04-21T00:00:00.000Z",
			"updated_at": "2026-04-21T00:00:00.000Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"cursor": "next-cursor",
		"per_page": 50,
		"count": 1
	}
}

获取命名空间

通过名称检索单个命名空间。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"name": "support-agent",
		"created_at": "2026-04-21T00:00:00.000Z",
		"updated_at": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

删除命名空间

将命名空间标记为删除。删除后，命名空间名称将可重新使用。

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

配置文件

使用配置文件端点来管理配置文件，并在命名配置文件中存储的内存上进行操作。当您第一次写入配置文件时，它们会自动创建。

删除配置文件

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

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

删除会话

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

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/sessions/<SESSION_ID>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

摄取消息

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

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/ingest" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I prefer concise answers.",
        "timestamp": "2026-04-21T00:00:00.000Z"
      }
    ],
    "sessionId": "chat-2026-04-21"
  }'

{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

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

记住一条内存

显式存储单个内存。当您的应用程序或 Agent 已经知道什么应该被存储时，使用 remember。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/remember" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user prefers concise answers.",
    "sessionId": "chat-2026-04-21"
  }'

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"type": "instruction",
		"summary": "The user prefers concise answers.",
		"content": "The user prefers concise answers.",
		"sessionId": "chat-2026-04-21",
		"createdAt": "2026-04-21T00:00:00.000Z",
		"updatedAt": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

召回内存

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

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/recall" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How should I answer this user?",
    "thinkingLevel": "low",
    "responseLength": "medium"
  }'

{
	"result": {
		"answer": "The user prefers concise answers.",
		"count": 1,
		"candidates": [
			{
				"id": "01JSGCEXAMPLE000000000000",
				"summary": "The user prefers concise answers.",
				"sessionId": "chat-2026-04-21",
				"score": 0.87
			}
		]
	},
	"success": true,
	"errors": [],
	"messages": []
}

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

列出内存

列出存储在配置文件中的内存。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/memories?per_page=50" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": [
		{
			"id": "01JSGCEXAMPLE000000000000",
			"type": "instruction",
			"summary": "The user prefers concise answers.",
			"sessionId": "chat-2026-04-21",
			"createdAt": "2026-04-21T00:00:00.000Z",
			"updatedAt": "2026-04-21T00:00:00.000Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"cursor": "next-cursor",
		"per_page": 50,
		"count": 1
	}
}

列表条目省略了 content。使用获取内存端点来检索完整的内存。

若要过滤内存，请使用 session_id 和 type 查询参数。

获取一条内存

通过 ID 检索一条内存。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/memories/<MEMORY_ID>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"type": "instruction",
		"summary": "The user prefers concise answers.",
		"content": "The user prefers concise answers.",
		"sessionId": "chat-2026-04-21",
		"createdAt": "2026-04-21T00:00:00.000Z",
		"updatedAt": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

删除一条内存

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

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/memories/<MEMORY_ID>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
	"result": {
		"id": "01JSGCEXAMPLE000000000000",
		"type": "instruction",
		"summary": "The user prefers concise answers.",
		"content": "The user prefers concise answers.",
		"sessionId": "chat-2026-04-21",
		"createdAt": "2026-04-21T00:00:00.000Z",
		"updatedAt": "2026-04-21T00:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

获取摘要

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

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/agent-memory/namespaces/<NAMESPACE_NAME>/profiles/<PROFILE_NAME>/summary" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

{
	"result": {
		"summary": "## Summary\n\nThe user prefers concise answers."
	},
	"success": true,
	"errors": [],
	"messages": []
}

为了限制摘要“上一次会话 (Last Session)”部分的范围，请在请求体中包含 sessionId 字段。

错误响应

所有端点在失败时都会返回标准的 Cloudflare V4 错误响应：

{
	"result": null,
	"success": false,
	"errors": [
		{
			"code": 10008,
			"message": "Namespace name already exists"
		}
	],
	"messages": []
}

常见的错误场景包括：

场景	HTTP 状态码
无效的命名空间名称格式	`400`
身份验证失败	`401`
命名空间名称已存在	`409`
找不到命名空间	`404`
找不到配置文件	`404`