# Konzept: Hermes Memory Next Level

## 1. Executive Summary

Hermes Memory Next Level (HMNL) ist ein hierarchisches, strukturiertes Memory-Upgrade für den Hermes Agent. Es löst das "Context Rot"-Problem, bei dem KI-Agenten nach Session-Wechseln oder Context-Compressionen wichtige Zustände, Präferenzen und Projekt-Details verlieren. Statt flachem Key-Value-Speicher nutzt HMNL vier Memory-Tiers mit automatischer Fakten-Extraktion, Entity-Linking und semantischer Suche.

**Status**: Konzept + Prototyp (Architektur implementiert, Integration geplant)
**Zielgruppe**: Hermes Agent Nutzer, KI-Agent-Entwickler, Systemintegratoren
**Lizenz**: Open Source

---

## 2. Problemstellung

### 2.1 Context Rot

LLM-basierte Agenten haben feste Token-Limits (4K–2M). Bei Erreichen des Limits werden ältere Nachrichten entfernt oder zusammengefasst. Das führt zu:

| Was verloren geht | Beispiel vor Compression | Beispiel nach Compression |
|-------------------|-------------------------|---------------------------|
| Tool-Konfigurationen | "Docker-Compose auf Port 8080" | "Docker wurde erwähnt" |
| Projekt-Zustände | "Zeile 47 in auth.service.ts" | "An Auth gearbeitet" |
| User-Präferenzen | "Tabellen mit │-Trennern, keine Bullets" | "Formatierungspräferenzen" |
| Gelernte Patterns | "pytest -n 4 funktioniert hier" | "Tests wurden erwähnt" |

### 2.2 Hermes-spezifische Probleme

| Feature | Aktueller Zustand | Problem |
|---------|-----------------|---------|
| `memory` Tool | Manuell, flaches Key-Value | Nutzer muss aktiv speichern; keine Typisierung |
| `session_search` | FTS5-basiert | Findet Sessions, aber nicht den Zustand darin |
| `skills` | Prozedurales Memory | Statisch, nicht automatisch aktualisiert |
| `profile` | Isoliert | Keine Cross-Profile Memory-Sync |
| Context | Session-bound | Nach Compression oder Neustart = Tabula Rasa |

### 2.3 Geschäftlicher Impact

- **Zeitverlust**: Nutzer wiederholt Erklärungen (5–15 Minuten pro Session)
- **Fehler**: Agent "ratet" statt zu wissen → falsche Entscheidungen
- **Frustration**: Kontinuitätsverlust mindert Akzeptanz
- **Skalierungsgrenze**: Lange Projekte (>1h) werden unmöglich

---

## 3. Vision & Ziele

### 3.1 Vision

> Memory wird von **manuell** und **flach** zu **automatisch** und **strukturiert**. Der Agent merkt sich nicht nur, was der Nutzer sagt — sondern versteht, warum es wichtig ist, verknüpft es mit anderen Fakten und ruft es automatisch ab, wenn es relevant wird.

### 3.2 Ziele

| Ziel | Metrik | Zielwert |
|------|--------|----------|
| Reduktion Wiederholungen | Nutzer muss X-mal weniger erklären | -80% |
| Kontinuität | Agent erinnert sich an Projekt nach 7 Tagen | 95% |
| Auto-Extraction | Fakten werden ohne manuelles Speichern erkannt | 90% Recall |
| Retrieval-Qualität | Relevante Memories werden gefunden | 95% Precision |
| Latenz | Memory-Abfrage < 100ms | 99th Percentile |

---

## 4. Architektur

### 4.1 Überblick: 4-Tier Memory

