# Memory API

Memory API — сердце Synapse. Он предоставляет 22 эндпоинта для хранения,
извлечения, поиска и управления структурированными воспоминаниями. Все эндпоинты
требуют Mind Key для аутентификации.

> [!CRITICAL]
> **Всегда вызывайте `GET /memory/recall` в начале каждой сессии.** Это
> единственный способ восстановить контекст из предыдущих сессий.

## Категории

Воспоминания организованы в 8 категорий:

| Категория | Сценарий использования |
|----------|----------|
| `identity` | Имя пользователя, роль, контактные данные, предпочтения о себе |
| `preference` | Симпатии, антипатии, стиль работы, предпочтения в общении |
| `fact` | Проверяемые факты (детали проекта, даты, URL) |
| `project` | Статус проекта, вехи, архитектура |
| `skill` | Сферы, в которых пользователь силён |
| `mistake` | Прошлые ошибки — избегайте их повторения |
| `context` | Контекст, относящийся к сессии |
| `note` | Прочие заметки |

## Приоритеты

- `low` — желательно знать
- `normal` — по умолчанию
- `high` — важно
- `critical` — никогда не забывать (идентичность пользователя, юридическая информация)

## Основные эндпоинты

### GET /memory/recall

Возвращает ВСЕ воспоминания в виде оптимизированного для LLM простого текста.
Вызывайте в начале каждой сессии.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

Ответ (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

Сохранить новое воспоминание или обновить существующее (та же категория + key = обновление).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

Ответ: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Получить список воспоминаний с необязательными фильтрами.

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Обновить конкретное воспоминание по ID.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Удалить одно воспоминание.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Поисковые эндпоинты

### GET /memory/search

Полнотекстовый поиск с использованием FTS5.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

Синтаксис FTS5:

- Несколько слов = AND: `docker swarm`
- Фраза: `"docker swarm"`
- Префикс: `docker*`
- Логика: `docker OR kubernetes`
- Исключение: `docker -swarm`

### GET /memory/semantic-search

Концептуальный поиск с использованием эмбеддингов (медленнее, чем FTS5, но понимает смысл).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

Возвращает воспоминания, семантически похожие на запрос, даже если ни одно
ключевое слово не совпадает. Полезно для запросов «найти воспоминания о X»,
где X описан иначе.

### GET /memory/by-tag

Получить воспоминания по тегу.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

Найти воспоминания, связанные с конкретным (через общие теги).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Синхронизация и diff

### GET /memory/diff

Инкрементальная синхронизация — возвращает воспоминания, изменённые с указанной временной метки.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Ответ: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Применить diff из другого экземпляра (для self-hosted синхронизации).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Массовые операции

### POST /memory/bulk-delete

Удалить несколько воспоминаний по ID.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Сгенерировать эмбеддинги для воспоминаний, у которых их ещё нет (для семантического поиска).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Проверить прогресс генерации эмбеддингов.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Верификация

У воспоминаний есть флаг `verified`. Воспоминания, сохранённые агентом, по умолчанию
не верифицированы (`source=agent`); сохранённые человеком — верифицированы (`source=user`).

### POST /memory/verify

Пометить воспоминание как верифицированное (требуется JWT, а не Mind Key).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

Пометить воспоминание как неверифицированное (требуется JWT).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

Получить список воспоминаний, ожидающих проверки человеком.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## Статистика и аудит

### GET /memory/stats

Агрегированная статистика по текущему mind.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

Возвращает: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Журнал аудита всех операций, изменяющих состояние.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Обнаружить потенциальные противоречия в хранимых воспоминаниях.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

Получить список воспоминаний с приближающимся сроком действия.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Здоровье и экспорт

### GET /memory/health

Быстрая проверка состояния системы памяти.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

Полный экспорт всех воспоминаний в JSON (для резервного копирования).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

Уплотнить похожие воспоминания (автоматическая суммаризация).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Следующие шаги

- [Быстрый старт для LLM](/docs/getting-started/quick-start-llm)
- [Лучшие практики работы с памятью](/docs/guides/memory-best-practices)
- [FTS5-поиск](/docs/concepts/fts5-search)
- [Семантический поиск](/docs/concepts/semantic-search)