Hermes-Memory-Next-Level/docs/architecture/memory-tiers.md

# Memory Tiers Architecture

## Übersicht

```
┌─────────────────────────────────────────────────────────────┐
│ TIER 1: WORKING MEMORY (Aktiver Prompt)                     │
│ • Aktuelle Nachrichten + relevante Kontext                   │
│ • 4K–128K Tokens (je nach Modell)                            │
│ • Schnellster Zugriff, höchste Relevanz                     │
├─────────────────────────────────────────────────────────────┤
│ TIER 2: SHORT-TERM MEMORY (Letzte N Sessions)                │
│ • Vollständige Nachrichten der letzten 5–10 Sessions       │
│ • SQLite/JSON, schneller Zugriff                           │
│ • Für Rückfragen zu kürzlich abgeschlossenen Tasks         │
├─────────────────────────────────────────────────────────────┤
│ TIER 3: LONG-TERM MEMORY (Vektor-Store + Graph)              │
│ • Embeddings für semantische Suche                         │
│ • Knowledge Graph für Beziehungen                          │
│ • Fakten, Präferenzen, Projekt-Zustände                    │
├─────────────────────────────────────────────────────────────┤
│ TIER 4: ARCHIVE (Vollständige Historie)                    │
│ • Alle Sessions, alle Nachrichten                          │
│ • Nur bei Bedarf durchsucht (langsame Suche)               │
│ • Compliance, Audit, vollständige Rekonstruktion           │
└─────────────────────────────────────────────────────────────┘
```

## Tier 1: Working Memory

**Speicher**: LLM Prompt (nicht persistent)
**Zugriff**: Synchron, < 1ms
**Inhalt**: Aktuelle Nachrichten + relevante Kontext aus Tier 2/3
**Größe**: 4K–128K Tokens (je nach Modell)
**Lifecycle**: Session-bound, flüchtig

**Injection-Pattern**:
```
System Prompt
├── Base Instructions
├── Injected Memories (relevante Blocks aus Tier 2/3)
├── Current Session Context
└── User Message
```

## Tier 2: Short-Term Memory

**Speicher**: SQLite (`memory.db`)
**Zugriff**: Synchron, ~1-5ms
**Inhalt**: Letzte 5–10 Sessions, vollständige Nachrichten
**Größe**: ~10-50 MB
**Lifecycle**: 30 Tage, dann Archivierung oder Löschung

**Schema**:
```sql
CREATE TABLE short_term_sessions (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    messages JSON NOT NULL,
    summary TEXT,
    extracted_blocks JSON
);

CREATE INDEX idx_sessions_time ON short_term_sessions(timestamp);
CREATE INDEX idx_sessions_session ON short_term_sessions(session_id);
```

## Tier 3: Long-Term Memory

**Speicher**: Qdrant (Vektor) + NetworkX (Graph)
**Zugriff**: Asynchron, ~10-50ms
**Inhalt**: Memory Blocks, Entities, Beziehungen
**Größe**: Unbegrenzt (skalierbar)
**Lifecycle**: Permanent

**Vektor-Store (Qdrant)**:
```python
# Memory Blocks als Embeddings
{
    "id": "uuid",
    "vector": [0.1, 0.2, ...],  # 768-dim embedding
    "payload": {
        "type": "user_preference",
        "category": "formatting",
        "key": "table_style",
        "value": "compact with │ separators",
        "entities": ["Flo"],
        "confidence": 0.95
    }
}
```

**Knowledge Graph (NetworkX)**:
```python
# Entities als Nodes, Beziehungen als Edges
G.add_node("Flo", type="user", properties={...})
G.add_node("waldseilgarten-crm", type="project", properties={...})
G.add_edge("Flo", "waldseilgarten-crm", relation="works_on")
```

## Tier 4: Archive

**Speicher**: Dateisystem (komprimierte JSONL)
**Zugriff**: Asynchron, ~100ms-1s
**Inhalt**: Alle Sessions, alle Nachrichten
**Größe**: Unbegrenzt
**Lifecycle**: Permanent, komprimiert

**Format**:
```jsonl
{"session_id": "...", "date": "2026-06-03", "messages": [...], "compressed": true}
```

## Zugriffsmuster

```
User fragt: "Was war der letzte Stand vom Waldseilgarten-Projekt?"

1. Tier 1 (Working): Prüfe aktuellen Kontext
   → Nicht vorhanden (neue Session)

2. Tier 2 (Short-Term): Suche in letzten 5 Sessions
   → Session vom 3.6.2026 gefunden, aber nur Summary

3. Tier 3 (Long-Term): Vektor-Suche + Graph-Traversal
   → Memory Block: "Projekt-State: waldseilgarten-crm"
   → Graph: Flo → works_on → waldseilgarten-crm
   → Related: docker-compose.yml, NestJS, React

4. Tier 4 (Archive): Vollständige Session laden
   → Nur bei Bedarf, wenn Details fehlen

5. Injection: Relevante Blocks in Working Memory laden
   → System Prompt wird angereichert
```

## Migration

```
Phase 1: Tier 2 (SQLite) — Sofort
         → Short-Term Memory für letzte Sessions

Phase 2: Tier 3 (Vektor + Graph) — 1-2 Monate
         → Memory Blocks aus bestehenden `memory` Einträgen
         → Auto-Extraction startet

Phase 3: Tier 1 (Injection) — 2-3 Monate
         → Session-Start automatisch mit relevanten Memories

Phase 4: Tier 4 (Archive) — 3-6 Monate
         → Vollständige Historie, komprimiert
```

## Technologie-Stack

| Tier | Technologie | Begründung |
|------|-------------|------------|
| Tier 1 | LLM Prompt | Nativ, kein Overhead |
| Tier 2 | SQLite | Einfach, schnell, kein extra Service |
| Tier 3 | Qdrant + NetworkX | Open Source, lokal hostbar, Python-native |
| Tier 4 | JSONL + gzip | Einfach, komprimierbar, durchsuchbar |

## Datum

2026-06-03