# Das Memory-Modell

Synapses Memory-Modell ist für LLM-Agenten gestaltet — strukturiert genug für
zuverlässiges Abrufen, flexibel genug für jede Domäne.

## Anatomie eines Memories

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

## Felder

| Feld | Typ | Pflicht | Beschreibung |
|-------|------|---------|--------------|
| `id` | string | auto | Eindeutige ID (mem_xxx) |
| `category` | enum | ✅ | Eine von 8 Kategorien |
| `key` | string | ✅ | Stabiler Bezeichner (für Updates genutzt) |
| `content` | string | ✅ | Der Memory-Inhalt (beliebiger Text) |
| `tags` | string[] | – | Für Suche und Filterung |
| `priority` | enum | – | low, normal, high, critical (Standard: normal) |
| `source` | enum | auto | user, agent (wer hat es gespeichert) |
| `verified` | bool | auto | Wurde das von einem Menschen verifiziert? |
| `confidence` | float | – | 0.0 bis 1.0 (Standard: 1.0 für user, 0.7 für agent) |
| `expires_at` | timestamp | – | Wann dieser Memory vergessen werden soll |
| `mind_id` | string | auto | Welcher Mind ihn besitzt |
| `created_at` | timestamp | auto | Erstmalig gespeichert |
| `updated_at` | timestamp | auto | Zuletzt geändert |

## Kategorien

Acht Kategorien decken die gängigen LLM-Agent-Anwendungsfälle ab:

| Kategorie | Zweck | Beispielinhalt |
|-----------|-------|----------------|
| `identity` | Wer der Nutzer ist | „Nutzer ist Michael Schäfer, Software Engineer in Berlin" |
| `preference` | Nutzerpräferenzen | „Bevorzugt prägnante technische Antworten" |
| `fact` | Überprüfbare Fakten | „Büro in Berlin, Zeitzone Europe/Berlin" |
| `project` | Projektstatus | „Synapse v1.5.0 deployed, arbeite an v1.6.0-Docs" |
| `skill` | Fähigkeiten des Nutzers | „Fortgeschrittenes Python, 10+ Jahre" |
| `mistake` | Frühere Fehler | „NPM-Version nicht gebumpt — CI fehlgeschlagen" |
| `context` | Session-Kontext | „Prüfe gerade PR #42" |
| `note` | Sonstige Notizen | „Nächstes Sprint Redis fürs Caching testen" |

## Keys: Stabile Bezeichner

Das Feld `key` ist entscheidend — so aktualisierst du Memories, ohne Duplikate
zu erzeugen.

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

# Update with same key (overwrites, doesn't duplicate)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**Key-Regeln:**

- Muss innerhalb (Kategorie, Mind) eindeutig sein
- Verwende `snake_case`
- Präfix mit Kategorie für Klarheit: `preference_communication`, `mistake_npm_version`
- Stabil halten — Keys nach Anlage nicht ändern

## Tags: Für die Suche

Tags ermöglichen schnelle Filterung und Suche:

```bash
# Find all memories with tag "docker"
GET /memory/by-tag?tag=docker

# FTS5 search within tagged subset
GET /memory/search?q=swarm&tag=docker
```

**Tag-Best-Practices:**

- 2-5 Tags pro Memory (nicht übertrieben)
- Kleinschreibung für Konsistenz
- Projektnamen, Themen, Technologien verwenden
- Tags sind Case-insensitive

## Prioritätsstufen

| Priorität | Wann verwenden | Recall-Verhalten |
|-----------|----------------|-------------------|
| `critical` | Identität, rechtlich, unumkehrbar | Immer oben im Recall |
| `high` | Aktive Projekte, zentrale Präferenzen | Prominent im Recall |
| `normal` | Die meisten Memories (Standard) | Standard-Reihenfolge |
| `low` | Flüchtig, nett zu wissen | Kann zusammengefasst werden |

`/memory/recall` sortiert nach Priorität (critical zuerst), dann nach Aktualität.

## Quelle: User vs Agent

Memories werden mit `source` markiert:

- `user` — von einem Menschen gespeichert (via JWT oder Human-UI)
- `agent` — von einem LLM-Agenten gespeichert (via Mind Key)

Das beeinflusst:

- **Verifikation**: `user`-Memories sind auto-verifiziert, `agent`-Memories nicht
- **Confidence**: `user` defaults auf 1.0, `agent` auf 0.7
- **Recall**: `/memory/recall` markiert unverified Memories mit „(unverified)"

> [!NOTE]
> Behandle `agent`-Memories mit angemessenem Skepsis. Sie könnten gefolgert
> oder angenommen statt direkt vom Nutzer geäußert sein.

## Verifikation

Das Flag `verified` zeigt an, dass ein Mensch den Memory bestätigt hat:

- `user`-Memories: auto-verifiziert (`true`)
- `agent`-Memories: standardmäßig unverified (`false`)

Memories verifizieren via:

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

> [!NOTE]
> Verifikation erfordert JWT (Human-Auth), nicht Mind Key (Agent-Auth). So wird
> sichergestellt, dass nur Menschen Memories als verifiziert markieren können.

## Confidence

Das Feld `confidence` (0.0 bis 1.0) zeigt, wie zuverlässig der Memory ist:

- 1.0 — direkt vom Nutzer geäußert
- 0.7 — vom Agenten gefolgert
- 0.5 — unsicher, needs Verifikation
- 0.0 — explizit angezweifelt

Beim Speichern Confidence setzen:

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

## Ablauf

Für zeitkritische Memories `expires_at` setzen:

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

Abgelaufene Memories werden von `/memory/recall` nicht zurückgegeben (bleiben
aber in der DB). Verwende `/memory/expiring?within=7d`, um bald ablaufende
Memories zu sehen.

## Memory-Lebenszyklus

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

## Recall-Verhalten

`GET /memory/recall` liefert eine Klartext-Zusammenfassung, optimiert für
LLM-Kontext:

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

...
```

- Sortiert nach Priorität (critical → low), dann nach Aktualität
- Unverified Memories markiert mit `[unverified]`
- Tags für Kontext enthalten
- Klartext (kein JSON-Parsing nötig)

## Nächste Schritte

- [Memory-API](/docs/api/memory)
- [Memory-Best-Practices](/docs/guides/memory-best-practices)
- [FTS5-Suche](/docs/concepts/fts5-search)