```
┌─────────────────────────────────────────────────────────────┐
│ TIER 1: WORKING MEMORY (Aktiver Prompt)                     │
│ • Aktuelle Nachrichten + injizierter Kontext                │
│ • 4K–128K Tokens (modellabhängig)                           │
│ • Zugriff: Synchron, < 1ms                                  │
├─────────────────────────────────────────────────────────────┤
│ TIER 2: SHORT-TERM MEMORY (SQLite)                           │
│ • Letzte 5–10 Sessions, vollständige Nachrichten            │
│ • Zugriff: Synchron, ~1–5ms                                 │
│ • Lifecycle: 30 Tage, dann Archivierung                     │
├─────────────────────────────────────────────────────────────┤
│ TIER 3: LONG-TERM MEMORY (Vektor + Graph)                    │
│ • Memory Blocks, Entities, Beziehungen                     │
│ • Zugriff: Asynchron, ~10–50ms                              │
│ • Lifecycle: Permanent                                      │
├─────────────────────────────────────────────────────────────┤
│ TIER 4: ARCHIVE (Komprimiert)                               │
│ • Vollständige Historie, alle Sessions                     │
│ • Zugriff: Asynchron, ~100ms–1s                             │
│ • Lifecycle: Permanent, komprimiert                         │
└─────────────────────────────────────────────────────────────┘
```

