AI Platform Docs
API

API Memory Service

Спецификация программных интерфейсов управляемого сервиса памяти агентов Платформы ИИ.

Общие сведения

API Memory Service совместим с контрактом mem0. Публичные маршруты начинаются с /v1/. Аутентификация выполняется через JWT платформы; user_id извлекается из токена, а не из тела запроса.

Каждая защищённая операция проходит проверку прав через SpiceDB (fail-closed). Операции записи регистрируются в immutable audit log платформы.

Формат ошибок

Все ошибки возвращают объект:

{
  "error": "string",
  "message": "string",
  "details": {}
}

Эндпоинты

POST /v1/memories — Добавить память

Добавляет память из сообщений диалога. Извлечение фактов выполняется асинхронно через очередь RabbitMQ. Возвращает event_id для отслеживания статуса.

Тело запроса — AddMemoryRequest

ПолеТипОбязательноОписание
messagesarrayДаМассив сообщений с полями role и content
agent_idstringДа (если нет run_id)Идентификатор агента
run_idstringДа (если нет agent_id)Идентификатор запуска
inferbooleanНетtrue — LLM-извлечение (по умолчанию); false — прямой импорт
metadataobjectНетПроизвольные метаданные записи
expiration_datestringНетДата окончания срока хранения (YYYY-MM-DD)
custom_instructionsstringНетИнструкции извлечения на вызов
promptstringНетАлиас custom_instructions (совместимость с mem0)

Ответ 202 — AddMemoryResponse

{
  "event_id": "uuid",
  "status": "PENDING"
}

Пример

POST /v1/memories
{
  "messages": [
    {"role": "user", "content": "Я работаю в отделе закупок, отчёты нужны в xlsx"},
    {"role": "assistant", "content": "Понял, буду присылать xlsx"}
  ],
  "agent_id": "procurement-assistant-v1",
  "run_id": "01J9X2K7...",
  "infer": true,
  "metadata": {"source": "chat"}
}
→ 202 Accepted
{"event_id": "01J9X2K8...", "status": "PENDING"}

POST /v1/memories/search — Поиск памяти

Мультисигнальный поиск по запросу с фильтрами, ранжированием и бюджетом токенов. Выполняется синхронно.

Тело запроса — SearchMemoriesRequest

ПолеТипОбязательноОписание
querystringДаТекст запроса
filtersobjectДаФильтры (scope + составные условия)
top_kintegerНетКоличество результатов (1–200, по умолчанию 20)
token_budgetintegerНетЛимит токенов в результатах
thresholdnumberНетМинимальный порог сходства (0–1, по умолчанию 0.1)
explainbooleanНетВключить детали оценок score_details
show_expiredbooleanНетПоказывать истёкшие записи (по умолчанию false)
reference_datestring или integerНетЯкорь для темпорального ранжирования

Фильтры

Минимум один entity-скоуп обязателен (agent_id или run_id). user_id доступен только для admin/compliance.

{
  "AND": [
    {"agent_id": "procurement-assistant-v1"},
    {"categories": {"in": ["preferences"]}}
  ]
}

Ответ 200 — SearchMemoriesResponse

{
  "results": [
    {
      "id": "uuid",
      "memory": "Предпочитает отчёты в формате xlsx",
      "categories": ["preferences"],
      "score": 0.91,
      "score_details": {
        "semantic": 0.93,
        "bm25": 0.88
      },
      "created_at": "2026-07-01T10:12:00Z",
      "valid_from": "2026-07-01"
    }
  ],
  "tokens_returned": 312
}

Пример

POST /v1/memories/search
{
  "query": "в каком формате присылать отчёт",
  "filters": {
    "AND": [
      {"agent_id": "procurement-assistant-v1"},
      {"categories": {"in": ["preferences"]}}
    ]
  },
  "top_k": 20,
  "token_budget": 4000
}
→ 200 OK
{
  "results": [...],
  "tokens_returned": 312
}

GET /v1/memories — Список памяти

Возвращает список фактов по фильтрам. Обязателен минимум один скоуп.

Параметры запроса

ПолеТипОбязательноОписание
agent_idstringНетИдентификатор агента
run_idstringНетИдентификатор запуска
top_kintegerНетМаксимум записей (1–1000, по умолчанию 100)
pageintegerНетНомер страницы (по умолчанию 1)
page_sizeintegerНетРазмер страницы (1–100, по умолчанию 100)
show_expiredbooleanНетПоказывать истёкшие записи (по умолчанию false)
categoriesarrayНетФильтр по категориям

Ответ 200 — ListMemoriesResponse

{
  "count": 42,
  "next": "https://api.example.com/v1/memories?page=2",
  "previous": null,
  "results": [
    {
      "id": "uuid",
      "memory": "Предпочитает отчёты в формате xlsx",
      "agent_id": "procurement-assistant-v1",
      "created_at": "2026-07-01T10:12:00Z"
    }
  ]
}

