# Memory-best-practices

Hoe u herinneringen structureert bepaalt hoe nuttig ze zijn. Deze handleiding behandelt
patronen voor het categoriseren, taggen en prioriteren van herinneringen zodat de LLM
de juiste informatie op het juiste moment kan ophalen.

## Categorieën: kies de meest specifieke

| Categorie | Gebruik voor | Voorbeeld |
|-----------|--------------|-----------|
| `identity` | Gebruikersnaam, rol, contactgegevens | `"user_name": "Michael Schäfer"` |
| `preference` | Voorkeuren, afkeuren, werkstijl | `"communication": "Prefers concise responses"` |
| `fact` | Verifieerbare feiten | `"office_location": "Berlin, Germany"` |
| `project` | Projectstatus, beslissingen | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Vaardigheden van de gebruiker | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Eerdere fouten om te vermijden | `"mistake_npm_version": "Always bump version"` |
| `context` | Sessie-relevante context | `"current_focus": "Working on docs system"` |
| `note` | Diverse notities | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> Bij twijfel, gebruik `fact` voor verifieerbare info en `note` voor al het andere.
> Over-categoriseer niet — beter een duidelijke `fact` dan een verwarrende `context`.

## Sleutels: betekenisvolle identificatoren

Het `key`-veld is de identificator van de herinnering. Gebruik betekenisvolle, stabiele sleutels:

**Goede sleutels:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Slechte sleutels:**
- `mem_001` (niet betekenisvol)
- `temp` (niet beschrijvend)
- `2026-06-27-note` (datum helpt niet bij recall)

### Sleutelnaamconventies

- `snake_case` (kleine letters met underscores)
- Voorvoeg met categorie: `preference_*`, `project_*`, `mistake_*`
- Gebruik beschrijvende zelfstandige naamwoorden, niet werkwoorden
- Houd onder 50 tekens

## Tags: voor zoeken en filteren

Tags maken snelle filtering en zoekopdrachten mogelijk. Voeg 2-5 tags toe per herinnering:

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}
```

### Tag-patronen

- **Projectnamen**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Onderwerpen**: `deployment`, `ci`, `database`, `auth`
- **Status**: `active`, `completed`, `blocked`
- **Prioriteitsindicatoren**: `urgent`, `long-term`

> [!NOTE]
> Tags zijn niet hoofdlettergevoelig. Gebruik kleine letters voor consistentie.

## Prioriteiten: wees realistisch

| Prioriteit | Gebruik voor | % van herinneringen |
|------------|--------------|---------------------|
| `critical` | Gebruikersidentiteit, juridische info, onomkeerbare beslissingen | ~5% |
| `high` | Actieve projecten, belangrijke voorkeuren | ~20% |
| `normal` | Meeste feiten, notities, context | ~65% |
| `low` | Efemeer, leuk-om-te-weten | ~10% |

> [!WARNING]
> Markeer niet alles `critical`. Als alles kritiek is, is niets dat.
> Reserveer `critical` voor dingen die echte schade veroorzaken als ze vergeten worden.

## Wanneer wel en niet opslaan

### Sla altijd op

- Gebruikersidentiteit (naam, e-mail, rol)
- Langetermijnvoorkeuren
- Projectbeslissingen en rationaal
- Eerdere fouten en geleerde lessen
- Gemaakte toezeggingen aan de gebruiker

- Niet opslaan

- Tijdelijke staat (gebruik variabelen)
- Letterlijke gespreksgeschiedenis (chat-systeem handelt dit af)
- Gevoelige data (wachtwoorden, API-sleutels)
- Gemakkelijk af te leiden feiten (huidige datum, bestandsinhouden)
- Efemere context (gebruik `context`-categorie met lage prioriteit)

## Herinneringen bijwerken

POST `/memory` met dezelfde `category` + `key` werkt de bestaande herinnering bij:

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

# Later: update with same key
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Gebruik stabiele sleutels zodat u kunt bijwerken zonder duplicaten te maken. De LLM
> moet dezelfde sleutel opnieuw POSTen als info verandert, niet nieuwe herinneringen maken.

## Memory-levenscyclus

```
Create → Active → Stale → Archive → Delete
```

- **Create**: POST /memory met volledige context
- **Active**: Vaak ophalen, zo nodig bijwerken
- **Stale**: Nog relevant maar niet actief gebruikt (lagere prioriteit?)
- **Archive**: Stel prioriteit in op `low`, bewaar voor historische referentie
- **Delete**: DELETE /memory/:id wanneer niet meer relevant

### Periodieke opschoning

```python
# Find memories not updated in 90 days
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Patroon: memory-overerving

Voor hiërarchische context (project → subproject → taak):

```python
# Parent project
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

De LLM kan dan `q=synapse+docs` zoeken om alle gerelateerde herinneringen te vinden.

## Patroon: beslissingslogboek

Sla beslissingen met rationaal op zodat de LLM ze niet heroverweegt:

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## Patroon: foutvermijding

Sla fouten op met specifieke vermijdingsinstructies:

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## Anti-patronen om te vermijden

> [!WARNING]
> - **Gesprekslogs opslaan** — chat-systeem handelt dit af
> - **Volledige bestanden opslaan** — gebruik script store of externe opslag
> - **Efemere staat opslaan** — gebruik variabelen
> - **Geheimen opslaan** — gebruik omgevingsvariabelen
> - **Herinneringen dupliceren** — gebruik stabiele sleutels
> - **Over-taggen** — 2-5 tags per herinnering is ideaal
> - **Alles is kritiek** — wees realistisch met prioriteiten

## Volgende stappen

- [Memory API](/docs/api/memory)
- [Permanente LLM-agent](/docs/guides/persistent-llm-agent)
- [Memory-tagging-strategie](/docs/llm-cookbook/memory-tagging-strategy)