### 4.2 Datenfluss: Session → Memory

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Session │───▶│  Chunking│───▶│Pre-Filter│───▶│  LLM     │
│  (SQLite)│    │(Sliding) │    │(Heuristik│    │Extract.  │
└──────────┘    └──────────┘    └──────────┘    └────┬─────┘
                                                     │
                              ┌──────────┐    ┌──────▼─────┐
                              │  Store   │◄───│  Klassif.  │
                              │  Tier 2/3│    │  + Entity  │
                              └──────────┘    │  + Temporal│
                                              └────────────┘
```

### 4.3 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"
  ttl_days: 365  # user_preference: 1 Jahr
```

### 4.4 Entity-Linking Graph

```
[User: Flo] --prefers--> [Format: Tables with │]
[User: Flo] --works_on--> [Project: waldseilgarten-crm]
[Project: waldseilgarten-crm] --has_file--> [File: docker-compose.yml]
[Project: waldseilgarten-crm] --uses--> [Tech: NestJS + React]
[Session: 2026-06-03] --discussed--> [Topic: Kundenprozess]
```

### 4.5 Auto-Extraction Pipeline

| Schritt | Beschreibung | Technologie |
|---------|-------------|-------------|
| **Chunking** | Sliding-Window über Session, max 3500 Tokens/Chunk | Python |
| **Pre-Filter** | Heuristisches Scoring: Code/Config (+3), Präferenzen (+2), Projekt (+2) | Regex + Keywords |
| **LLM Extraction** | JSON-Output: type, confidence, subject, predicate, object, context, temporal, entities | LLM (lokal oder API) |
| **Klassifikation** | 5 Kategorien mit TTL: user_preference (1y), project_state (3m), learned_pattern (6m), entity_relationship (1y), procedural (6m) | Regelbasiert |
| **Entity-Linking** | Alias-Matching (O(1)), Embedding-Similarity (Threshold 0.85), Coreference-Resolution | NetworkX + Embeddings |
| **Temporal Reasoning** | Regex-basierte Datums-Extraktion, Gültigkeits-Engine | Python + dateutil |
| **Deduplizierung** | Exakter Key-Match (Subject::Predicate::Object), Cosine-Similarity (Threshold 0.92) | SHA-256 + Embeddings |

---

## 5. Technologie-Stack

| Komponente | Technologie | Begründung |
|------------|-------------|------------|
| **Tier 2 (Short-Term)** | SQLite + FTS5 | Einfach, schnell, kein extra Service, nativ in Hermes |
| **Tier 3 (Vektor)** | Chroma oder Qdrant | Open Source, lokal hostbar, Python-native, gute Performance |
| **Tier 3 (Graph)** | NetworkX | Python-native, GraphML-Persistenz, keine DB-Abhängigkeit |
| **Embeddings** | sentence-transformers (lokal) oder Ollama | Privacy, keine API-Kosten, subbie hat 48GB VRAM |
| **LLM für Extraction** | Ollama (lokal) oder gleiches Modell | Speed, Kosten, Privacy |
| **API** | Python (FastAPI optional) | Hermes-native, einfache Integration |
| **Cron/Scheduler** | Hermes Cronjob-System | Bestehende Infrastruktur nutzen |
| **Integration** | Hermes Memory Provider Plugin | Minimal invasive, kein Core-Fork |

---

## 6. Integration in Hermes Agent

### 6.1 Strategie: Memory Provider Plugin

Hermes hat bereits ein `MemoryProvider` ABC mit Hooks:
- `initialize()` — Setup beim Agent-Start
- `prefetch()` — Relevante Memories für Session-Start
- `sync_turn()` — Nach jeder Conversation-Turn
- `on_session_end()` — Session-Abschluss
- `get_tool_schemas()` — Zusätzliche Tools für den Agenten

HMNL implementiert dieses ABC als neues Plugin unter `plugins/memory/nextlevel/`.

### 6.2 Session-Start Injection

```python
def prefetch(self, query: str, context: dict) -> str:
    # 1. Semantische Suche über Tier 3 (Vektor + Graph)
    relevant_blocks = self.tier3.search(query, context)
    
    # 2. Graph-Traversal für verwandte Entities
    related_entities = self.graph.expand(relevant_blocks.entities)
    
    # 3. Tier 2: Letzte Sessions für Kurzzeit-Kontext
    recent_sessions = self.tier2.get_recent(limit=5)
    
    # 4. Formatierung als Memory-Context Block
    return format_memory_context(relevant_blocks, related_entities, recent_sessions)
```

### 6.3 Auto-Extraction Trigger

| Trigger | Wann | Was |
|---------|------|-----|
| `sync_turn()` | Nach jeder Nachricht | Wichtige Fakten sofort extrahieren |
| Cronjob | Nach Session-Ende | Batch-Verarbeitung aller unverarbeiteten Sessions |
| Manual | Auf Nutzer-Anfrage | "Speichere das als Memory" |

### 6.4 Neue Tools für den Agenten

| Tool | Funktion |
|------|----------|
| `nextlevel_search` | Semantische Suche über alle Tiers |
| `nextlevel_remember` | Explizites Speichern mit Typisierung |
| `nextlevel_forget` | Löschen oder TTL-Update |
| `nextlevel_graph` | Entity-Graph exploration |
| `nextlevel_stats` | Memory-Übersicht (Größe, Verteilung, Zugriff) |

### 6.5 Hermes Core Änderungen

**Minimal**: Praktisch keine. Optional:
- `extracted` Flag in `state.db` Sessions-Tabelle
- `on_cron_tick()` Hook im `MemoryProvider` ABC
- Cron-Post-Job Hook für Memory-Extraction

---

## 7. Implementierungsplan

### 7.1 Phasen

| Phase | Dauer | Inhalt | Deliverable |
|-------|-------|--------|-------------|
| **P0: Foundation** | ~4h | Plugin-Struktur, Hermes-Integration, Config | Plugin lädt, `prefetch()` läuft |
| **P1: Tier 2** | ~8h | SQLite-Schema, FactStore, EntityStore, Timeline | Short-Term Memory vollständig |
| **P2: Tier 3** | ~8h | Vektor-Backend, Embeddings, Graph-Store | Long-Term Memory + semantische Suche |
| **P3: Graph** | ~6h | Entity-Linking, Graph-Traversal, Visualization | Knowledge Graph vollständig |
| **P4: Extraction** | ~4h | Auto-Extraction Pipeline, Cronjobs | Fakten werden automatisch extrahiert |
| **P5: Tests** | ~2h | Unit + Integration Tests, Dokumentation | 90% Coverage, Docs vollständig |

**Gesamt: ~32h** (bei konzentrierter Arbeit)

### 7.2 Milestones

| Milestone | Datum | Kriterium |
|-----------|-------|-----------|
| M1: Plugin lädt | +1 Tag | `prefetch()` gibt Memory-Context zurück |
| M2: Tier 2 läuft | +3 Tage | Sessions werden in SQLite gespeichert, FTS5 funktioniert |
| M3: Tier 3 läuft | +5 Tage | Vektor-Suche findet relevante Memories |
| M4: Graph läuft | +7 Tage | Entity-Linking verknüpft Projekte, Dateien, Personen |
| M5: Auto-Extract | +9 Tage | Cronjob extrahiert Fakten aus Sessions |
| M6: Release | +10 Tage | Tests grün, Docs vollständig, Nutzer-Test bestanden |

---

## 8. Vergleich mit Alternativen

### 8.1 Bestehende Lösungen

| Projekt | Ansatz | Self-Mgmt | Multi-Tier | Entity-Linking | Integration | Lokal | Open Source |
|---------|--------|-----------|------------|----------------|-------------|-------|-------------|
| **Letta** | OS-ähnliches Memory | ✅ | ✅ | ✅ | Python SDK | ✅ | ✅ |
| **Mem0** | Multi-Level Memory | ❌ | ✅ | ✅ | REST API | ❌ | ✅ |
| **Zep** | Async Long-Term | ❌ | ✅ | ✅ | Python/JS SDK | ❌ | ✅ |
| **LangChain** | Modular | ❌ | ✅ | ❌ | Python/JS | ✅ | ✅ |
| **AutoGPT** | Configurable | ❌ | ❌ | ❌ | Python | ✅ | ✅ |
| **Hermes (current)** | Key-Value | ❌ | ❌ | ❌ | Built-in | ✅ | ✅ |
| **HMNL (geplant)** | Hierarchisch + Plugin | ✅ | ✅ | ✅ | Hermes Plugin | ✅ | ✅ |

### 8.2 Differenzierung

| Aspekt | Andere | HMNL |
|--------|--------|------|
| **Integration** | Separate Frameworks | Native Hermes Plugin |
| **Deployment** | Cloud oder komplex | Lokal, SQLite, kein extra Service |
| **Kosten** | API-Kosten für Embeddings | Lokal (Ollama/sentence-transformers) |
| **Privacy** | Daten verlassen Maschine | Alles lokal |
| **Auto-Extract** | Teilweise | Vollständig mit Klassifikation |
| **Entity-Linking** | Teilweise | Knowledge Graph mit Traversal |
| **Session-Start** | Manuelles Laden | Automatische Injection |

---

## 9. Risiken & Mitigation

| Risiko | Wahrscheinlichkeit | Impact | Mitigation |
|--------|-------------------|--------|------------|
| **Embedding-Performance** | Mittel | Hoch | Ollama auf subbie (48GB VRAM), Fallback auf CPU |
| **SQLite-Skalierung** | Niedrig | Mittel | Migration zu PostgreSQL optional, VACUUM regelmäßig |
| **LLM-Extraction-Qualität** | Mittel | Hoch | Pre-Filter reduziert Noise, Confidence-Threshold, manuelle Review |
| **Hermes Core Breaking Changes** | Niedrig | Hoch | Plugin-Architektur isoliert, ABC stabil |
| **Nutzer-Akzeptanz** | Mittel | Mittel | Graduelle Einführung, manuelles Memory bleibt verfügbar |
| **Token-Overhead** | Mittel | Mittel | Memory-Context limitiert (max 2K Tokens), Relevanz-Scoring |

---

## 10. Erfolgskriterien & Metriken

### 10.1 Technische Metriken

| Metrik | Baseline | Ziel | Messung |
|--------|----------|------|---------|
| Memory-Latenz (Tier 2) | — | < 5ms | Benchmark-Script |
| Memory-Latenz (Tier 3) | — | < 50ms | Benchmark-Script |
| Extraction-Recall | — | > 90% | Manuell gelabelte Sessions |
| Extraction-Precision | — | > 85% | Manuell gelabelte Sessions |
| Deduplizierung | — | < 5% False Positives | Stichprobe |
| Speicherplatz (Tier 2) | — | < 100MB / 100 Sessions | `du -sh` |
| Speicherplatz (Tier 3) | — | < 500MB / 1000 Blocks | `du -sh` |

### 10.2 Nutzer-Metriken

| Metrik | Baseline | Ziel | Messung |
|--------|----------|------|---------|
| Wiederholungen pro Session | 3–5x | < 1x | Nutzer-Feedback |
| Session-Effizienz | — | +30% | Vergleich vor/nach |
| Nutzer-Zufriedenheit | — | > 4/5 | Umfrage |
| Feature-Adoption | — | > 80% | Tool-Usage-Stats |

---

## 11. Offene Entscheidungen

| Entscheidung | Optionen | Empfehlung | Status |
|--------------|----------|------------|--------|
| **Embedding-Modell** | A: sentence-transformers (CPU) / B: OpenAI API / C: Ollama (GPU) | C: Ollama auf subbie | Offen |
| **Hermes Integration** | A: Plugin / B: Core-Modifikation / C: Fork | A: Plugin | Offen |
| **Auto-Extract Trigger** | A: Nach Session / B: Nach jeder Nachricht / C: Hybrid | C: Hybrid | Offen |
| **Migration** | A: Manuell / B: Automatisch / C: Beides | C: Beides | Offen |
| **Deployment** | A: Direkt / B: pip / C: Docker | A für Dev, B für Prod | Offen |
| **LLM für Extraction** | A: Gleiches Modell / B: Kleineres lokal / C: Dediziertes | B: Ollama lokal | Offen |

---

## 12. Anhänge

### 12.1 Projektstruktur

```
hermes-memory-next-level/
├── AGENTS.md              # Agent-Context
├── README.md              # Projekt-Übersicht
├── ARCHITECTURE.md        # Detaillierte Architektur
├── INTEGRATION_PLAN.md    # Integrationsplan
├── .env.example           # Umgebungsvariablen
├── pyproject.toml         # Package-Definition
├── docs/
│   ├── research/
│   │   └── agent-memory-solutions-2026.md
│   ├── architecture/
│   │   └── memory-tiers.md
│   ├── decisions/
│   │   └── ADR-001-structured-memory-blocks.md
│   └── pitch-60sec.md
├── src/
│   ├── extraction/        # Auto-Extraction Pipeline
│   ├── storage/             # Tier 2/3 Implementierungen
│   ├── graph/               # Knowledge Graph
│   ├── injection/           # Session-Start Injection
│   └── api/                 # REST API + Unified Interface
├── tests/
│   ├── unit/
│   └── integration/
├── scripts/
│   └── setup.sh
└── docker-compose.yml
```

### 12.2 Referenzen

| Quelle | URL | Beschreibung |
|--------|-----|--------------|
| Letta | https://github.com/letta-ai/letta | OS-ähnliches Memory |
| Mem0 | https://github.com/mem0ai/mem0 | Multi-Level Memory |
| Zep | https://github.com/getzep/zep-python | Async Long-Term |
| LangChain Memory | https://python.langchain.com/docs/modules/memory/ | Modular Memory |
| Hermes Agent | https://hermes-agent.nousresearch.com/docs/ | Hermes Dokumentation |

### 12.3 Glossary

| Begriff | Definition |
|---------|------------|
| **Context Rot** | Verlust von Agent-Zustand durch Context-Compression oder Session-Wechsel |
| **Memory Tier** | Hierarchische Speicher-Ebene mit unterschiedlicher Geschwindigkeit und Kapazität |
| **Memory Block** | Strukturierte, typisierte Memory-Einheit mit Metadaten |
| **Entity-Linking** | Verknüpfung von Entitäten (Personen, Projekte, Dateien) in einem Graphen |
| **Auto-Extraction** | Automatisches Erkennen und Speichern von Fakten aus Conversations |
| **Session-Start Injection** | Automatisches Laden relevanter Memories in den System-Prompt |
| **Embedding** | Vektor-Repräsentation von Text für semantische Suche |
| **Knowledge Graph** | Graph-basierte Darstellung von Entitäten und Beziehungen |
| **TTL** | Time-To-Live: Gültigkeitsdauer eines Memory Blocks |
| **FTS5** | Full-Text Search: SQLite-Erweiterung für Volltextsuche |

---

*Konzept erstellt: Juni 2026*
*Version: 1.0*
*Autor: AI Council (3 parallele Agenten + Synthese)*
*Projekt: https://gitea.insight-it.de:2222/b0rbor4d/Hermes-Memory-Next-Level.git*