# 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

Зберігає новий спогад або оновлює наявний (та сама категорія + ключ = оновлення).

```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
# Усі спогади (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Фільтр за категорією
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Фільтр за тегом
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)