Florian Hartmann
830a804eb3
- 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
393 lines
18 KiB
Markdown
393 lines
18 KiB
Markdown
# 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*
|