Initial commit: Project structure, README, AGENTS.md, .env.example, docs

- README.md with project overview, status, architecture - AGENTS.md with agent context and conventions - .env.example with environment variables - docs/research/agent-memory-solutions-2026.md (full research) - docs/architecture/memory-tiers.md (4-tier architecture) - docs/decisions/ADR-001-structured-memory-blocks.md - Directory structure for src/, tests/, scripts/, logs/, data/
2026-06-03 22:25:43 +00:00
commit 33fb180855
6 changed files with 798 additions and 0 deletions
@@ -0,0 +1,337 @@
+# Deep Research: Agent Memory & Context Rot Solutions (2026)
+
+## Executive Summary
+
+LLM-basierte Agenten verlieren ihren Zustand bei Context-Compression, weil Token-Limits durch verlustbehaftete Summarization oder naive Truncation "gelöst" werden. Die Lösung ist kein größeres Kontextfenster, sondern **hierarchisches, strukturiertes Memory-Management** über mehrere Tiers — von Working Memory (aktiver Prompt) bis Long-Term Memory (Vektor-Store + Knowledge Graph). Projekte wie **Letta** (OS-ähnliches Memory), **Mem0** (Multi-Level Personal Memory), und **Zep** (asynchrone Long-Term Context) adressieren das Problem aktiv. Für Hermes Agent bedeutet das: Memory muss von flachem Key-Value zu strukturierten, gelabelten Blöcken mit Entity-Linking und temporaler Abfrage werden.
+
+---
+
+## 1. Context Rot: Warum Agenten ihren Zustand verlieren
+
+### Technische Ursachen
+
+| Mechanismus | Beschreibung | Auswirkung |
+|------------|-------------|------------|
+| **Token-Limits** | Jedes LLM hat festes Kontextfenster (4K–2M Tokens) | Ältere Nachrichten müssen entfernt werden |
+| **Naive Truncation** | Einfaches Abschneiden alter Nachrichten | Kompletter Verlust aller Informationen vor dem Cutoff |
+| **Summarization** | KI-generierte Zusammenfassung bei ~90% Auslastung | Verlust von Details, Nuancen, implizitem Zustand |
+| **Sliding Window** | FIFO-Buffer, alte Nachrichten fallen raus | Keine Persistenz, keine Rückwärtsnavigation |
+| **Session Reset** | Neue Session = leerer Kontext | Totaler Zustandsverlust ohne Memory-Injection |
+
+### Warum Summarization zerstört
+
+Die meisten Frameworks (LangChain, etc.) ersetzen bei Erreichen eines Schwellenwerts (typisch 90% des Kontextfensters) die ältesten Nachrichten durch eine einzelne Zusammenfassung. Das Problem:
+- **Verlust von Tool-Konfigurationen**: "Wir haben gerade Docker-Compose auf Port 8080 konfiguriert" → "Docker wurde erwähnt"
+- **Verlust von Präferenzen**: "Nutzer hasst Bullet-Points, mag Tabellen mit │" → "Nutzer hat Formatierungspräferenzen"
+- **Verlust von Projekt-Zustand**: "Wir arbeiten an Zeile 47 in auth.service.ts" → "Es wurde an Authentifizierung gearbeitet"
+- **Halluzinationen**: Der Agent "ratet", was vorher passiert ist, anstatt es zu wissen
+
+### Der Hermes-spezifische Schmerz
+
+Hermes nutzt `session_search` für vergangene Sessions, aber:
+- **Keine automatische Memory-Extraktion**: Wichtige Fakten werden nicht automatisch aus Sessions gezogen
+- **Kein Entity-Linking**: "Projekt X" in Session A und "Projekt X" in Session B sind nicht verknüpft
+- **Keine Temporalität**: "Was war der letzte Stand?" kann nicht beantwortet werden
+- **Memory-Tool ist manuell**: Der Nutzer muss aktiv `memory` aufrufen, um etwas zu speichern
+- **Keine hierarchische Struktur**: Alles ist flaches Key-Value, keine gelabelten Blöcke
+
+---
+
+## 2. Memory-Architekturen für Agenten
+
+### Memory-Typen (kognitive Psychologie)
+
+| Typ | Beschreibung | Beispiel für Agent |
+|-----|-------------|-------------------|
+| **Episodic** | Konkrete Ereignisse/Episoden | "Session vom 3.6.2026: Wir haben den Kundenprozess für Waldseilgarten modelliert" |
+| **Semantic** | Fakten, Konzepte, Beziehungen | "Nutzer bevorzugt Tabellen mit │-Trennern, kein SAP B1" |
+| **Procedural** | Wie man Dinge tut | "Für ECC-Integration: erst CODING.md lesen, dann planen" |
+| **Working** | Aktiver, kurzfristiger Kontext | "Wir sind gerade bei Zeile 47 in auth.service.ts" |
+
+### Speicher-Mechanismen
+
+| Mechanismus | Stärke | Schwäche | Beste für |
+|------------|--------|----------|-----------|
+| **Vector Stores** | Semantische Ähnlichkeitssuche | Keine strukturierten Beziehungen | Fakten, Dokumente, große Mengen |
+| **Knowledge Graphs** | Strukturierte Beziehungen, Reasoning | Aufbau-Komplexität | Entitäten, Beziehungen, Projekte |
+| **Structured Memory** | Typisierte Blöcke, Labels | Weniger flexibel als Vektor-Store | User-Prefs, Projekt-State, Skills |
+| **Key-Value (current)** | Einfach, schnell | Keine Semantik, keine Verknüpfung | Einfache Fakten, kurze Notizen |
+
+---
+
+## 3. Projekte & Frameworks im Detail
+
+### Letta (ehemals MemGPT) — OS-ähnliches Memory
+
+| Aspekt | Details |
+|--------|---------|
+| **GitHub** | `letta-ai/letta` |
+| **Kernidee** | Virtuelles Kontextfenster: Agent "denkt", er hat unendlichen Kontext, aber nur ein Subset ist im Prompt |
+| **Memory Blocks** | Strukturierte, gelabelte Blöcke: `human`, `persona`, `project`, `preferences` |
+| **Summarization** | Automatisch bei 90% Auslastung (`SUMMARIZATION_TRIGGER_MULTIPLIER = 0.9`) |
+| **Passage Manager** | Alle Nachrichten persistent gespeichert, auch nach Summarization |
+| **In-Context Messages** | Nur aktives Subset im Prompt, Rest aus DB geladen |
+| **Self-Management** | Eigene Memory-Tools: `core_memory_append`, `core_memory_replace`, `core_memory_delete` |
+| **Tool-Integration** | Agent kann selbst entscheiden, was wichtig ist und speichern |
+
+**Relevanz für Hermes**: Letta zeigt, dass Memory nicht passiv sein darf. Der Agent muss aktiv sein eigenes Memory verwalten können — nicht nur der Nutzer.
+
+### Mem0 — The Memory Layer for Personalized AI
+
+| Aspekt | Details |
+|--------|---------|
+| **GitHub** | `mem0ai/mem0` |
+| **Kernidee** | Multi-Level Memory für User, Session und Agent-State |
+| **Neuer Algorithmus (Apr 2026)** | Single-pass ADD-only Extraction, Entity Linking, Multi-Signal Retrieval |
+| **Retrieval** | Semantisch + BM25 + Entity Matching + Temporal Reasoning |
+| **Benchmarks** | 91.6 auf LoCoMo, 94.8 auf LongMemEval |
+| **Hybrid Search** | Kombination aus semantischer und Keyword-Suche |
+| **API** | Einfache REST-API für Integration in bestehende Agenten |
+
+**Relevanz für Hermes**: Mem0's Multi-Level-Approach passt perfekt zu Hermes' Profile-System. User-Memory + Session-Memory + Agent-State als separate Ebenen.
+
+### Zep AI — Long-Term Context for AI Assistants
+
+| Aspekt | Details |
+|--------|---------|
+| **GitHub** | `getzep/zep-python` |
+| **Kernidee** | Asynchrone Memory-Verarbeitung, die den Chat nicht blockiert |
+| **Auto-Summaries** | Generiert Zusammenfassungen aus Chat-Historie im Hintergrund |
+| **Fact Extraction** | Extrahiert Fakten ohne vordefiniertes Schema |
+| **Document Collections** | Vektor-Suche über Dokumente |
+| **Prompt-Strukturierung** | Automatisches Hinzufügen von Recent Messages + Summary + Relevant Context |
+
+**Relevanz für Hermes**: Zep's asynchrone Verarbeitung wäre ideal für Hermes' Cronjob-System — Memory-Extraktion im Hintergrund, nicht in der aktiven Session.
+
+### LangChain Memory — Modularer Ansatz
+
+| Memory-Typ | Funktion |
+|------------|----------|
+| `ConversationBufferMemory` | Speichert alle Nachrichten roh |
+| `ConversationSummaryMemory` | Summarisiert bei Overflow |
+| `VectorStoreRetrieverMemory` | RAG-basiertes Retrieval aus Vektor-Store |
+| `CombinedMemory` | Kombiniert mehrere Memory-Typen |
+
+**Relevanz für Hermes**: LangChain's modulares Design zeigt, dass Memory nicht entweder/oder sein muss. Mehrere Tiers gleichzeitig sind sinnvoll.
+
+### AutoGPT — Historischer Pioneer
+
+| Aspekt | Details |
+|--------|---------|
+| **GitHub** | `Significant-Gravitas/AutoGPT` |
+| **Historisch** | Einer der ersten Agenten mit Memory-Ansatz (2023) |
+| **Memory-Backends** | Lokale JSON, Redis, Pinecone, Weaviate |
+| **Aktueller Fokus** | Platform/Forge statt klassisches Memory |
+
+---
+
+## 4. Praktische Ansätze & Patterns
+
+### Memory-Tiers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 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           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Hierarchical Memory
+
+- **Session-Ebene**: Volle Nachrichten, aktueller Zustand
+- **Tages-Ebene**: Zusammenfassung der Sessions eines Tages
+- **Wochen-Ebene**: Zusammenfassung der Projekte einer Woche
+- **Monats-Ebene**: Langfristige Trends, gelernte Präferenzen
+
+### Checkpoint/Restore
+
+- Agent-State wird nach jedem signifikanten Schritt persistiert
+- Bei Context-Overflow oder Fehler: Restore auf letzten Checkpoint
+- Hermes-Analogon: `session_search` + Memory-Tool, aber automatisch
+
+### Session Bridging
+
+- Beim Start neuer Session: Relevante Memories aus vorherigen Sessions laden
+- "Memory Injection": System-Prompt wird mit relevantem Kontext angereichert
+- Hermes-Analogon: Aktuell manuell über `memory` tool, nicht automatisch
+
+### Memory Injection Patterns
+
+| Pattern | Beschreibung | Wann nutzen |
+|---------|-------------|-------------|
+| **RAG-Style** | Retrieve relevante Memories → Inject in Prompt | Große Memory-Mengen, semantische Suche |
+| **Structured Blocks** | Typisierte Memory-Blöcke mit festen Labels | User-Prefs, Projekt-State, wiederkehrende Daten |
+| **Self-Management** | Agent entscheidet selbst, was gespeichert/gelesen wird | Komplexe, langlebige Agenten |
+| **Hybrid** | Kombination aus RAG + Structured + Self-Management | Produktions-Agenten (Letta, Mem0) |
+
+---
+
+## 5. Hermes-spezifische Analyse & Empfehlungen
+
+### Was Hermes bereits hat
+
+| Feature | Status | Bewertung |
+|---------|--------|-----------|
+| `memory` Tool | ✅ Manuell | Nutzer muss aktiv speichern |
+| `session_search` | ✅ FTS5-basiert | Gut für Discovery, schlecht für State |
+| `skills` System | ✅ Wiederverwendbar | Prozedurales Memory, aber statisch |
+| `profile` System | ✅ Isoliert | Keine Cross-Profile Memory-Sync |
+| `cronjob` | ✅ Scheduler | Könnte Memory-Extraktion im Hintergrund machen |
+| `MEMORY.md` | ✅ Manuell | Nutzer muss selbst kuratieren |
+
+### Was Hermes braucht
+
+| Priorität | Feature | Beschreibung | Umsetzung |
+|-----------|---------|------------|-----------|
+| **P0** | **Auto-Extraction** | Automatisches Extrahieren von Fakten aus Sessions | Cronjob nach jeder Session |
+| **P0** | **Structured Blocks** | Gelabelte Memory-Blöcke statt flaches Key-Value | `memory` Tool erweitern |
+| **P1** | **Entity Linking** | Verknüpfung von Memories über Entitäten | Projekt-Namen, Personen, Konzepte |
+| **P1** | **Temporal Memory** | Zeitbewusstes Retrieval | "Was war der letzte Stand von X?" |
+| **P1** | **Multi-Tier** | Unterschiedliche Speicher-Ebenen | Working → Short-Term → Long-Term |
+| **P2** | **Self-Management** | Agent kann selbst Memory verwalten | Memory-Tools für Agenten |
+| **P2** | **Summarization-Persistenz** | Zusammenfassungen bei Compression speichern | Nicht verwerfen, sondern archivieren |
+
+### Konkrete Umsetzungsvorschläge für Hermes
+
+#### 1. Memory-Block-Schema (erweitertes `memory` Tool)
+
+```yaml
+# Statt:
+memory: "User prefers tables with │ separators"
+
+# Besser:
+memory_block:
+  type: "user_preference"
+  category: "formatting"
+  key: "table_style"
+  value: "compact with │ separators"
+  source: "session_2026-06-03"
+  confidence: 0.95
+  entities: ["Flo"]
+```
+
+#### 2. Auto-Extraction Cronjob
+
+```yaml
+# Nach jeder Session:
+cronjob:
+  schedule: "after_session_end"
+  action: "extract_memories"
+  # Extrahiert automatisch:
+  # - User preferences (Formatierung, Workflow)
+  # - Project state (aktuelle Dateien, offene Tasks)
+  # - Learned patterns (was hat funktioniert, was nicht)
+  # - Entity relationships (Projekt X → Datei Y → Config Z)
+```
+
+#### 3. 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. Session-Start Memory-Injection
+
+```
+# Bevor die Session startet:
+1. Suche relevante Memories für aktuellen Kontext
+2. Lade Project-State (letzter Stand)
+3. Lade User-Preferences (Formatierung, Workflow)
+4. Lade offene Tasks / TODOs
+5. Injected in System-Prompt
+```
+
+---
+
+## 6. Vergleich: Bestehende Lösungen
+
+| Projekt | Memory-Typ | Self-Mgmt | Multi-Tier | Entity-Linking | Temporal | Integration | Open Source |
+|---------|-----------|-----------|------------|----------------|----------|-------------|-------------|
+| **Letta** | Structured Blocks | ✅ | ✅ | ✅ | ✅ | Python SDK | ✅ |
+| **Mem0** | Multi-Level | ❌ | ✅ | ✅ | ✅ | REST API | ✅ |
+| **Zep** | Async + Facts | ❌ | ✅ | ✅ | ✅ | Python/JS SDK | ✅ |
+| **LangChain** | Modular | ❌ | ✅ | ❌ | ❌ | Python/JS | ✅ |
+| **AutoGPT** | Configurable | ❌ | ❌ | ❌ | ❌ | Python | ✅ |
+| **Hermes (current)** | Key-Value | ❌ | ❌ | ❌ | ❌ | Built-in | ✅ |
+
+---
+
+## 7. Empfehlungen für Hermes
+
+### Kurzfristig (1–2 Wochen)
+
+1. **Memory-Blocks erweitern**: `memory` Tool um `type`, `category`, `entities` erweitern
+2. **Auto-Extraction-Prototype**: Cronjob, der nach Sessions automatisch Fakten extrahiert (basierend auf `session_search` + LLM-Summarization)
+3. **Project-State-Memory**: Automatisches Speichern von aktuellem Projekt, offenen Dateien, letzten Änderungen
+
+### Mittelfristig (1–2 Monate)
+
+1. **Entity-Linking**: Einfacher Graph, der Projekte, Dateien, Personen, Konzepte verknüpft
+2. **Multi-Tier Memory**: SQLite für Short-Term, Vektor-Store (Chroma/Qdrant) für Long-Term
+3. **Session-Start Injection**: Automatisches Laden relevanter Memories beim Session-Start
+
+### Langfristig (3–6 Monate)
+
+1. **Self-Management**: Agent kann selbst entscheiden, was wichtig ist
+2. **Hierarchical Summarization**: Tages-/Wochen-/Monats-Zusammenfassungen
+3. **Cross-Profile Memory**: Geteilte Fakten über Profile hinweg (User-Prefs bleiben gleich)
+
+---
+
+## 8. Quellen & Referenzen
+
+### Primärquellen (GitHub)
+
+| Projekt | URL | Analysierte Dateien |
+|---------|-----|---------------------|
+| **Letta** | `https://github.com/letta-ai/letta` | `letta/agent.py`, `letta/memory.py`, `letta/system.py`, `letta/persistence_manager.py` |
+| **Mem0** | `https://github.com/mem0ai/mem0` | `mem0/memory/main.py`, `mem0/configs/base.py`, `mem0/utils/main.py` |
+| **Zep** | `https://github.com/getzep/zep-python` | `zep_python/client.py`, `zep_python/memory.py` |
+| **AutoGPT** | `https://github.com/Significant-Gravitas/AutoGPT` | `autogpt/memory/` |
+| **LangChain** | `https://github.com/langchain-ai/langchain` | `langchain/memory/` |
+
+### Dokumentation
+
+- Letta Docs: `https://docs.letta.com/` — Memory Blocks, System Prompts, Tool Integration
+- Mem0 Docs: `https://docs.mem0.ai/` — Memory Layer, Multi-Level Architecture, API Reference
+- Zep Docs: `https://docs.getzep.com/` — Long-Term Memory, Fact Extraction, Async Processing
+- LangChain Memory: `https://python.langchain.com/docs/modules/memory/` — Buffer, Summary, Vector Store
+
+### Papers & Benchmarks
+
+- LoCoMo Benchmark: Long-Context Memory Evaluation
+- LongMemEval: Long-term Memory Evaluation for Conversational Agents
+- Mem0 Benchmarks (Apr 2026): 91.6 LoCoMo, 94.8 LongMemEval
+
+### Hermes-Intern
+
+- `memory` Tool: `~/.hermes/memory/` (user + memory stores)
+- `session_search`: SQLite FTS5 in `~/.hermes/sessions.db`
+- `skills`: `~/.hermes/skills/` (prozedurales Memory)
+- `cronjob`: `~/.hermes/cron/` (Scheduler für Background-Tasks)
+
+---
+
+*Recherche durchgeführt: Juni 2026*
+*SearXNG war für API-Anfragen nicht verfügbar (403 Forbidden), daher primär über direkte GitHub-Source-Analyse*