# Memory API

Memory API stanowi serce Synapse. Zapewnia 22 endpointy do zapisywania,
pobierania, wyszukiwania i zarządzania ustrukturyzowanymi wspomnieniami. Wszystkie
endpointy wymagają Mind Key do autoryzacji.

> [!CRITICAL]
> **Należy zawsze wywoływać `GET /memory/recall` na początku każdej sesji.** To
> jedyny sposób odbudowy kontekstu z poprzednich sesji.

## Kategorie

Wspomnienia są zorganizowane w 8 kategoriach:

| Kategoria | Przypadek użycia |
|----------|----------|
| `identity` | Imię użytkownika, rola, dane kontaktowe, preferencje dotyczące samego siebie |
| `preference` | Sympatie, antypatie, styl pracy, preferencje komunikacyjne |
| `fact` | Weryfikowalne fakty (szczegóły projektu, daty, URL-e) |
| `project` | Status projektu, kamienie milowe, architektura |
| `skill` | Rzeczy, w których użytkownik jest dobry |
| `mistake` | Błędy z przeszłości — unikać ich powtarzania |
| `context` | Kontekst istotny dla sesji |
| `note` | Różne notatki |

## Priorytety

- `low` — warto wiedzieć
- `normal` — domyślny
- `high` — ważne
- `critical` — nigdy nie wolno zapominać (tożsamość użytkownika, informacje prawne)

## Podstawowe endpointy

### GET /memory/recall

Zwraca WSZYSTKIE wspomnienia jako zwykły tekst zoptymalizowany dla LLM. Należy
wywoływać na początku każdej sesji.

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

Odpowiedź (text/plain):

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

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

...
```

### POST /memory

Zapisuje nowe wspomnienie lub aktualizuje istniejące (ta sama kategoria + klucz
= aktualizacja).

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

Odpowiedź: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Lista wspomnień z opcjonalnymi filtrami.

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

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

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

### PUT /memory/:id

Aktualizuje konkretne wspomnienie po 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

Usuwa pojedyncze wspomnienie.

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

## Endpointy wyszukiwania

### GET /memory/search

Wyszukiwanie pełnotekstowe z użyciem FTS5.

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

Składnia FTS5:

- Wiele słów = AND: `docker swarm`
- Fraza: `"docker swarm"`
- Prefiks: `docker*`
- Wartość logiczna: `docker OR kubernetes`
- Wykluczenie: `docker -swarm`

### GET /memory/semantic-search

Wyszukiwanie semantyczne z użyciem osadzeń (wolniejsze niż FTS5, ale rozumie znaczenie).

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

Zwraca wspomnienia semantycznie podobne do zapytania, nawet jeśli nie ma dopasowań
słów kluczowych. Przydatne do „znajdź wspomnienia o X", gdy X jest opisane inaczej.

### GET /memory/by-tag

Lista wspomnień wg tagu.

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

### GET /memory/related/:id

Znajduje wspomnienia powiązane z konkretnym (przez wspólne tagi).

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

## Synchronizacja i diff

### GET /memory/diff

Synchronizacja przyrostowa — zwraca wspomnienia zmienione od podanego
znacznika czasu.

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

Odpowiedź: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Stosuje diff z innej instancji (do synchronizacji 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": [...]}'
```

## Operacje masowe

### POST /memory/bulk-delete

Usuwa wiele wspomnień po 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

Generuje osadzenia dla wspomnień, które ich jeszcze nie mają (do wyszukiwania
semantycznego).

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

Sprawdza postęp generowania osadzeń.

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

## Weryfikacja

Wspomnienia mają flagę `verified`. Wspomnienia zapisane przez agenta są domyślnie
niezweryfikowane (`source=agent`); zapisane przez człowieka są zweryfikowane
(`source=user`).

### POST /memory/verify

Oznacza wspomnienie jako zweryfikowane (wymaga JWT, nie Mind Key).

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

### POST /memory/unverify

Oznacza wspomnienie jako niezweryfikowane (wymaga JWT).

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

### GET /memory/unverified

Lista wspomnień oczekujących na weryfikację przez człowieka.

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

## Statystyki i audyt

### GET /memory/stats

Statystyki agregowane dla bieżącego umysłu.

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

Zwraca: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Dziennik audytu wszystkich operacji zmieniających stan.

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

### GET /memory/contradictions

Wykrywa potencjalne sprzeczności w zapisanych wspomnieniach.

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

### GET /memory/expiring

Lista wspomnień z zbliżającą się datą wygaśnięcia.

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

## Kondycja i eksport

### GET /memory/health

Szybkie sprawdzenie kondycji systemu pamięci.

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

### GET /memory/mind-export

Pełny eksport JSON wszystkich wspomnień (do kopii zapasowej).

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

### POST /memory/compact

Kompaktuje podobne wspomnienia (automatyczne streszczanie).

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

## Następne kroki

- [Szybki start dla LLM](/docs/getting-started/quick-start-llm)
- [Najlepsze praktyki pamięci](/docs/guides/memory-best-practices)
- [Wyszukiwanie FTS5](/docs/concepts/fts5-search)
- [Wyszzukiwanie semantyczne](/docs/concepts/semantic-search)