# Portabilitaet: UNIVERSAL
# Zuletzt validiert: 2026-02-15 (Claude)
# Naechste Pruefung: 2026-08-15
# Quellen: [BACH ARCHITECTURE.md], [Agentic Workflow Research], [Memory Systems in AI]

SPEICHER-ARCHITEKTUR IN BACH
=============================

Stand: 2026-02-15

WAS IST SPEICHER-ARCHITEKTUR?
-----------------------------
Die Speicher-Architektur in BACH ist ein System von vielen verschiedenen Speicherschichten,
das es Agenten ermöglicht, Kontext zu bewahren, von Fehlern zu lernen und sich selbst zu
verbessern, ohne dabei ihre Statelessness zu verlieren.

Im Gegensatz zu traditionellen Systemen mit einem Single-Memory-Model nutzt BACH eine
differenzierte Speicherstrategie mit mehreren Zwecken und Lebensdauern.

KERNKONZEPT: MULTI-LAYER MEMORY
--------------------------------
BACH organisiert Speicher in diese Schichten (von kurzfristig zu langfristig):

1. **CONVERSATION MEMORY** (aktueller Dialog)
   - Speichert: Die letzten N Meldungen im Chat
   - Lebensdauer: 1 Session (bis Browser-Reload oder Timeout)
   - Zugriff: Automatisch in Prompts
   - Beispiel: "Der Nutzer sagte zuvor ..."

2. **SESSION MEMORY** (aktuelle Arbeitssitzung)
   - Speichert: Variablen, Status, Zwischenergebnisse
   - Lebensdauer: Eine Arbeitssitzung (z.B. ein Projekt-Bearbeitungstag)
   - Zugriff: Explizit über Agenten-Memory API
   - Beispiel: "Merke: Der Nutzer arbeitet an Projekt X"
   - Format: JSON in `data/sessions/{session_id}.json`

3. **FACTS MEMORY** (strukturierte Erkenntnisse)
   - Speichert: Wichtige Fakten über den Nutzer/System
   - Lebensdauer: Langfristig (bis manuell überschrieben)
   - Zugriff: Semantische Suche via Datenbank
   - Beispiel: "User hat ADHS, bevorzugt Checklisten"
   - Format: bach.db `facts` Tabelle mit Embedding-Index
   - Eigenschaften: Strukturiert, durchsuchbar, versionierbar

4. **LESSONS MEMORY** (gelernte Patterns & Fehler)
   - Speichert: Was der Agent gelernt hat (Best Practices, häufige Fehler)
   - Lebensdauer: Sehr langfristig (persistent, aber überschreibbar)
   - Zugriff: Automatisch bei ähnlichen Tasks laden
   - Beispiel: "Wenn Benutzer Datei X bearbeitet, nutze immer Tool Y"
   - Format: bach.db `lessons` Tabelle mit Kontext-Tags
   - Eigenschaften: Implizit abrufbar, automatisch anwendbar

5. **CONTEXT WINDOW** (aktueller KI-Kontext)
   - Speichert: Alle Informationen die zur aktuellen Verarbeitung nötig sind
   - Lebensdauer: Ein KI-API-Call (Z.B. eine Claude-API-Request)
   - Zugriff: Automatisch als System Prompt
   - Beispiel: Relevante Facts + relevante Lessons + aktuelle Conversation
   - Größe: Begrenzt durch Token-Limit (z.B. Claude 200K)
   - Optimierung: Adaptive Context-Selection (nur die nötigsten Infos laden)

UNTERSCHIED ZU EINFACHER MEMORY
--------------------------------
Einfaches System:
  Agent hat 1 Memory (Alles in einer großen Datenbank)
  → Waechst unbegrenzt
  → Suche wird langsam
  → LLM liest immer ALLES (Context-Bloat)
  
BACH Multi-Layer:
  Agent nutzt 5 Speichertypen mit unterschiedlichen Zwecken
  → Conversation bleibt klein (nur aktueller Chat)
  → Facts sind strukturiert und durchsuchbar
  → Lessons werden intelligent geladen (nur relevante)
  → Context wird optimiert (adaptive Selection)
  → Performance bleibt konstant, auch bei Jahr-langer Nutzung

PRACTICAL EXAMPLE: FEHLERBEHANDLUNG
------------------------------------
Szenario: Agent versucht, Datei X zu bearbeiten und schlägt fehl.

1. **CONVERSATION**: "Error: Permission denied"
   → Agent sieht den Fehler in der Conversation

2. **SESSION**: Agent speichert: "Versuch 3: Datei X gescheitert"
   → Begrenzt Retry-Versuche (nicht unendlich fehlen)

