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

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:

{
  "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

Prioriteiten: wees realistisch

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:

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

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

# 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):

# 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:

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:

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

Volgende stappen

• Memory API
• Permanente LLM-agent
• Memory-tagging-strategie