# Memory-API

Die Memory-API ist das Herz von Synapse. Sie bietet 22 Endpunkte zum Speichern,
Abrufen, Suchen und Verwalten strukturierter Erinnerungen. Alle Endpunkte
erfordern einen Mind Key zur Authentifizierung.

> [!CRITICAL]
> **Rufe immer `GET /memory/recall` zu Beginn jeder Session auf.** Das ist der
> einzige Weg, den Kontext aus früheren Sessions wiederherzustellen.

## Kategorien

Memories sind in 8 Kategorien gegliedert:

| Kategorie | Anwendungsfall |
|-----------|----------------|
| `identity` | Nutzername, Rolle, Kontaktinfo, Selbstaussagen |
| `preference` | Vorlieben, Abneigungen, Arbeitsstil, Kommunikationspräferenzen |
| `fact` | Überprüfbare Fakten (Projekt-Details, Daten, URLs) |
| `project` | Projektstatus, Meilensteine, Architektur |
| `skill` | Dinge, die der Nutzer gut kann |
| `mistake` | Frühere Fehler — nicht wiederholen |
| `context` | Session-relevanter Kontext |
| `note` | Sonstige Notizen |

## Prioritäten

- `low` — nett zu wissen
- `normal` — Standard
- `high` — wichtig
- `critical` — darf nie vergessen werden (Nutzeridentität, rechtliche Infos)

## Kern-Endpunkte

### GET /memory/recall

Liefert ALLE Memories als LLM-optimierten Klartext. Rufe dies zu Beginn jeder
Session auf.

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

Antwort (text/plain):

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

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

...
```

### POST /memory

Einen neuen Memory speichern oder einen bestehenden aktualisieren (gleiche
Kategorie + Key = Update).

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

Antwort: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Memories mit optionalen Filtern auflisten.

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

# Nach Kategorie filtern
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Nach Tag filtern
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Einen bestimmten Memory per ID aktualisieren.

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

Einen einzelnen Memory löschen.

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

## Such-Endpunkte

### GET /memory/search

Volltextsuche via FTS5.

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

FTS5-Syntax:

- Mehrere Wörter = AND: `docker swarm`
- Phrase: `"docker swarm"`
- Präfix: `docker*`
- Boolesch: `docker OR kubernetes`
- Ausschließen: `docker -swarm`

### GET /memory/semantic-search

Konzeptionelle Suche via Embeddings (langsamer als FTS5, versteht aber Bedeutung).

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

Liefert Memories, die semantisch zur Anfrage passen, selbst wenn keine Keywords
übereinstimmen. Nützlich für „finde Memories über X", wenn X anders beschrieben
wird.

### GET /memory/by-tag

Memories nach Tag auflisten.

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

### GET /memory/related/:id

Memories finden, die mit einem bestimmten Memory verwandt sind (über gemeinsame
Tags).

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

## Sync & Diff

### GET /memory/diff

Inkrementeller Sync — liefert Memories, die seit einem Zeitstempel geändert
wurden.

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

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

### POST /memory/sync

Einen Diff aus einer anderen Instanz anwenden (für selbstgehosteten Sync).

```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": [...]}'
```

## Bulk-Operationen

### POST /memory/bulk-delete

Mehrere Memories per ID löschen.

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

Embeddings für Memories generieren, die noch keine haben (für semantische
Suche).

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

Fortschritt der Embedding-Generierung prüfen.

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

## Verifikation

Memories haben ein `verified`-Flag. Vom Agent gespeicherte Memories sind
standardmäßig unbestätigt (`source=agent`); von Menschen gespeicherte Memories
sind verifiziert (`source=user`).

### POST /memory/verify

Einen Memory als verifiziert markieren (erfordert JWT, nicht Mind Key).

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

### POST /memory/unverify

Einen Memory als unverifiziert markieren (erfordert JWT).

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

### GET /memory/unverified

Memories auflisten, die auf menschliche Verifikation warten.

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

## Statistik & Audit

### GET /memory/stats

Aggregierte Statistiken für den aktuellen Mind.

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

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

### GET /memory/audit

Audit-Log aller zustandsverändernden Operationen.

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

### GET /memory/contradictions

Potenzielle Widersprüche in gespeicherten Memories erkennen.

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

### GET /memory/expiring

Memories auflisten, deren Ablaufdatum näher rückt.

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

## Health & Export

### GET /memory/health

Schneller Health-Check für das Memory-System.

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

### GET /memory/mind-export

Vollständiger JSON-Export aller Memories (für Backups).

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

### POST /memory/compact

Ähnliche Memories komprimieren (Auto-Summary).

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

## Nächste Schritte

- [Quick Start für LLMs](/docs/getting-started/quick-start-llm)
- [Memory-Best-Practices](/docs/guides/memory-best-practices)
- [FTS5-Suche](/docs/concepts/fts5-search)
- [Semantische Suche](/docs/concepts/semantic-search)