Hermes-Memory-Next-Level/docs/KONZEPT.md

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

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

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