GET /v1/memories/memory_id — Одна запись

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

Параметры пути

ПолеТипОбязательноОписание
memory_idstringДаUUID записи памяти

Ответ 200 — MemoryItem

{
  "id": "uuid",
  "memory": "Предпочитает отчёты в формате xlsx",
  "user_id": "user-123",
  "agent_id": "procurement-assistant-v1",
  "categories": ["preferences"],
  "score": null,
  "hash": "sha256-...",
  "created_at": "2026-07-01T10:12:00Z",
  "updated_at": "2026-07-02T14:30:00Z",
  "role": "user"
}

PUT /v1/memories/memory_id — Изменить запись

Изменяет текст или метаданные существующей записи.

Тело запроса — UpdateMemoryRequest

ПолеТипОбязательноОписание
textstringНетНовый текст факта
metadataobjectНетНовые метаданные
expiration_datestring или nullНетНовая дата окончания срока; null — снять

Ответ 200 — MemoryItem

DELETE /v1/memories/memory_id — Удалить запись

Удаляет одну запись (soft-delete).

Параметры запроса

ПолеТипОбязательноОписание
delete_linkedbooleanНетУдалить связанные записи (по умолчанию false)

Ответ 200 — DeleteMemoryResponse

{
  "message": "Memory deleted successfully"
}

DELETE /v1/memories — Удалить по фильтру

Удаляет все записи, соответствующие фильтру. Используется для реализации права на забвение.

Параметры запроса

ПолеТипОбязательноОписание
user_idstringНетИдентификатор субъекта (из JWT)
agent_idstringНетИдентификатор агента
run_idstringНетИдентификатор запуска

Ответ 200 — DeleteAllMemoriesResponse

{
  "message": "All relevant memories deleted",
  "deleted_count": 5,
  "confirmation_id": "uuid"
}

GET /v1/memories/memory_id/history — История записи

Возвращает историю изменений одной записи памяти.

Параметры пути

ПолеТипОбязательноОписание
memory_idstringДаUUID записи памяти

Ответ 200 — MemoryHistoryResponse

[
  {
    "id": "uuid",
    "memory_id": "uuid",
    "old_memory": "Отчёты в PDF",
    "new_memory": "Отчёты в xlsx",
    "event": "UPDATE",
    "created_at": "2026-07-02T14:30:00Z",
    "is_deleted": false
  }
]

GET /v1/events/event_id — Статус события

Возвращает статус асинхронной обработки добавления памяти.

Параметры пути

ПолеТипОбязательноОписание
event_idstringДаUUID события

Ответ 200 — EventResponse

{
  "event_id": "uuid",
  "status": "SUCCEEDED",
  "memory_ids": ["uuid-1", "uuid-2"],
  "created_at": "2026-07-01T10:00:00Z",
  "updated_at": "2026-07-01T10:00:05Z"
}

Статусы: PENDING, SUCCEEDED, FAILED. При FAILED возвращается поле error.

POST /v1/sessions/session_id/state — Сохранить состояние сессии

Сохраняет рабочую память / чекпоинт сессии.

Тело запроса — PutSessionStateRequest

ПолеТипОбязательноОписание
stateobject или stringДаПрозрачный чекпоинт (JSON или base64)
agent_idstringНетИдентификатор агента
run_idstringНетИдентификатор запуска
ttl_secondsintegerНетВремя жизни (60–2592000, по умолчанию 86400)

Ответ 200 — SessionStateResponse

{
  "session_id": "uuid",
  "state": {"key": "value"},
  "updated_at": "2026-07-01T10:00:00Z",
  "ttl_remaining_seconds": 82800
}

GET /v1/sessions/session_id/state — Восстановить состояние сессии

Восстанавливает рабочую память / чекпоинт сессии.

Параметры запроса

ПолеТипОбязательноОписание
agent_idstringНетИдентификатор агента

Ответ 200 — SessionStateResponse

Ответ 404 — Error — состояние не найдено

Интерфейсы Control plane

Предыдущая страница

Интерфейсы RAG

Следующая страница

На этой странице

Общие сведенияФормат ошибокЭндпоинтыPOST /v1/memories — Добавить памятьPOST /v1/memories/search — Поиск памятиGET /v1/memories — Список памятиGET /v1/memories/memory_id — Одна записьPUT /v1/memories/memory_id — Изменить записьDELETE /v1/memories/memory_id — Удалить записьDELETE /v1/memories — Удалить по фильтруGET /v1/memories/memory_id/history — История записиGET /v1/events/event_id — Статус событияPOST /v1/sessions/session_id/state — Сохранить состояние сессииGET /v1/sessions/session_id/state — Восстановить состояние сессии