# Hermes Memory Next Level

> Lösung für Context Rot und Agent Memory bei Hermes Agent. Von manuellem Key-Value zu strukturiertem, hierarchischem, automatischem Memory.

## Problem

Hermes verliert nach Context-Compression oder Session-Wechsel wichtigen Zustand:
- Tool-Konfigurationen werden zu "Docker wurde erwähnt"
- Projekt-Zustände zu "Wir haben an Auth gearbeitet"
- Präferenzen verschwinden komplett
- Nutzer muss dieselben Dinge immer wieder erklären

## Vision

Memory wird von **manuell** und **flach** zu **automatisch** und **strukturiert**:
- Auto-Extraktion aus jeder Session
- Typisierte Memory-Blöcke mit Entity-Linking
- Multi-Tier: Working → Short-Term → Long-Term
- Session-Start Injection: Relevanter Kontext wird automatisch geladen

## Status

| Phase | Status | Ziel |
|-------|--------|------|
| P0 Auto-Extraction | 🔄 In Planung | Cronjob extrahiert Fakten aus Sessions |
| P0 Structured Blocks | 🔄 In Planung | Erweitertes `memory` Tool mit Typen |
| P1 Entity-Linking | ⏳ Pending | Graph: Projekte, Dateien, Personen verknüpfen |
| P1 Temporal Memory | ⏳ Pending | "Was war der letzte Stand von X?" |
| P1 Multi-Tier | ⏳ Pending | SQLite + Vektor-Store |
| P2 Self-Management | ⏳ Pending | Agent speichert selbst |
| P2 Session Injection | ⏳ Pending | Automatisches Laden beim Start |

## Architektur

```
┌─────────────────────────────────────────────────────────────┐
│ 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           │
└─────────────────────────────────────────────────────────────┘
```

## Memory-Block-Schema

```yaml
memory_block:
  id: "uuid"
  type: "user_preference" | "project_state" | "learned_pattern" | "entity_relationship" | "procedural"
  category: "formatting" | "workflow" | "tech_stack" | "contact" | "project" | "skill"
  key: "table_style"
  value: "compact with │ separators"
  source: "session_2026-06-03"
  confidence: 0.95
  entities: ["Flo", "waldseilgarten-crm"]
  created_at: "2026-06-03T14:30:00Z"
  updated_at: "2026-06-03T14:30:00Z"
  access_count: 1
  last_accessed: "2026-06-03T14:30:00Z"
```

## Projektstruktur

```
hermes-memory-next-level/
├── AGENTS.md              # Agent-Context (wer ist der Agent, was soll er wissen)
├── README.md              # Diese Datei
├── .env.example           # Umgebungsvariablen
├── docs/
│   ├── research/
│   │   └── agent-memory-solutions-2026.md
│   ├── architecture/
│   │   └── memory-tiers.md
│   └── decisions/
│       └── ADR-001-structured-memory-blocks.md
├── src/
│   ├── extraction/        # Auto-Extraction aus Sessions
│   ├── storage/           # Memory-Tier-Implementierungen
│   ├── graph/             # Entity-Linking Graph
│   ├── injection/         # Session-Start Injection
│   └── api/               # REST API für Memory-Operationen
├── tests/
│   ├── unit/
│   └── integration/
├── scripts/
│   └── setup.sh           # Setup-Script
└── docker-compose.yml     # Für lokale Entwicklung (SQLite, Qdrant, etc.)
```

## Remote

- **Gitea**: `ssh://git@gitea.insight-it.de:2222/b0rbor4d/Hermes-Memory-Next-Level.git`
- **SSH-Key**: `id_ed25519` (lokal vorhanden, muss in Gitea hinterlegt werden)

## Mitwirkung

ECC-Standards gelten. Siehe `AGENTS.md` und `CODING.md` (wenn vorhanden).

---

*Projekt gestartet: Juni 2026*
*Ziel: Context Rot eliminieren, Hermes Memory auf Next-Level bringen*