# Het Memory-model

Het memory-model van Synapse is ontworpen voor LLM-agents — gestructureerd genoeg voor
betrouwbare recall, flexibel genoeg voor elk domein.

## Anatomie van een herinnering

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

## Velden

| Veld | Type | Vereist | Beschrijving |
|------|------|---------|--------------|
| `id` | string | auto | Unieke ID (mem_xxx) |
| `category` | enum | ✅ | Een van 8 categorieën |
| `key` | string | ✅ | Stabiele identificator (gebruikt voor updates) |
| `content` | string | ✅ | De memory-inhoud (willekeurige tekst) |
| `tags` | string[] | – | Voor zoeken en filteren |
| `priority` | enum | – | low, normal, high, critical (standaard: normal) |
| `source` | enum | auto | user, agent (wie heeft het opgeslagen) |
| `verified` | bool | auto | Heeft een mens dit geverifieerd? |
| `confidence` | float | – | 0.0 tot 1.0 (standaard: 1.0 voor user, 0.7 voor agent) |
| `expires_at` | timestamp | – | Wanneer deze herinnering vergeten moet worden |
| `mind_id` | string | auto | Welke mind eigenaar is |
| `created_at` | timestamp | auto | Eerst opgeslagen |
| `updated_at` | timestamp | auto | Laatst gewijzigd |

## Categorieën

Acht categorieën dekken de veelvoorkomende LLM-agent-toepassingen:

| Categorie | Doel | Voorbeeldinhoud |
|-----------|------|-----------------|
| `identity` | Wie de gebruiker is | "Gebruiker is Michael Schäfer, software engineer in Berlin" |
| `preference` | Gebruikersvoorkeuren | "Geeft de voorkeur aan beknopte technische antwoorden" |
| `fact` | Verifieerbare feiten | "Kantoor is in Berlin, tijdzone Europe/Berlin" |
| `project` | Projectstatus | "Synapse v1.5.0 uitgerold, bezig met v1.6.0 docs" |
| `skill` | Vaardigheden van de gebruiker | "Gevorderd Python, 10+ jaar" |
| `mistake` | Eerdere fouten | "Vergeten npm-versie te verhogen — CI faalde" |
| `context` | Sessie-context | "Momenteel PR #42 aan het beoordelen" |
| `note` | Diverse notities | "Probeer Redis voor caching in volgende sprint" |

## Sleutels: stabiele identificatoren

Het `key`-veld is kritiek — het is hoe u herinneringen bijwerkt zonder duplicaten
te maken.

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

**Sleutelregels:**

- Moet uniek zijn binnen (category, mind)
- Gebruik `snake_case`
- Voorvoeg met categorie voor duidelijkheid: `preference_communication`, `mistake_npm_version`
- Houd stabiel — wijzig sleutels niet na aanmaak

## Tags: voor zoeken

Tags maken snelle filtering en zoekopdrachten mogelijk:

```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 per herinnering (over-tag niet)
- Kleine letters voor consistentie
- Gebruik projectnamen, onderwerpen, technologieën
- Tags zijn niet hoofdlettergevoelig

## Prioriteitsniveaus

| Prioriteit | Wanneer te gebruiken | Recall-gedrag |
|------------|----------------------|---------------|
| `critical` | Identiteit, juridisch, onomkeerbaar | Altijd bovenaan recall |
| `high` | Actieve projecten, kernvoorkeuren | Prominent in recall |
| `normal` | Meeste herinneringen (standaard) | Standaard recall-volgorde |
| `low` | Efemeer, leuk-om-te-weten | Kan worden samengevat |

`/memory/recall` sorteert op prioriteit (critical eerst), dan op recentheid.

## Bron: User versus Agent

Herinneringen worden getagd met `source`:

- `user` — opgeslagen door een mens (via JWT of human-UI)
- `agent` — opgeslagen door een LLM-agent (via Mind Key)

Dit beïnvloedt:

- **Verificatie**: `user`-herinneringen worden automatisch geverifieerd, `agent`-herinneringen niet
- **Betrouwbaarheid**: `user` standaard 1.0, `agent` 0.7
- **Recall**: `/memory/recall` markeert niet-geverifieerde herinneringen met "(unverified)"

> [!NOTE]
> Behandel `agent`-bron-herinneringen met gepast skepticisme. Ze kunnen zijn
> afgeleid of aangenomen in plaats van direct door de gebruiker gesteld.

## Verificatie

De `verified`-vlag geeft aan dat een mens de herinnering heeft bevestigd:

- `user`-herinneringen: automatisch geverifieerd (`true`)
- `agent`-herinneringen: standaard niet-geverifieerd (`false`)

Verifieer herinneringen via:

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

> [!NOTE]
> Verificatie vereist JWT (mens-auth), niet Mind Key (agent-auth). Dit
> zorgt ervoor dat alleen mensen herinneringen als geverifieerd kunnen markeren.

## Betrouwbaarheid

Het `confidence`-veld (0.0 tot 1.0) geeft aan hoe betrouwbaar de herinnering is:

- 1.0 — direct door gebruiker gesteld
- 0.7 — door agent afgeleid
- 0.5 — onzeker, vereist verificatie
- 0.0 — expliciet betwijfeld

Stel betrouwbaarheid in bij opslaan:

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

## Verval

Stel `expires_at` in voor tijdgevoelige herinneringen:

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

Verlopen herinneringen worden niet geretourneerd door `/memory/recall` (maar bestaan nog wel in DB).
Gebruik `/memory/expiring?within=7d` om herinneringen te zien die binnenkort verlopen.

## Memory-levenscyclus

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

## Recall-gedrag

`GET /memory/recall` retourneert een platte-tekst samenvatting geoptimaliseerd voor LLM-context:

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

...
```

- Gesorteerd op prioriteit (critical → low), dan op recentheid
- Niet-geverifieerde herinneringen gemarkeerd met `[unverified]`
- Tags inbegrepen voor context
- Platte tekst (geen JSON-parsing nodig)

## Volgende stappen

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