Files

T

Florian Hartmann 33fb180855 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

5.7 KiB

Raw Blame History

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:

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):

# 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):

# 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:

{"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

5.7 KiB Raw Blame History Unescape Escape