3. **LESSONS**: Agent speichert: "Datei X braucht sudoedit"
   → Nächstes Mal: "Mit sudoedit versuchen"

4. **FACTS**: Optional speichern: "User hat nur sudo-Zugriff auf bestimmte Dateien"
   → Agenten nutzen das für zukünftige Planungen

5. **CONTEXT**: Beim nächsten Versuch wird das Lesson automatisch geladen
   → "Ah, ich sollte sudoedit nutzen basierend auf vorherigen Erfahrung"

SPEICHER-LIFECYCLE
------------------
Wie lange lebt Speicher in BACH?

  CONVERSATION   ════════════════════════     1 Session (z.B. 4 Stunden)
  SESSION        ════════════════════════════ 1 Tag / Projekt
  FACTS          ════════════════════════════════════════ 1 Jahr+ (persistent)
  LESSONS        ════════════════════════════════════════ 1 Jahr+ (persistent)
  CONTEXT WINDOW ══════════════════             1 API Call (Sekunden)

TECHNISCHE IMPLEMENTIERUNG
--------------------------
Memory wird auf mehreren Ebenen implementiert:

- **Datenbank**: bach.db speichert Facts, Lessons, Sesssion-Metadaten
- **Dateisystem**: data/sessions/*.json für Session-State
- **LLM Context**: Relevante Infos werden in System Prompt eingefügt
- **Vector-DB**: Embedding-Index für semantische Suche (Facts/Lessons)
- **APIs**: bach_api.py stellt Memory-Funktionen bereit

SELBSTHEILUNGS-INTEGRATION
--------------------------
Die Speicher-Architektur ist eng mit BACH's Self-Healing verbunden:

- **Konsistenz-Checks**: Prüft ob Facts <-> Lessons konsistent sind
- **Garbage Collection**: Löscht abgelaufene Sessions, verifiziert DB-Integrität
- **Learning Cycles**: Extrahiert neue Lessons aus Session-Logs
- **Corruption Repair**: Wenn eine Speicherschicht beschädigt ist, kann der 
                        Agent auf andere Schichten ausweichen

BEST PRACTICES
--------------
Für Agenten und Skills:

1. **Nicht alles speichern**
   - Nur wichtige Facts speichern
   - Nicht: "Nutzer hat heute eine Datei bearbeitet"
   - Sondern: "Nutzer mag Markdown-Format"

2. **Sessions cleanup**
   - Sessions sollten manuell gelöscht werden wenn abgeschlossen
   - Verhindert Datenbloat

3. **Lessons sind teuer**
   - Lessons brauchen Embedding und Verifizierung
   - Nur speichern wenn wirklich wichtig
   - Beispiel: "Fehler bei Datei-Format X" vs "Nutzer brauchte 3 Versuche"

4. **Context-Aware sein**
   - Lessons sollten Tagged sein (z.B. "datei-handling", "error-recovery")
   - Agenten können gezielt Lessons mit bestimmten Tags laden

5. **Sicherheit beachten**
   - Facts sollten sensible Daten NICHT speichern
   - Nutze stattdessen PRIVAT/ Ordner oder verstoepple Daten
   - Siehe: wiki/anonymisierung_sicherheit.txt

ERWEITERUNGEN & FORSCHUNG
--------------------------
Mögliche zukünftige Verbesserungen:

- **Hierarchische Lessons**: Lessons mit Abhängigkeiten (A braucht B)
- **Probabilistic Memory**: Lessons mit Confidence-Scores
- **Collaborative Learning**: Lessons zwischen mehreren Agenten teilen
- **Temporal Memory**: Facts mit Gültigkeitsdatum (z.B. "Version XYZ alt seit 2025-12-01")
- **Cross-Session Synthesis**: Erkenne Patterns über mehrere Sessions

VERWANDTE KONZEPTE
------------------
  Agentic Workflows      Wie Agenten mit Memory arbeiten
  Self-Healing           Wie Memory konsistent bleibt
  ReAct Pattern          Observe-Think-Act Loop (nutzt Memory)
  Embedding-Search       Wie Lessons semantisch gefunden werden
  Context Window         Wie Memory in LLM-Context passt
  Vector Databases       Backend für Facts/Lessons-Suche

SIEHE AUCH
----------
  wiki/agentic_workflows.txt         Wie Agenten Memory nutzen
  wiki/selbstheilung.txt             Self-Healing & Memory-Konsistenz
  wiki/was_ist_bach.txt              Überblick über BACH
  data/bach.db                       Die Speicherdatenbank
  ARCHITECTURE.md                    Technische Details
