← Agent Memory / agent-memory / api

HTTP API

Используйте HTTP API, чтобы вызывать Agent Memory из служб, которые не выполняются внутри Cloudflare Workers. Для приложений на Workers используйте API Workers через agent_memory привязку.

HTTP API использует пространства имён и профили. Пространство имён задаёт область действия профилей вашего приложения, а каждый профиль представляет собой изолированное хранилище памяти. Профили создаются автоматически при первой записи в них.

Аутентификация

Для всех запросов требуется API-токен с соответствующими правами доступа Agent Memory.

Укажите свой API токен в Authorization заголовок:

Authorization: Bearer <API_TOKEN>

Сведения о вызове Cloudflare API см. в Выполняйте вызовы API.

Управление пространствами имён

A пространство имён это контейнер верхнего уровня, который определяет область профилей памяти для вашего приложения.

Создание пространства имён

Создаёт новое пространство имён для указанного аккаунта.

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": []
}

Удаление сессии

Помечает для удаления все воспоминания и сообщения в профиле, помеченные указанным идентификатором сессии. Записи других сессий в том же профиле не затрагиваются. Операция идемпотентна: удаление идентификатора сессии, для которого нет записей, ничего не делает.

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 идемпотентен. Повторная загрузка того же разговора не создаёт дублирующиеся записи памяти.

Сохранение воспоминания

Явно сохраняет одно воспоминание. Используйте 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 параметры запроса.

Получение записи

Возвращает воспоминание по идентификатору.

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": []
}

Удаление записи

Удаляет запись по идентификатору. Удаляет саму запись и все связанные с ней исходные сообщения. Возвращает удалённую запись.

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`