Add comprehensive KONZEPT.md for external agent review

- 12 sections: Executive Summary, Problem, Vision, Architecture, Technology Stack, Integration, Implementation Plan, Comparison, Risks, Success Metrics, Open Decisions, Appendices - Includes data flow diagrams, schema definitions, milestones - Glossary, references, project structure - Ready for distribution to other AI agents for evaluation
2026-06-04 00:08:17 +00:00
parent cb0a241e73
commit 830a804eb3
1 changed files with 392 additions and 0 deletions
@@ -0,0 +1,392 @@
+# 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*