From 33fb18085572d996a4248d8baa38d029c6ecec3d Mon Sep 17 00:00:00 2001 From: Florian Hartmann Date: Wed, 3 Jun 2026 22:25:43 +0000 Subject: [PATCH] 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/ --- .env.example | 30 ++ AGENTS.md | 74 ++++ README.md | 117 ++++++ docs/architecture/memory-tiers.md | 166 +++++++++ .../ADR-001-structured-memory-blocks.md | 74 ++++ docs/research/agent-memory-solutions-2026.md | 337 ++++++++++++++++++ 6 files changed, 798 insertions(+) create mode 100644 .env.example create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 docs/architecture/memory-tiers.md create mode 100644 docs/decisions/ADR-001-structured-memory-blocks.md create mode 100644 docs/research/agent-memory-solutions-2026.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..f17dfe1 --- /dev/null +++ b/.env.example @@ -0,0 +1,30 @@ +# Umgebungsvariablen für Hermes Memory Next Level +# Kopiere nach .env und passe Werte an + +# ── Datenbank ─────────────────────────────────────────────── +DB_PATH=./data/memory.db +VECTOR_DB_URL=http://localhost:6333 +VECTOR_DB_COLLECTION=hermes_memory + +# ── API ───────────────────────────────────────────────────── +API_HOST=0.0.0.0 +API_PORT=8000 +API_KEY=change-me-in-production + +# ── Hermes Integration ────────────────────────────────────── +HERMES_HOME=/home/b0rbor4d/.hermes +HERMES_SESSIONS_DB=/home/b0rbor4d/.hermes/sessions.db +HERMES_MEMORY_DIR=/home/b0rbor4d/.hermes/memory + +# ── Extraction ────────────────────────────────────────────── +EXTRACTION_MODEL=kimi-k2.6 +EXTRACTION_BATCH_SIZE=10 +EXTRACTION_CONFIDENCE_THRESHOLD=0.7 + +# ── Logging ───────────────────────────────────────────────── +LOG_LEVEL=INFO +LOG_FILE=./logs/hermes-memory.log + +# ── Gitea ─────────────────────────────────────────────────── +GITEA_URL=https://gitea.insight-it.de +GITEA_SSH_PORT=2222 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..15750ce --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# AGENTS.md - Hermes Memory Next Level + +## Wer ist der Agent? + +Du bist ein AI-Assistent, der an einem Projekt arbeitet, um **Context Rot** und das **Agent Memory Problem** bei Hermes Agent zu lösen. + +## Was ist das Projekt? + +**Hermes Memory Next Level** — ein Upgrade des bestehenden Memory-Systems von manuellem Key-Value zu strukturiertem, hierarchischem, automatischem Memory. + +## Was soll der Agent wissen? + +### Kontext +- Hermes Agent hat aktuell ein manuelles `memory` Tool (flaches Key-Value) +- `session_search` findet Sessions, aber nicht den Zustand darin +- Nach Context-Compression verliert der Agent Tool-Konfigurationen, Projekt-Zustände, Präferenzen +- Der Nutzer (Flo) muss dieselben Dinge ständig wiedererklären + +### Ziel +- Memory wird automatisch aus Sessions extrahiert +- Typisierte Memory-Blöcke mit Entity-Linking +- Multi-Tier: Working → Short-Term → Long-Term +- Session-Start Injection: Relevanter Kontext wird automatisch geladen + +### Technologie-Stack (geplant) +- Python (Extraktion, API) +- SQLite (Short-Term Memory) +- Qdrant/Chroma (Long-Term Vektor-Store) +- NetworkX/Neo4j (Entity Graph) +- Hermes-native Integration (Cronjobs, Skills) + +### Nutzer-Präferenzen (Flo) +- **Sprache**: Deutsch für alle automatisierten Ausgaben +- **Formatierung**: Kompakte Tabellen mit `│`-Trennern, fette Headers, keine Bullet-Points +- **Kommunikation**: Sachlich, emotionsfrei, direkt, kompakt, ergebnisorientiert +- **Workflow**: Read COMPLETELY mit `read_file`, collaborative, fragt nach Ideen +- **ECC**: affaan-m/ECC für ALLE Projekte + +## Sicherheit +- Keine privaten Daten exfiltrieren +- Keine destruktiven Befehle ohne Rückfrage +- `trash` > `rm` + +## Extern vs Intern +- **Frei**: Lesen, explorieren, organisieren, lernen +- **Rückfrage**: Emails, Posts, alles was die Maschine verlässt + +## Memory +- Tägliche Notizen: `memory/YYYY-MM-DD.md` +- Langfristig: `MEMORY.md` (nur in Main Session) +- Text > Brain — alles aufschreiben + +## Coding Workflow +1. `CODING.md` lesen (ECC Standards) +2. Success-Kriterien definieren +3. Annahmen formulieren +4. Plan mit Verifikation +5. Simplicity First, Surgical Changes, Verify each step +6. Diff review, Cleanup, Document + +## Tools +- Skills sind die primären Werkzeuge +- Lokale Notizen in `TOOLS.md` +- `sag` (ElevenLabs TTS) für Voice Storytelling + +## Heartbeats +- `HEARTBEAT.md` lesen, wenn vorhanden +- Produktive Checks: Email, Calendar, Weather +- Proaktive Arbeit ohne Rückfrage: Memory-Dateien organisieren, Projekte checken + +## Make It Yours +- Füge eigene Konventionen, Stil und Regeln hinzu +- Was funktioniert, wird behalten +- Was nicht funktioniert, wird angepasst diff --git a/README.md b/README.md new file mode 100644 index 0000000..38b0d01 --- /dev/null +++ b/README.md @@ -0,0 +1,117 @@ +# Hermes Memory Next Level + +> Lösung für Context Rot und Agent Memory bei Hermes Agent. Von manuellem Key-Value zu strukturiertem, hierarchischem, automatischem Memory. + +## Problem + +Hermes verliert nach Context-Compression oder Session-Wechsel wichtigen Zustand: +- Tool-Konfigurationen werden zu "Docker wurde erwähnt" +- Projekt-Zustände zu "Wir haben an Auth gearbeitet" +- Präferenzen verschwinden komplett +- Nutzer muss dieselben Dinge immer wieder erklären + +## Vision + +Memory wird von **manuell** und **flach** zu **automatisch** und **strukturiert**: +- Auto-Extraktion aus jeder Session +- Typisierte Memory-Blöcke mit Entity-Linking +- Multi-Tier: Working → Short-Term → Long-Term +- Session-Start Injection: Relevanter Kontext wird automatisch geladen + +## Status + +| Phase | Status | Ziel | +|-------|--------|------| +| P0 Auto-Extraction | 🔄 In Planung | Cronjob extrahiert Fakten aus Sessions | +| P0 Structured Blocks | 🔄 In Planung | Erweitertes `memory` Tool mit Typen | +| P1 Entity-Linking | ⏳ Pending | Graph: Projekte, Dateien, Personen verknüpfen | +| P1 Temporal Memory | ⏳ Pending | "Was war der letzte Stand von X?" | +| P1 Multi-Tier | ⏳ Pending | SQLite + Vektor-Store | +| P2 Self-Management | ⏳ Pending | Agent speichert selbst | +| P2 Session Injection | ⏳ Pending | Automatisches Laden beim Start | + +## Architektur + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 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 │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 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" +``` + +## Projektstruktur + +``` +hermes-memory-next-level/ +├── AGENTS.md # Agent-Context (wer ist der Agent, was soll er wissen) +├── README.md # Diese Datei +├── .env.example # Umgebungsvariablen +├── docs/ +│ ├── research/ +│ │ └── agent-memory-solutions-2026.md +│ ├── architecture/ +│ │ └── memory-tiers.md +│ └── decisions/ +│ └── ADR-001-structured-memory-blocks.md +├── src/ +│ ├── extraction/ # Auto-Extraction aus Sessions +│ ├── storage/ # Memory-Tier-Implementierungen +│ ├── graph/ # Entity-Linking Graph +│ ├── injection/ # Session-Start Injection +│ └── api/ # REST API für Memory-Operationen +├── tests/ +│ ├── unit/ +│ └── integration/ +├── scripts/ +│ └── setup.sh # Setup-Script +└── docker-compose.yml # Für lokale Entwicklung (SQLite, Qdrant, etc.) +``` + +## Remote + +- **Gitea**: `ssh://git@gitea.insight-it.de:2222/b0rbor4d/Hermes-Memory-Next-Level.git` +- **SSH-Key**: `id_ed25519` (lokal vorhanden, muss in Gitea hinterlegt werden) + +## Mitwirkung + +ECC-Standards gelten. Siehe `AGENTS.md` und `CODING.md` (wenn vorhanden). + +--- + +*Projekt gestartet: Juni 2026* +*Ziel: Context Rot eliminieren, Hermes Memory auf Next-Level bringen* diff --git a/docs/architecture/memory-tiers.md b/docs/architecture/memory-tiers.md new file mode 100644 index 0000000..e69ec1e --- /dev/null +++ b/docs/architecture/memory-tiers.md @@ -0,0 +1,166 @@ +# Memory Tiers Architecture + +## Übersicht + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 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 │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Tier 1: Working Memory + +**Speicher**: LLM Prompt (nicht persistent) +**Zugriff**: Synchron, < 1ms +**Inhalt**: Aktuelle Nachrichten + relevante Kontext aus Tier 2/3 +**Größe**: 4K–128K Tokens (je nach Modell) +**Lifecycle**: Session-bound, flüchtig + +**Injection-Pattern**: +``` +System Prompt +├── Base Instructions +├── Injected Memories (relevante Blocks aus Tier 2/3) +├── Current Session Context +└── User Message +``` + +## Tier 2: Short-Term Memory + +**Speicher**: SQLite (`memory.db`) +**Zugriff**: Synchron, ~1-5ms +**Inhalt**: Letzte 5–10 Sessions, vollständige Nachrichten +**Größe**: ~10-50 MB +**Lifecycle**: 30 Tage, dann Archivierung oder Löschung + +**Schema**: +```sql +CREATE TABLE short_term_sessions ( + id TEXT PRIMARY KEY, + session_id TEXT NOT NULL, + timestamp DATETIME DEFAULT CURRENT_TIMESTAMP, + messages JSON NOT NULL, + summary TEXT, + extracted_blocks JSON +); + +CREATE INDEX idx_sessions_time ON short_term_sessions(timestamp); +CREATE INDEX idx_sessions_session ON short_term_sessions(session_id); +``` + +## Tier 3: Long-Term Memory + +**Speicher**: Qdrant (Vektor) + NetworkX (Graph) +**Zugriff**: Asynchron, ~10-50ms +**Inhalt**: Memory Blocks, Entities, Beziehungen +**Größe**: Unbegrenzt (skalierbar) +**Lifecycle**: Permanent + +**Vektor-Store (Qdrant)**: +```python +# Memory Blocks als Embeddings +{ + "id": "uuid", + "vector": [0.1, 0.2, ...], # 768-dim embedding + "payload": { + "type": "user_preference", + "category": "formatting", + "key": "table_style", + "value": "compact with │ separators", + "entities": ["Flo"], + "confidence": 0.95 + } +} +``` + +**Knowledge Graph (NetworkX)**: +```python +# Entities als Nodes, Beziehungen als Edges +G.add_node("Flo", type="user", properties={...}) +G.add_node("waldseilgarten-crm", type="project", properties={...}) +G.add_edge("Flo", "waldseilgarten-crm", relation="works_on") +``` + +## Tier 4: Archive + +**Speicher**: Dateisystem (komprimierte JSONL) +**Zugriff**: Asynchron, ~100ms-1s +**Inhalt**: Alle Sessions, alle Nachrichten +**Größe**: Unbegrenzt +**Lifecycle**: Permanent, komprimiert + +**Format**: +```jsonl +{"session_id": "...", "date": "2026-06-03", "messages": [...], "compressed": true} +``` + +## Zugriffsmuster + +``` +User fragt: "Was war der letzte Stand vom Waldseilgarten-Projekt?" + +1. Tier 1 (Working): Prüfe aktuellen Kontext + → Nicht vorhanden (neue Session) + +2. Tier 2 (Short-Term): Suche in letzten 5 Sessions + → Session vom 3.6.2026 gefunden, aber nur Summary + +3. Tier 3 (Long-Term): Vektor-Suche + Graph-Traversal + → Memory Block: "Projekt-State: waldseilgarten-crm" + → Graph: Flo → works_on → waldseilgarten-crm + → Related: docker-compose.yml, NestJS, React + +4. Tier 4 (Archive): Vollständige Session laden + → Nur bei Bedarf, wenn Details fehlen + +5. Injection: Relevante Blocks in Working Memory laden + → System Prompt wird angereichert +``` + +## Migration + +``` +Phase 1: Tier 2 (SQLite) — Sofort + → Short-Term Memory für letzte Sessions + +Phase 2: Tier 3 (Vektor + Graph) — 1-2 Monate + → Memory Blocks aus bestehenden `memory` Einträgen + → Auto-Extraction startet + +Phase 3: Tier 1 (Injection) — 2-3 Monate + → Session-Start automatisch mit relevanten Memories + +Phase 4: Tier 4 (Archive) — 3-6 Monate + → Vollständige Historie, komprimiert +``` + +## Technologie-Stack + +| Tier | Technologie | Begründung | +|------|-------------|------------| +| Tier 1 | LLM Prompt | Nativ, kein Overhead | +| Tier 2 | SQLite | Einfach, schnell, kein extra Service | +| Tier 3 | Qdrant + NetworkX | Open Source, lokal hostbar, Python-native | +| Tier 4 | JSONL + gzip | Einfach, komprimierbar, durchsuchbar | + +## Datum + +2026-06-03 diff --git a/docs/decisions/ADR-001-structured-memory-blocks.md b/docs/decisions/ADR-001-structured-memory-blocks.md new file mode 100644 index 0000000..0aaa7fe --- /dev/null +++ b/docs/decisions/ADR-001-structured-memory-blocks.md @@ -0,0 +1,74 @@ +# ADR-001: Structured Memory Blocks + +## Status + +Accepted + +## Kontext + +Hermes Memory ist aktuell flaches Key-Value. Der Nutzer speichert manuell: +``` +memory: "User prefers tables with │ separators" +``` + +Das Problem: +- Keine Typisierung (ist das eine Präferenz, ein Fakt, ein Projekt-State?) +- Keine Verknüpfung (welches Projekt? welche Person?) +- Keine Temporalität (wann gespeichert? wann zuletzt genutzt?) +- Keine Confidence (wie sicher ist die Extraktion?) +- Keine automatische Extraktion (Nutzer muss manuell speichern) + +## Entscheidung + +Wir führen **Structured Memory Blocks** ein: + +```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" +``` + +## Konsequenzen + +### Positiv +- Typisierung ermöglicht gezieltes Retrieval ("gib mir alle Präferenzen des Users") +- Entity-Linking ermöglicht Kontext-Navigation ("was wissen wir über Projekt X?") +- Temporalität ermöglicht "letzter Stand"-Abfragen +- Confidence ermöglicht Filterung nach Qualität +- Auto-Extraction kann strukturiert speichern + +### Negativ +- Komplexer als Key-Value +- Migration bestehender Memories nötig +- Mehr Speicherplatz pro Memory + +## Alternative + +Key-Value beibehalten + Tags hinzufügen: +``` +memory: "User prefers tables with │ separators" +tags: ["user_preference", "formatting", "Flo"] +``` + +Abgelehnt: Tags sind nicht strukturiert genug für Entity-Linking und Temporalität. + +## Implementierung + +1. SQLite-Schema für Memory Blocks +2. Migration bestehender `memory` Einträge +3. Erweitertes `memory` Tool in Hermes +4. Auto-Extraction produziert Blocks statt Strings + +## Datum + +2026-06-03 diff --git a/docs/research/agent-memory-solutions-2026.md b/docs/research/agent-memory-solutions-2026.md new file mode 100644 index 0000000..da01595 --- /dev/null +++ b/docs/research/agent-memory-solutions-2026.md @@ -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*