# Memory API

De Memory API is het hart van Synapse. Het biedt 22 eindpunten voor het opslaan,
ophalen, zoeken en beheren van gestructureerde herinneringen. Alle eindpunten vereisen
een Mind Key voor authenticatie.

> [!CRITICAL]
> **Roep altijd `GET /memory/recall` aan aan het begin van elke sessie.** Dit is
> de enige manier om context van eerdere sessies te herstellen.

## Categorieën

Herinneringen zijn ingedeeld in 8 categorieën:

| Categorie | Gebruik |
|-----------|---------|
| `identity` | Naam, rol, contactgegevens, voorkeuren over zichzelf |
| `preference` | Voorkeuren, afkeuren, werkstijl, communicatievoorkeuren |
| `fact` | Verifieerbare feiten (projectdetails, data, URL's) |
| `project` | Projectstatus, mijlpalen, architectuur |
| `skill` | Dingen waar de gebruiker goed in is |
| `mistake` | Eerdere fouten — herhaal ze niet |
| `context` | Sessie-relevante context |
| `note` | Diverse notities |

## Prioriteiten

- `low` — leuk om te weten
- `normal` — standaard
- `high` — belangrijk
- `critical` — mag nooit vergeten worden (gebruikersidentiteit, juridische info)

## Kern-eindpunten

### GET /memory/recall

Retourneert ALLE herinneringen als op LLM geoptimaliseerde platte tekst. Roep dit aan bij elke sessiestart.

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

Respons (text/plain):

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

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

...
```

### POST /memory

Sla een nieuwe herinnering op of werk een bestaande bij (zelfde categorie + 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"
  }'
```

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

### GET /memory

Toon herinneringen met optionele filters.

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

# Filter op categorie
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

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

### PUT /memory/:id

Werk een specifieke herinnering bij op 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

Verwijder één herinnering.

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

## Zoek-eindpunten

### GET /memory/search

Volledige-tekst zoeken met FTS5.

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

FTS5-syntaxis:

- Meerdere woorden = AND: `docker swarm`
- Zin: `"docker swarm"`
- Prefix: `docker*`
- Booleaans: `docker OR kubernetes`
- Uitsluiten: `docker -swarm`

### GET /memory/semantic-search

Conceptueel zoeken met embeddings (langzamer dan FTS5 maar begrijpt betekenis).

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

Retourneert herinneringen die semantisch overeenkomen met de query, zelfs als er geen
trefwoorden overeenkomen. Handig voor "vind herinneringen over X" waarbij X anders
wordt omschreven.

### GET /memory/by-tag

Toon herinneringen per tag.

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

### GET /memory/related/:id

Vind herinneringen gerelateerd aan een specifieke herinnering (via gedeelde tags).

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

## Synchronisatie & Diff

### GET /memory/diff

Incrementele synchronisatie — retourneert herinneringen die sinds een tijdstempel gewijzigd zijn.

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

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

### POST /memory/sync

Pas een diff toe vanuit een andere instantie (voor self-hosted synchronisatie).

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

## Bulkbewerkingen

### POST /memory/bulk-delete

Verwijder meerdere herinneringen op 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

Genereer embeddings voor herinneringen die deze nog niet hebben (voor semantisch zoeken).

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

Controleer de voortgang van embedding-generatie.

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

## Verificatie

Herinneringen hebben een `verified`-vlag. Door agents opgeslagen herinneringen zijn
standaard niet geverifieerd (`source=agent`); door mensen opgeslagen herinneringen
zijn geverifieerd (`source=user`).

### POST /memory/verify

Markeer een herinnering als geverifieerd (vereist JWT, niet Mind Key).

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

### POST /memory/unverify

Markeer een herinnering als niet-geverifieerd (vereist JWT).

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

### GET /memory/unverified

Toon herinneringen die wachten op menselijke verificatie.

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

## Statistieken & Audit

### GET /memory/stats

Geaggregeerde statistieken voor de huidige mind.

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

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

### GET /memory/audit

Auditlog van alle toestandswijzigende bewerkingen.

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

### GET /memory/contradictions

Detecteer mogelijke tegenstrijdigheden in opgeslagen herinneringen.

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

### GET /memory/expiring

Toon herinneringen met naderende vervaldatums.

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

## Health & Export

### GET /memory/health

Snelle health check voor het memory-systeem.

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

### GET /memory/mind-export

Volledige JSON-export van alle herinneringen (voor back-up).

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

### POST /memory/compact

Compacteer vergelijkbare herinneringen (automatische samenvatting).

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

## Volgende stappen

- [Quick Start voor LLM's](/docs/getting-started/quick-start-llm)
- [Memory-best-practices](/docs/guides/memory-best-practices)
- [FTS5-zoekopdracht](/docs/concepts/fts5-search)
- [Semantisch zoeken](/docs/concepts/semantic-search)