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,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