{"title":"Das Memory-Modell","slug":"memory-model","category":"concepts","summary":"Wie Memories strukturiert sind — Kategorien, Keys, Tags, Prioritäten, Quellen, Verifikation.","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":664,"read_minutes":3,"lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Das Memory-Modell\n\nSynapses Memory-Modell ist für LLM-Agenten gestaltet — strukturiert genug für\nzuverlässiges Abrufen, flexibel genug für jede Domäne.\n\n## Anatomie eines Memories\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## Felder\n\n| Feld | Typ | Pflicht | Beschreibung |\n|-------|------|---------|--------------|\n| `id` | string | auto | Eindeutige ID (mem_xxx) |\n| `category` | enum | ✅ | Eine von 8 Kategorien |\n| `key` | string | ✅ | Stabiler Bezeichner (für Updates genutzt) |\n| `content` | string | ✅ | Der Memory-Inhalt (beliebiger Text) |\n| `tags` | string[] | – | Für Suche und Filterung |\n| `priority` | enum | – | low, normal, high, critical (Standard: normal) |\n| `source` | enum | auto | user, agent (wer hat es gespeichert) |\n| `verified` | bool | auto | Wurde das von einem Menschen verifiziert? |\n| `confidence` | float | – | 0.0 bis 1.0 (Standard: 1.0 für user, 0.7 für agent) |\n| `expires_at` | timestamp | – | Wann dieser Memory vergessen werden soll |\n| `mind_id` | string | auto | Welcher Mind ihn besitzt |\n| `created_at` | timestamp | auto | Erstmalig gespeichert |\n| `updated_at` | timestamp | auto | Zuletzt geändert |\n\n## Kategorien\n\nAcht Kategorien decken die gängigen LLM-Agent-Anwendungsfälle ab:\n\n| Kategorie | Zweck | Beispielinhalt |\n|-----------|-------|----------------|\n| `identity` | Wer der Nutzer ist | „Nutzer ist Michael Schäfer, Software Engineer in Berlin\" |\n| `preference` | Nutzerpräferenzen | „Bevorzugt prägnante technische Antworten\" |\n| `fact` | Überprüfbare Fakten | „Büro in Berlin, Zeitzone Europe/Berlin\" |\n| `project` | Projektstatus | „Synapse v1.5.0 deployed, arbeite an v1.6.0-Docs\" |\n| `skill` | Fähigkeiten des Nutzers | „Fortgeschrittenes Python, 10+ Jahre\" |\n| `mistake` | Frühere Fehler | „NPM-Version nicht gebumpt — CI fehlgeschlagen\" |\n| `context` | Session-Kontext | „Prüfe gerade PR #42\" |\n| `note` | Sonstige Notizen | „Nächstes Sprint Redis fürs Caching testen\" |\n\n## Keys: Stabile Bezeichner\n\nDas Feld `key` ist entscheidend — so aktualisierst du Memories, ohne Duplikate\nzu erzeugen.\n\n```python\n# First store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**Key-Regeln:**\n\n- Muss innerhalb (Kategorie, Mind) eindeutig sein\n- Verwende `snake_case`\n- Präfix mit Kategorie für Klarheit: `preference_communication`, `mistake_npm_version`\n- Stabil halten — Keys nach Anlage nicht ändern\n\n## Tags: Für die Suche\n\nTags ermöglichen schnelle Filterung und Suche:\n\n```bash\n# Find all memories with tag \"docker\"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker\n```\n\n**Tag-Best-Practices:**\n\n- 2-5 Tags pro Memory (nicht übertrieben)\n- Kleinschreibung für Konsistenz\n- Projektnamen, Themen, Technologien verwenden\n- Tags sind Case-insensitive\n\n## Prioritätsstufen\n\n| Priorität | Wann verwenden | Recall-Verhalten |\n|-----------|----------------|-------------------|\n| `critical` | Identität, rechtlich, unumkehrbar | Immer oben im Recall |\n| `high` | Aktive Projekte, zentrale Präferenzen | Prominent im Recall |\n| `normal` | Die meisten Memories (Standard) | Standard-Reihenfolge |\n| `low` | Flüchtig, nett zu wissen | Kann zusammengefasst werden |\n\n`/memory/recall` sortiert nach Priorität (critical zuerst), dann nach Aktualität.\n\n## Quelle: User vs Agent\n\nMemories werden mit `source` markiert:\n\n- `user` — von einem Menschen gespeichert (via JWT oder Human-UI)\n- `agent` — von einem LLM-Agenten gespeichert (via Mind Key)\n\nDas beeinflusst:\n\n- **Verifikation**: `user`-Memories sind auto-verifiziert, `agent`-Memories nicht\n- **Confidence**: `user` defaults auf 1.0, `agent` auf 0.7\n- **Recall**: `/memory/recall` markiert unverified Memories mit „(unverified)\"\n\n> [!NOTE]\n> Behandle `agent`-Memories mit angemessenem Skepsis. Sie könnten gefolgert\n> oder angenommen statt direkt vom Nutzer geäußert sein.\n\n## Verifikation\n\nDas Flag `verified` zeigt an, dass ein Mensch den Memory bestätigt hat:\n\n- `user`-Memories: auto-verifiziert (`true`)\n- `agent`-Memories: standardmäßig unverified (`false`)\n\nMemories verifizieren via:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> Verifikation erfordert JWT (Human-Auth), nicht Mind Key (Agent-Auth). So wird\n> sichergestellt, dass nur Menschen Memories als verifiziert markieren können.\n\n## Confidence\n\nDas Feld `confidence` (0.0 bis 1.0) zeigt, wie zuverlässig der Memory ist:\n\n- 1.0 — direkt vom Nutzer geäußert\n- 0.7 — vom Agenten gefolgert\n- 0.5 — unsicher, needs Verifikation\n- 0.0 — explizit angezweifelt\n\nBeim Speichern Confidence setzen:\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## Ablauf\n\nFür zeitkritische Memories `expires_at` setzen:\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\nAbgelaufene Memories werden von `/memory/recall` nicht zurückgegeben (bleiben\naber in der DB). Verwende `/memory/expiring?within=7d`, um bald ablaufende\nMemories zu sehen.\n\n## Memory-Lebenszyklus\n\n```\n ┌─────────────────┐\n │ Create │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Active │ ◀──── PUT /memory/:id (update)\n │ (in recall) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ Expired │ │ Verified │ │ Deleted │\n │ (in DB) │ │ (flag) │ │ (gone) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## Recall-Verhalten\n\n`GET /memory/recall` liefert eine Klartext-Zusammenfassung, optimiert für\nLLM-Kontext:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- Sortiert nach Priorität (critical → low), dann nach Aktualität\n- Unverified Memories markiert mit `[unverified]`\n- Tags für Kontext enthalten\n- Klartext (kein JSON-Parsing nötig)\n\n## Nächste Schritte\n\n- [Memory-API](/docs/api/memory)\n- [Memory-Best-Practices](/docs/guides/memory-best-practices)\n- [FTS5-Suche](/docs/concepts/fts5-search)\n","content_html":"

Das Memory-Modell

\n

Synapses Memory-Modell ist für LLM-Agenten gestaltet — strukturiert genug für\nzuverlässiges Abrufen, flexibel genug für jede Domäne.

\n

Anatomie eines Memories

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

Felder

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FeldTypPflichtBeschreibung
idstringautoEindeutige ID (mem_xxx)
categoryenum✅Eine von 8 Kategorien
keystring✅Stabiler Bezeichner (für Updates genutzt)
contentstring✅Der Memory-Inhalt (beliebiger Text)
tagsstring[]–Für Suche und Filterung
priorityenum–low, normal, high, critical (Standard: normal)
sourceenumautouser, agent (wer hat es gespeichert)
verifiedboolautoWurde das von einem Menschen verifiziert?
confidencefloat–0.0 bis 1.0 (Standard: 1.0 für user, 0.7 für agent)
expires_attimestamp–Wann dieser Memory vergessen werden soll
mind_idstringautoWelcher Mind ihn besitzt
created_attimestampautoErstmalig gespeichert
updated_attimestampautoZuletzt geändert
\n

Kategorien

\n

Acht Kategorien decken die gängigen LLM-Agent-Anwendungsfälle ab:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KategorieZweckBeispielinhalt
identityWer der Nutzer ist„Nutzer ist Michael Schäfer, Software Engineer in Berlin"
preferenceNutzerpräferenzen„Bevorzugt prägnante technische Antworten"
factÜberprüfbare Fakten„Büro in Berlin, Zeitzone Europe/Berlin"
projectProjektstatus„Synapse v1.5.0 deployed, arbeite an v1.6.0-Docs"
skillFähigkeiten des Nutzers„Fortgeschrittenes Python, 10+ Jahre"
mistakeFrühere Fehler„NPM-Version nicht gebumpt — CI fehlgeschlagen"
contextSession-Kontext„Prüfe gerade PR #42"
noteSonstige Notizen„Nächstes Sprint Redis fürs Caching testen"
\n

Keys: Stabile Bezeichner

\n

Das Feld key ist entscheidend — so aktualisierst du Memories, ohne Duplikate\nzu erzeugen.

\n
# First store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

Key-Regeln:

\n\n

Tags: Für die Suche

\n

Tags ermöglichen schnelle Filterung und Suche:

\n
# Find all memories with tag "docker"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker

Tag-Best-Practices:

\n\n

Prioritätsstufen

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PrioritätWann verwendenRecall-Verhalten
criticalIdentität, rechtlich, unumkehrbarImmer oben im Recall
highAktive Projekte, zentrale PräferenzenProminent im Recall
normalDie meisten Memories (Standard)Standard-Reihenfolge
lowFlüchtig, nett zu wissenKann zusammengefasst werden
\n

/memory/recall sortiert nach Priorität (critical zuerst), dann nach Aktualität.

\n

Quelle: User vs Agent

\n

Memories werden mit source markiert:

\n\n

Das beeinflusst:

\n\n
Behandle `agent`-Memories mit angemessenem Skepsis. Sie könnten gefolgert\noder angenommen statt direkt vom Nutzer geäußert sein.

Verifikation

\n

Das Flag verified zeigt an, dass ein Mensch den Memory bestätigt hat:

\n\n

Memories verifizieren via:

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
Verifikation erfordert JWT (Human-Auth), nicht Mind Key (Agent-Auth). So wird\nsichergestellt, dass nur Menschen Memories als verifiziert markieren können.

Confidence

\n

Das Feld confidence (0.0 bis 1.0) zeigt, wie zuverlässig der Memory ist:

\n\n

Beim Speichern Confidence setzen:

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

Ablauf

\n

Für zeitkritische Memories expires_at setzen:

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

Abgelaufene Memories werden von /memory/recall nicht zurückgegeben (bleiben\naber in der DB). Verwende /memory/expiring?within=7d, um bald ablaufende\nMemories zu sehen.

\n

Memory-Lebenszyklus

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

Recall-Verhalten

\n

GET /memory/recall liefert eine Klartext-Zusammenfassung, optimiert für\nLLM-Kontext:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

Nächste Schritte

\n\n","urls":{"html":"/docs/concepts/memory-model","text":"/docs/concepts/memory-model?format=text","json":"/docs/concepts/memory-model?format=json","llm":"/docs/concepts/memory-model?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}