diff --git a/docs/KONZEPT.md b/docs/KONZEPT.md new file mode 100644 index 0000000..101d39b --- /dev/null +++ b/docs/KONZEPT.md @@ -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*