# Семантичний пошук (ембеддинги)

Synapse підтримує семантичний пошук за допомогою векторних ембеддингів. На відміну
від FTS5 (зіставлення ключових слів), семантичний пошук знаходить спогади за
**змістом** — навіть якщо ключові слова не збігаються.

## Як це працює

```
1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned
```

### Що таке ембеддинги?

Ембеддинги — це числові векторні представлення тексту. Текст зі схожим змістом
має схожі вектори. Synapse генерує вектор (напр. 1536 вимірів) для вмісту
кожного спогаду.

### Косинусна подібність

Для пошуку семантично схожих спогадів Synapse обчислює косинусну подібність
між вектором запиту та вектором кожного спогаду. Більша подібність = більша
релевантність.

## Коли використовувати семантичний пошук

### Використовуйте семантичний пошук, коли:

- Потрібні «спогади про X», де X описано інакше, ніж збережено
- FTS5 не повертає результатів (немає збігу ключових слів)
- Потрібне концептуальне групування (напр. усі спогади про «deployment», навіть якщо деякі кажуть «release»)
- Запит є питанням: «як ми обробляємо автентифікацію?»

### Використовуйте FTS5, коли:

- Знаєте точні ключові слова
- Потрібна булева логіка (AND, OR, NOT)
- Потрібна затримка менше мілісекунди
- Потрібен пошук фраз

## Кінцева точка

### GET /memory/semantic-search

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

Відповідь:

```json
{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}
```

## Приклади

### Пошук спогадів про розгортання

```bash
# FTS5 може пропустити деякі — семантичний ловить усі
curl .../memory/semantic-search?q=deployment+process
```

Повертає спогади про «deployment», «release», «publishing», «rolling out» тощо.

### Пошук шаблонів автентифікації

```bash
curl .../memory/semantic-search?q=how+do+users+log+in
```

Повертає спогади про login, auth, JWT, session management, OAuth тощо.

### Пошук подібних спогадів

```bash
# Знайти спогади, подібні до конкретного
curl .../memory/related/mem_001
```

Використовує семантичну подібність (через спільні теги ТА вектори ембеддингів).

## Генерування ембеддингів

### Коли генеруються ембеддинги?

- **При збереженні спогаду** — якщо службу ембеддингів налаштовано, ембеддинг генерується синхронно
- **Пакетна генерація** — `POST /memory/embed-batch` генерує ембеддинги для спогадів, що їх не мають
- **Асинхронні оновлення** — при оновленні вмісту ембеддинг регенерується

### Постачальники ембеддингів

Synapse підтримує настроюваних постачальників ембеддингів:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Локальні моделі** (через Ollama або подібні)
- **Користувацькі** (реалізуйте інтерфейс ембеддингів)

Налаштування через змінні середовища:

```bash
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small
```

### Пакетна генерація

Для mind-ів із багатьма спогадами без ембеддингів:

```bash
# Згенерувати ембеддинги для до 100 спогадів
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Перевірити прогрес
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Продуктивність

| Операція | Затримка |
|-----------|---------|
| Генерування ембеддингу (OpenAI) | 100-200мс |
| Семантичний пошук (1к спогадів) | 50-100мс |
| Семантичний пошук (10к спогадів) | 200-500мс |
| Пакетна генерація (100 спогадів) | 10-20с |

> [!NOTE]
> Семантичний пошук повільніший за FTS5 через обчислення векторів. Використовуйте
> FTS5 для відомих ключових слів, семантичний — для концептуальних запитів.

## Обмеження

### Вартість ембеддингів

Якщо використовуєте OpenAI, генерування ембеддингів коштує гроші (~$0.02 за 1М
токенів для text-embedding-3-small). Для 10 000 спогадів у середньому по 100
токенів кожен — це ~$0.02, що несуттєво.

### Холодний старт

Спогади, збережені до налаштування ембеддингів, не матимуть ембеддингів. Запустіть
`POST /memory/embed-batch` для заповнення.

### Залежність від постачальника

Якщо постачальник ембеддингів недоступний, семантичний пошук м'яко завершується
помилкою (повертає порожні результати або помилку). FTS5 продовжує працювати.

## Коли ембеддинги недоступні

Якщо службу ембеддингів не налаштовано:

- `GET /memory/semantic-search` повертає 503 Service Unavailable
- `POST /memory` продовжує працювати (просто ембеддинг не генерується)
- Пошук FTS5 продовжує працювати

## Найкращі практики

> [!TIP]
> - **Семантичний для концептуальних запитів** — «як ми обробляємо X?»
> - **FTS5 для конкретних термінів** — «docker swarm»
> - **Регулярно заповнюйте ембеддинги** — `POST /memory/embed-batch`
> - **Моніторте стан постачальника** — від нього залежить семантичний пошук
> - **Комбінуйте з тегами** — семантичний + фільтр тегів звужує результати

## Наступні кроки

- [Пошук FTS5](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Архітектура](/docs/concepts/architecture)