Справочник API: долговременная память
Управление долговременной памятью текущего вызывающего, темами и предпочтениями по документам, а также конфигурацией памяти уровня пространства. Пути используют префикс /api/v1.
Все персональные эндпоинты требуют Viewer+, а API-ключ должен быть full-access. Область действия определяется из учётных данных, произвольный subject_id не принимается. В примерах $BASE — адрес сервиса, $TOKEN — Bearer-токен текущего пользователя.
Конфигурация пространства и переключатели запросов
Конфигурация пространства использует GET/PUT /tenants/kv/memory-config, а не эндпоинт обновления имени/описания тенанта. Для чтения требуется Viewer+, для записи — Admin+, API-ключ должен иметь manage_tenant_settings или full-access. Ответ — {success,data:MemoryConfig}, в PUT передаётся объект конфигурации напрямую; персональный PUT /memory/settings не заменяет переключатель пространства.
curl -X PUT "$BASE/api/v1/tenants/kv/memory-config" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"enabled":true,"write_mode":"explicit_only","max_items":200}'Поля memory_config: enabled, write_mode (explicit_only/auto), extract_model_id, max_items, extract_delay_seconds, extract_min_interval_seconds, extract_instructions, interest_threshold, embedding_model_id, vector_recall, retrieval_conditioning. Семантику см. в Долговременная память. При обновлении передавайте полный объект конфигурации, который нужно сохранить.
Если CustomAgentConfig.memory_enabled опущено, наследуется пространство; false запрещает этому агенту использовать память; IM/Embed используют конфигурацию привязанного агента, а текущая структура канала не имеет отдельного поля memory_enabled.
Персональные настройки
| Метод | Путь | Запрос / Ответ |
|---|---|---|
| GET | /memory/settings | {success,data:{workspace_enabled,user_enabled,effective,write_mode,item_count,max_items}} |
| PUT | /memory/settings | {"enabled":true}, enabled обязателен; возвращает обновлённые settings |
effective — результат объединения переключателей пространства и пользователя; отдельный чат дополнительно ограничен переключателем агента.
curl -X PUT "$BASE/api/v1/memory/settings" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"enabled":true}'Записи
| Метод | Путь | Запрос / Ответ |
|---|---|---|
| GET | /memory/items | необязательные status, limit, offset; {success,data:[MemoryItem],total} |
| POST | /memory/items | {kind,content,importance}; 200 {success,data:MemoryItem} |
| PUT | /memory/items/:id | {content,importance}; 200 {success,data:MemoryItem} |
| DELETE | /memory/items/:id | 200 {"success":true} |
| POST | /memory/items/:id/confirm | 200 {success,data:MemoryItem}; если вывод устарел или его основание было изменено, возвращается 409 |
| POST | /memory/items/:id/reject | 200 {"success":true} |
| DELETE | /memory/items | очищает текущую личность; 200 {success,removed} |
status может быть active, pending, superseded, archived; при пропуске фильтрация не применяется. limit по умолчанию 50, допустимый диапазон 1–200, при выходе за границы используется 50; offset по умолчанию 0, отрицательное значение приводится к нулю. kind — profile/preference/fact/task/interest; содержимое — краткая память длиной до 300 символов, importance используется для сортировки по важности.
MemoryItem включает id, kind, content, topic, importance, origin, status, source_session_id, source_message_id, expires_at, superseded_by и время создания/изменения. pending не участвует в промпте; после редактирования обрабатывается как ручное обслуживание.
pending-выводы, предназначенные для изменения существующей памяти: до подтверждения старая запись продолжает действовать; подтверждение в рамках одной транзакции активирует вывод и заменяет старую запись. Выводы, которые устарели, истекли или опираются на изменённое/удалённое содержимое, подтвердить нельзя — возвращается 409, и клиент должен обновить список. Если содержимое почти целиком состоит из чувствительной информации вроде учётных данных, добавление или редактирование возвращает 400.
curl -X POST "$BASE/api/v1/memory/items" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"kind":"preference","content":"Сначала вывод, затем обоснование","importance":3}'
curl "$BASE/api/v1/memory/items?status=pending&limit=50&offset=0" \
-H "Authorization: Bearer $TOKEN"
curl -X POST "$BASE/api/v1/memory/items/item-1/confirm" \
-H "Authorization: Bearer $TOKEN"Темы и предпочтения по документам
| Метод | Путь | Описание |
|---|---|---|
| GET | /memory/topics | темы, которые отслеживаются, но ещё не повышены; limit/offset как у записей, возвращает data и total |
| POST | /memory/topics/:id/promote | вручную повышает до долгосрочного отслеживания; возвращает {success,data:MemoryItem} |
| DELETE | /memory/topics/:id | прекращает отслеживание темы; возвращает success |
| GET | /memory/documents | предпочтения по документам; limit/offset как у записей, возвращает data и total |
| DELETE | /memory/documents/:id | удаляет запись предпочтения; возвращает success, не удаляет документ базы знаний |
Поля Topic включают id/topic/aliases/hits/threshold/last_seen_at; поля Document включают id/knowledge_id/knowledge_base_id/title/hits/last_used_at. Для удаления используется id записи предпочтения.
curl "$BASE/api/v1/memory/topics" -H "Authorization: Bearer $TOKEN"
curl -X POST "$BASE/api/v1/memory/topics/topic-1/promote" \
-H "Authorization: Bearer $TOKEN"
curl -X DELETE "$BASE/api/v1/memory/documents/affinity-1" \
-H "Authorization: Bearer $TOKEN"Экспорт и немедленная консолидация
GET /memory/export возвращает {success,total,truncated,data} с именем файла для скачивания weknora-memories.json. Экспортируется не более 20 000 записей; при достижении лимита проверяйте truncated.
POST /memory/consolidate возвращает {success,data:{merged,demoted,expired,reviewed,candidates,skipped?}}, немедленно объединяет близкие по смыслу записи и архивирует истёкшие. Если изменений нет, skipped объясняет причину.
curl "$BASE/api/v1/memory/export" -H "Authorization: Bearer $TOKEN" \
-o weknora-memories.json
curl -X POST "$BASE/api/v1/memory/consolidate" -H "Authorization: Bearer $TOKEN"При недопустимых параметрах, чувствительном содержимом или выключенной памяти возвращается 400; если записи текущей личности не найдены — 404; конфликт подтверждения — 409; неудовлетворённая аутентификация/права — 401/403. У эндпоинта нет параметра subject для чтения администратором чужой памяти. Реализация: internal/handler/memory.go, internal/router/routes_memory.go.