# Швидкий старт для LLM-агентів

Ви втрачаєте всю пам'ять між сесіями. Synapse — ваш зовнішній мозок. Цей посібник
показує три основні API-виклики, які має знати кожен LLM-агент.

> [!CRITICAL]
> Викликайте `GET /memory/recall` НА ПОЧАТКУ КОЖНОЇ сесії.
> Без цього виклику ви не маєте пам'яті про те, хто користувач, що ви обіцяли,
> або над чим працювали минулого разу.

## Крок 1: Відкликання всіх спогадів (ЗАВЖДИ ПЕРШИМ)

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

Повертає структуроване текстове резюме всіх збережених спогадів. Розберіть це,
щоб відновити свою ментальну модель користувача, його проєктів та минулих
взаємодій.

Приклад відповіді:

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

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

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## Крок 2: Збереження нового спогаду

Коли ви дізнаєтесь щось, що варто запам'ятати:

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**Категорії:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Пріоритети:** `low`, `normal`, `high`, `critical`

> [!TIP]
> Завжди включайте поле `key` — короткий ідентифікатор спогаду. Це дозволяє
> оновлювати той самий спогад пізніше, повторно POST-нувши з тим самим ключем.

## Крок 3: Пошук конкретного спогаду

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> Синтаксис FTS5: кілька слів = пошук AND. Фрази в лапках: `"docker swarm"`.
> Пошук за префіксом: `docker*`. Булеві операції: `docker OR kubernetes`.

## Відкриті інструменти (без auth-заголовків)

Якщо ваш інструмент може лише відкривати URL (без власних заголовків), використовуйте параметр `?key=`:

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` обмежено до 60 запитів/хв. Заголовок Bearer не має обмеження.
> Використовуйте заголовок Bearer, коли можливо.

## Повний робочий процес сесії

1. **Початок сесії:** `GET /memory/recall` — завантажити всі спогади
2. **Під час роботи:** `GET /memory/search?q=...` — знайти конкретні факти
3. **При новій інформації:** `POST /memory` — зберегти її (з category, key, tags, priority)
4. **Періодично:** `GET /chat/poll` — перевірити повідомлення від людини
5. **Кінець сесії:** зберегти будь-які фінальні висновки через `POST /memory`

## Поширені шаблони

### Оновлення наявного спогаду

POST `/memory` з тією ж `category` та `key` — наявний спогад оновлюється, а не
дублюється.

### Збереження статусу проєкту

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.",
  "tags": ["synapse", "deployment", "status"],
  "priority": "high"
}
```

### Запис помилки (щоб не повторювати)

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### Перевірка повідомлень від людини

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

Повертає непрочитані повідомлення від людини. Відповідайте через:

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

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

- [Автентифікація](/docs/getting-started/authentication) — Mind Key проти JWT
- [Довідник Memory API](/docs/api/memory) — усі 22 кінцеві точки пам'яті
- [Chat API](/docs/api/chat) — асинхронне спілкування з людьми
- [Куховарська книга LLM](/docs/llm-cookbook/session-start-pattern) — практичні шаблони