# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-02-28
# Nächste Prüfung: 2026-08-28
# Ressourcen: [hub/shared_memory.py, shared_memory_*, shared_context_triggers]

SHARED MEMORY - Multi-Agent Memory-Verwaltung
===============================================

STAND: 2026-02-28

Das Shared Memory System ermöglicht den gemeinsamen Speicherzugriff
mehrerer Agenten (Claude, Gemini, etc.). Im Gegensatz zum normalen
Memory-System können hier mehrere Partner gleichzeitig lesen und
schreiben.

Ref: SQ043 Stufe A-2

ARCHITEKTUR
-----------

  Agent A ─┐
  Agent B ─┤─> shared_memory_* (bach.db) <─┬─> Kontext-Block
  Agent C ─┘                                └─> Changes-Feed

Eigenschaften:
  - Multi-Agent-fähig (agent_id, namespace)
  - Visibility-Levels (private, team, global)
  - Decay-Tracking für automatisches Cleanup
  - Conflict Resolution via Konfidenz-Werte
  - dist_type für Distribution-System

CLI-BEFEHLE (bach shared-mem)
------------------------------

FACTS (Geteilte Fakten):
  facts list                    Alle shared Facts anzeigen
  facts add <key> <value>       Neuen Fact hinzufügen
  facts get <id>                Bestimmten Fact anzeigen
  facts delete <id>             Fact löschen

LESSONS (Geteilte Lektionen):
  lessons list                  Alle shared Lessons anzeigen
  lessons add <titel>           Neue Lesson hinzufügen
  lessons activate <id>         Lesson aktivieren
  lessons deactivate <id>       Lesson deaktivieren

WORKING MEMORY (Kurzzeitgedaechtnis):
  working list                  Aktive Einträge anzeigen
  working add <inhalt>          Eintrag hinzufügen
  working cleanup               Abgelaufene Einträge löschen
  working current-task <text>   Aktuellen Task setzen (max. 1 pro Agent)

SESSIONS:
  sessions list [N]             Sessions anzeigen (Standard: 20)
  sessions current              Aktive Sessions anzeigen
  sessions archive <tage>       Alte Sessions archivieren

CONSOLIDATION (Speicher-Gewichtung):
  consolidation list            Consolidation-Einträge anzeigen
  consolidation stats           Statistiken anzeigen
  consolidation add <t> <id>    Eintrag manuell hinzufügen
  consolidation consolidate     Schwache Einträge konsolidieren
  consolidation run             Decay-Logik ausführen (B57)

KONTEXT & ÄNDERUNGEN:
  context                       Kontext-Block generieren (B55)
  changes <timestamp>           Änderungen seit Zeitstempel (B58)

BEISPIELE
---------

  # Fact hinzufügen
  bach shared-mem facts add "api.endpoint" "https://api.example.com"
  bach shared-mem facts add "server.ip" "192.168.1.1" --agent CLAUDE --confidence 0.9

  # Lesson teilen
  bach shared-mem lessons add "Windows: UTF-8 mit PYTHONIOENCODING setzen" --severity high

  # Aktuellen Task setzen (Session-Anker)
  bach shared-mem working current-task "Migration von PyMuPDF auf pypdf"
  bach shared-mem working current-task "BACH Release vorbereiten" --agent GEMINI

  # Kontext-Block generieren (für Agenten-Initialisierung)
  bach shared-mem context

  # Änderungen seit gestern abfragen
  bach shared-mem changes 2026-02-27T00:00:00

  # Decay-Logik ausführen (Speicher-Cleanup)
  bach shared-mem consolidation run
  bach shared-mem consolidation run --dry-run

CONFLICT RESOLUTION (B56)
--------------------------

Beim `facts add` mit bestehendem Key:
  - Neuer Confidence >= bestehender Confidence → Eintrag wird aktualisiert
  - Neuer Confidence < bestehender Confidence → Eintrag bleibt unverändert

  Beispiel:
    bach shared-mem facts add "version" "2.5" --confidence 0.9
    # Überschreibt bestehenden Eintrag wenn dessen Confidence < 0.9

DECAY-SYSTEM (B57)
------------------

`consolidation run` führt Decay-Logik durch:
  - Jeder Eintrag: weight *= decay_rate (Standard: 95% Erhalt)
  - Unterschreitet weight den threshold (Standard: 0.1) → Archivierung
  - Haeufig aufgerufene Einträge erhalten Boost und werden seltener archiviert

CONTEXT-BLOCK (B55)
--------------------

`bach shared-mem context` generiert einen Markdown-Block:

  ## Shared Memory Context

  ### Current Tasks
  - **CLAUDE**: Migration läuft (seit ...)

  ### Top Facts
  - **api.endpoint** [0.9]: https://api.example.com

  ### Aktive Lessons
  - [high] Windows: UTF-8 mit PYTHONIOENCODING setzen

Wird für Agenten-Initialisierung genutzt.

CHANGES-FEED (B58)
-------------------

`bach shared-mem changes <timestamp>` liefert alle Änderungen
seit dem angegebenen ISO-Zeitstempel:

  bach shared-mem changes 2026-02-28T10:00:00

Nützlich für Agenten-Synchronisation: Ein Agent prüft regelmäßig
ob andere Agenten Fakten oder Lektionen hinzugefügt haben.

OPTIONEN FÜR FACTS ADD
-----------------------

  --agent <id>              Agent-ID (Standard: GLOBAL)
  --namespace <ns>          Namespace (Standard: default)
  --visibility <level>      private|team|global (Standard: global)
  --confidence <0.0-1.0>    Konfidenz-Wert (Standard: 0.5)

OPTIONEN FÜR LESSONS ADD
--------------------------

  --severity info|warn|high|critical   Schwere (Standard: info)
  --agent <id>                          Agent-ID (Standard: GLOBAL)
  --namespace <ns>                      Namespace (Standard: default)

DATENBANK-TABELLEN
------------------

  shared_memory_facts         Geteilte Fakten (key-value)
  shared_memory_lessons       Geteilte Lektionen
  shared_memory_sessions      Geteilte Session-Historie
  shared_memory_working       Kurzzeitgedaechtnis (is_active, expires_at)
  shared_memory_consolidation Decay-Tracking (weight, decay_rate, threshold)
  shared_context_triggers     Geteilte Context-Trigger

UNTERSCHIED ZUM NORMALEN MEMORY
---------------------------------

  Normales Memory (bach mem, bach --memory):
    - Für EINEN Agenten/Partner
    - memory_working, memory_facts, memory_lessons

  Shared Memory (bach shared-mem):
    - Für MEHRERE Agenten gleichzeitig
    - Visibility-Control (private/team/global)
    - Conflict Resolution via Konfidenz
    - Decay-System für Cleanup

DATEIEN
-------
  hub/shared_memory.py     Handler-Implementation

SIEHE AUCH
----------
  bach --help memory        Normales Memory-System (einzelner Agent)
  bach --help consolidation Konsolidierungs-Engine
  bach --help connector     Connector-System (Multi-Partner)
