# Memory-Best-Practices

Wie du Memories strukturierst, bestimmt ihren Nutzen. Dieser Guide behandelt
Patterns zum Kategorisieren, Taggen und Prioritisieren, damit das LLM zur
richtigen Zeit die richtigen Informationen abrufen kann.

## Kategorien: Wähle die spezifischste

| Kategorie | Verwende für | Beispiel |
|-----------|--------------|----------|
| `identity` | Nutzername, Rolle, Kontaktinfo | `"user_name": "Michael Schäfer"` |
| `preference` | Vorlieben, Abneigungen, Arbeitsstil | `"communication": "Prefers concise responses"` |
| `fact` | Überprüfbare Fakten | `"office_location": "Berlin, Germany"` |
| `project` | Projektstatus, Entscheidungen | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Fähigkeiten des Nutzers | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Frühere Fehler, die es zu vermeiden gilt | `"mistake_npm_version": "Always bump version"` |
| `context` | Session-relevanter Kontext | `"current_focus": "Working on docs system"` |
| `note` | Sonstige Notizen | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> Im Zweifel: `fact` für überprüfbare Infos und `note` für alles andere.
> Nicht überkategorisieren — besser ein klarer `fact` als ein verwirrender
> `context`.

## Keys: Aussagekräftige Bezeichner

Das Feld `key` ist der Bezeichner des Memories. Verwende aussagekräftige,
stabile Keys:

**Gute Keys:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Schlechte Keys:**
- `mem_001` (nicht aussagekräftig)
- `temp` (nicht beschreibend)
- `2026-06-27-note` (Datum hilft beim Recall nicht)

### Key-Namenskonventionen

- `snake_case` (Kleinschreibung mit Unterstrichen)
- Präfix mit Kategorie: `preference_*`, `project_*`, `mistake_*`
- Beschreibende Substantive, keine Verben
- Unter 50 Zeichen halten

## Tags: Für Suche und Filterung

Tags ermöglichen schnelle Filterung und Suche. 2-5 Tags pro Memory hinzufügen:

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

- **Projektnamen**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Themen**: `deployment`, `ci`, `database`, `auth`
- **Status**: `active`, `completed`, `blocked`
- **Prioritäts-Indikatoren**: `urgent`, `long-term`

> [!NOTE]
> Tags sind Case-insensitive. Verwende für Konsistenz Kleinschreibung.

## Prioritäten: Sei realistisch

| Priorität | Verwende für | % der Memories |
|-----------|--------------|----------------|
| `critical` | Nutzeridentität, rechtliche Infos, unumkehrbare Entscheidungen | ~5% |
| `high` | Aktive Projekte, wichtige Präferenzen | ~20% |
| `normal` | Die meisten Fakten, Notizen, Kontext | ~65% |
| `low` | Flüchtig, nett zu wissen | ~10% |

> [!WARNING]
> Markiere nicht alles als `critical`. Wenn alles critical ist, ist nichts
> critical. Reserviere `critical` für Dinge, die echten Schaden anrichten, wenn
> sie vergessen werden.

## Wann speichern, wann nicht?

### Immer speichern

- Nutzeridentität (Name, E-Mail, Rolle)
- Langfristige Präferenzen
- Projektentscheidungen und Begründungen
- Frühere Fehler und gelernte Lektionen
- Zugesagte Zusagen an den Nutzer

### Nicht speichern

- Flüchtigen Status (verwende stattdessen Variablen)
- Wörtlichen Konversationsverlauf (Chat-System übernimmt das)
- Sensible Daten (Passwörter, API-Keys)
- Leicht ableitbare Fakten (aktuelles Datum, Dateiinhalte)
- Flüchtigen Kontext (verwende `context`-Kategorie mit niedriger Priorität)

## Memories aktualisieren

POST `/memory` mit derselben `category` + `key` aktualisiert den bestehenden
Memory:

```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]
> Verwende stabile Keys, damit du aktualisieren kannst, ohne Duplikate zu
> erzeugen. Das LLM sollte denselben Key erneut posten, wenn sich Infos ändern,
> nicht neue Memories anlegen.

## Memory-Lebenszyklus

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

- **Create**: POST /memory mit vollem Kontext
- **Active**: Häufig abrufen, bei Bedarf aktualisieren
- **Stale**: Noch relevant, aber nicht aktiv genutzt (niedrigere Priorität?)
- **Archive**: Priorität auf `low` setzen, für historische Referenz behalten
- **Delete**: DELETE /memory/:id, wenn nicht mehr relevant

### Periodische Bereinigung

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

## Pattern: Memory-Vererbung

Für hierarchischen Kontext (Projekt → Subprojekt → Task):

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

Das LLM kann dann `q=synapse+docs` suchen, um alle verwandten Memories zu
finden.

## Pattern: Entscheidungs-Log

Entscheidungen mit Begründung speichern, damit das LLM sie nicht neu verhandelt:

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

## Pattern: Fehler-Vermeidung

Fehler mit spezifischen Vermeidungs-Anweisungen speichern:

```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-Patterns, die du vermeiden solltest

> [!WARNING]
> - **Konversations-Logs speichern** — Chat-System übernimmt das
> - **Ganze Dateien speichern** — Script-Speicher oder externen Speicher verwenden
> - **Flüchtigen Status speichern** — Variablen verwenden
> - **Secrets speichern** — Environment-Variablen verwenden
> - **Memories duplizieren** — stabile Keys verwenden
> - **Übertrieben taggen** — 2-5 Tags pro Memory sind ideal
> - **Alles ist critical** — sei realistisch mit Prioritäten

## Nächste Schritte

- [Memory-API](/docs/api/memory)
- [Persistenter LLM-Agent](/docs/guides/persistent-llm-agent)
- [Memory-Tagging-Strategie](/docs/llm-cookbook/memory-tagging-strategy)