# Szybki start dla agentów LLM

Między sesjami tracisz całą pamięć. Synapse jest twoim zewnętrznym mózgiem. Ten
przewodnik pokazuje trzy niezbędne wywołania API, które musi znać każdy agent LLM.

> [!CRITICAL]
> Należy wywołać `GET /memory/recall` na POCZĄTKU KAŻDEJ sesji.
> Bez tego wywołania agent nie ma pamięci o tym, kim jest użytkownik, co obiecał
> ani nad czym pracował ostatnio.

## Krok 1: Recall wszystkich wspomnień (ZAWSZE NAJPIERW)

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

Zwraca ustrukturyzowane, tekstowe podsumowanie wszystkich zapisanych wspomnień.
Należy je przeanalizować, aby odbudować model mentalny użytkownika, jego projektów
i przeszłych interakcji.

Przykładowa odpowiedź:

```
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
  ...
```

## Krok 2: Zapis nowego wspomnienia

Gdy poznasz coś warte zapamiętania:

```
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"
}
```

**Kategorie:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Priorytety:** `low`, `normal`, `high`, `critical`

> [!TIP]
> Zawsze należy dołączyć pole `key` — krótki identyfikator wspomnienia. Pozwala to
> zaktualizować to samo wspomnienie później przez ponowne POST z tym samym kluczem.

## Krok 3: Wyszukiwanie konkretnego wspomnienia

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

> [!TIP]
> Składnia FTS5: wiele słów = wyszukiwanie AND. Frazy w cudzysłowach: `"docker swarm"`.
> Wyszukiwanie prefiksem: `docker*`. Wartość logiczna: `docker OR kubernetes`.

## Narzędzia otwarte (bez nagłówków autoryzacji)

Jeśli narzędzie potrafi tylko otwierać URL-e (bez własnych nagłówków), użyć
parametru `?key=`:

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

> [!WARNING]
> `?key=` jest ograniczone do 60 żądań/minutę. Nagłówek Bearer nie ma limitu.
> Należy używać nagłówka Bearer zawsze, gdy to możliwe.

## Pełny przepływ sesji

1. **Początek sesji:** `GET /memory/recall` — załadowanie wszystkich wspomnień
2. **Podczas pracy:** `GET /memory/search?q=...` — znalezienie konkretnych faktów
3. **Przy nowej informacji:** `POST /memory` — zapis (z kategorią, kluczem, tagami, priorytetem)
4. **Okresowo:** `GET /chat/poll` — sprawdzenie wiadomości od człowieka
5. **Koniec sesji:** Zapis końcowych ustaleń przez `POST /memory`

## Typowe wzorce

### Aktualizacja istniejącego wspomnienia

Wykonać POST `/memory` z tym samym `category` i `key` — istniejące wspomnienie
jest aktualizowane, a nie duplikowane.

### Zapis statusu projektu

```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"
}
```

### Zapis błędu (aby go nie powtórzyć)

```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"
}
```

### Sprawdzanie wiadomości od człowieka

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

Zwraca nieprzeczytane wiadomości od człowieka. Odpowiedź przez:

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

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

## Następne kroki

- [Autoryzacja](/docs/getting-started/authentication) — Mind Key vs JWT
- [Dokumentacja Memory API](/docs/api/memory) — wszystkie 22 endpointy pamięci
- [Chat API](/docs/api/chat) — asynchroniczna komunikacja z ludźmi
- [Książka kucharska LLM](/docs/llm-cookbook/session-start-pattern) — praktyczne wzorce