# Model pamięci

Model pamięci Synapse jest zaprojektowany dla agentów LLM — na tyle
ustrukturyzowany, by zapewnić niezawodne przypominanie, na tyle elastyczny, by
pasował do każdej domeny.

## Anatomia wspomnienia

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## Pola

| Pole | Typ | Wymagane | Opis |
|-------|------|----------|-------------|
| `id` | string | auto | Unikalny identyfikator (mem_xxx) |
| `category` | enum | ✅ | Jedna z 8 kategorii |
| `key` | string | ✅ | Stabilny identyfikator (używany do aktualizacji) |
| `content` | string | ✅ | Treść wspomnienia (dowolny tekst) |
| `tags` | string[] | – | Do wyszukiwania i filtrowania |
| `priority` | enum | – | low, normal, high, critical (domyślnie: normal) |
| `source` | enum | auto | user, agent (kto zapisał) |
| `verified` | bool | auto | Czy człowiek to zweryfikował? |
| `confidence` | float | – | 0.0-1.0 (domyślnie: 1.0 dla użytkownika, 0.7 dla agenta) |
| `expires_at` | timestamp | – | Kiedy zapomnieć to wspomnienie |
| `mind_id` | string | auto | Do którego umysłu należy |
| `created_at` | timestamp | auto | Pierwszy zapis |
| `updated_at` | timestamp | auto | Ostatnia modyfikacja |

## Kategorie

Osiem kategorii pokrywa typowe przypadki użycia agentów LLM:

| Kategoria | Przeznaczenie | Przykładowa treść |
|----------|---------|-----------------|
| `identity` | Kim jest użytkownik | „User is Michael Schäfer, software engineer in Berlin" |
| `preference` | Preferencje użytkownika | „Prefers concise technical responses" |
| `fact` | Weryfikowalne fakty | „Office is in Berlin, timezone Europe/Berlin" |
| `project` | Status projektu | „Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | Umiejętności użytkownika | „Advanced Python, 10+ years" |
| `mistake` | Błędy z przeszłości | „Forgot to bump npm version — CI failed" |
| `context` | Kontekst sesji | „Currently reviewing PR #42" |
| `note` | Różne notatki | „Try Redis for caching next sprint" |

## Klucze: stabilne identyfikatory

Pole `key` jest kluczowe — to sposób aktualizacji wspomnień bez tworzenia
duplikatów.

```python
# Pierwszy zapis
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Aktualizacja tym samym kluczem (nadpisuje, nie duplikuje)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**Zasady kluczy:**

- Musi być unikalny w obrębie (kategoria, umysł)
- Używać `snake_case`
- Prefiksować kategorią dla jasności: `preference_communication`, `mistake_npm_version`
- Utrzymywać stabilność — nie zmieniać kluczy po utworzeniu

## Tagi: do wyszukiwania

Tagi umożliwiają szybkie filtrowanie i wyszukiwanie:

```bash
# Znalezienie wszystkich wspomnień z tagiem „docker"
GET /memory/by-tag?tag=docker

# Wyszukiwanie FTS5 w obrębie otagowanego podzbioru
GET /memory/search?q=swarm&tag=docker
```

**Najlepsze praktyki tagowania:**

- 2-5 tagów na wspomnienie (bez przesady)
- Małe litery dla spójności
- Używać nazw projektów, tematów, technologii
- Tagi są niewrażliwe na wielkość liter

## Poziomy priorytetu

| Priorytet | Kiedy stosować | Zachowanie recall |
|----------|-------------|-----------------|
| `critical` | Tożsamość, kwestie prawne, nieodwracalne | Zawsze na górze recall |
| `high` | Aktywne projekty, kluczowe preferencje | Wyeksponowane w recall |
| `normal` | Większość wspomnień (domyślny) | Standardowa kolejność recall |
| `low` | Efemeryczne, warto wiedzieć | Mogą zostać podsumowane |

`/memory/recall` sortuje po priorytecie (krytyczne najpierw), a następnie po
aktualności.

## Źródło: użytkownik czy agent

Wspomnienia są oznaczane `source`:

- `user` — zapisane przez człowieka (przez JWT lub interfejs ludzki)
- `agent` — zapisane przez agenta LLM (przez Mind Key)

To wpływa na:

- **Weryfikację:** wspomnienia `user` są automatycznie weryfikowane, `agent` — nie
- **Pewność:** `user` domyślnie 1.0, `agent` 0.7
- **Recall:** `/memory/recall` oznacza niezweryfikowane wspomnienia jako „(unverified)"

> [!NOTE]
> Należy podchodzić do wspomnień ze źródła `agent` z odpowiednim sceptycyzmem. Mogą
> być wnioskowane lub zakładane, a nie bezpośrednio zadeklarowane przez użytkownika.

## Weryfikacja

Flaga `verified` wskazuje, że człowiek potwierdził wspomnienie:

- Wspomnienia `user`: automatycznie zweryfikowane (`true`)
- Wspomnienia `agent`: domyślnie niezweryfikowane (`false`)

Weryfikacja wspomnień:

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

> [!NOTE]
> Weryfikacja wymaga JWT (autoryzacja człowieka), a nie Mind Key (autoryzacja
> agenta). Zapewnia to, że tylko ludzie mogą oznaczać wspomnienia jako zweryfikowane.

## Pewność

Pole `confidence` (0.0-1.0) wskazuje, jak wiarygodne jest wspomnienie:

- 1.0 — bezpośrednio zadeklarowane przez użytkownika
- 0.7 — wnioskowane przez agenta
- 0.5 — niepewne, wymaga weryfikacji
- 0.0 — wprost wątpliwe

Ustawianie pewności przy zapisie:

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## Wygaśnięcie

Dla wspomnień wrażliwych czasowo należy ustawić `expires_at`:

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

Wygasłe wspomnienia nie są zwracane przez `/memory/recall` (ale nadal istnieją w
bazie). Należy użyć `/memory/expiring?within=7d`, aby zobaczyć wspomnienia
wygasające wkrótce.

## Cykl życia wspomnienia

```
                  ┌─────────────────┐
                  │     Create      │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Active      │ ◀──── PUT /memory/:id (update)
                  │  (in recall)    │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Expired  │ │ Verified │ │ Deleted  │
        │ (in DB)  │ │ (flag)   │ │ (gone)   │
        └──────────┘ └──────────┘ └──────────┘
```

## Zachowanie recall

`GET /memory/recall` zwraca podsumowanie w postaci zwykłego tekstu, zoptymalizowane
dla kontekstu LLM:

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

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

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- Posortowane po priorytecie (critical → low), a następnie po aktualności
- Niezweryfikowane wspomnienia oznaczone `[unverified]`
- Tagi dołączone dla kontekstu
- Zwykły tekst (bez parsowania JSON)

## Następne kroki

- [Memory API](/docs/api/memory)
- [Najlepsze praktyki pamięci](/docs/guides/memory-best-practices)
- [Wyszukiwanie FTS5](/docs/concepts/fts5-search)