second-brain/docs/ARCHITECTURE.md

Second Brain - Architektur

Vision

Ein zweites Gehirn für OpenClaw das:

• Kurzzeitgedächtnis: Aktuelle Sessions, Kontext, unverarbeitete Informationen
• Langzeitgedächtnis: Gesammeltes Wissen, bewertet, verknüpft, priorisiert
• Bewertungssystem: Jedes Faktum hat einen Vertrauenswert (0-1), korrektierbar
• Proaktivität: Agent wacht auf, prüft, handelt ohne expliziten Befehl
• Selbstheilung: Erkennt eigene Fehler, korrigiert, lernt daraus

Module

1. Engram Store (Gedächtnis-Einheiten)

Jede Information wird als "Engramm" gespeichert:

{
  id: uuid
  content: string (Markdown)
  vector: [float...] (Embedding)
  metadata: {
    source: "user|agent|web|file"
    confidence: 0.0-1.0
    created: timestamp
    modified: timestamp
    access_count: int
    last_accessed: timestamp
    tags: [string...]
    session_id: string|null
    agent_id: string|null
  },
  correctness: {
    confirmed: bool
    confirmations: int
    rejections: int
    last_reviewed: timestamp
    review_history: [
      { by: "user|agent", action: "confirm|reject|modify", at: timestamp, note: string }
    ]
  },
  links: [uuid...] (verbundene Engramme)
  hierarchy: {
    parent: uuid|null
    children: [uuid...]
    depth: int
  }
}

2. Vector Store (ChromaDB)

• Lokale SQLite-basierte Vektor-Datenbank
• Kein externer Service nötig
• Embedding über sentence-transformers (all-MiniLM-L6-v2)
• ~22MB Modell, CPU-only, 384 Dimensionen

3. Neural Scorer

• Kleines Feed-Forward-Netz (PyTorch)
• Eingabe: Embedding + Metadaten (Alter, Zugriffshäufigkeit, Quelle)
• Ausgabe: Confidence-Score (0-1)
• Training: Reinforcement von User-Feedback (richtig/falsch)

4. Retrieval Engine

• Hybrid: Semantische Suche (Vektor) + Keyword (BM25-ähnlich)
• Reranking nach Confidence, Aktualität, Relevanz
• Contextual Compression: Nur relevante Teile zurückgeben

5. Proactivity Engine

• Cron-gesteuerte Hintergrundaufgaben
• Heartbeat-gesteuerte Prüfungen
• Trigger: Zeit, Events, Zustandsänderungen
• Entscheidet selbst: Was ist jetzt wichtig?

6. Error Correction

• Erkennt fehlgeschlagene Tool-Calls
• Speichert Fehler mit Kontext
• Analysiert Muster: "Immer wenn X, dann scheitert Y"
• Auto-Fix: Alternative Strategien, Fallbacks

7. Visualisierung

• Streamlit-Dashboard lokal
• Graph-Ansicht: Verknüpfte Engramme
• Timeline: Wann wurde was gelernt?
• Stats: Vertrauen, Korrektheit, Abdeckung

Tech Stack

Komponente	Technologie	Warum
Vektor-DB	ChromaDB (lokal)	Kein externer Service, SQLite-basiert
Embeddings	sentence-transformers	Klein, schnell, offline
Neural Scorer	PyTorch (custom)	Trainierbar, lokal, kein API-Key
Frontend	Streamlit	Schnell, Python-nativ, interaktiv
Daten-Layer	Python-Klassen + SQLite	Kontrollierbar, debuggbar
Prozesse	Cron (OpenClaw built-in) + Heartbeat	Kein externer Scheduler

Datenfluss

User Input / Event
        |
        v
[Parser] -> Engramm erstellen
        |
        v
[Embedding] -> Vektor generieren
        |
        v
[Vector Store] -> Speichern
        |
        v
[Neural Scorer] -> Initial-Confidence
        |
        v
[Link Engine] -> Mit bestehenden verknüpfen
        |
        v
[Retrieval] <- Anfrage
        |
        v
[Rerank] -> Beste Ergebnisse
        |
        v
[Response] -> An User / Agent
        |
        v
[Feedback Loop] <- Richtig/Falsch?
        |
        v
[Learn] -> Scorer trainieren, Confidence anpassen

Dateistruktur

second-brain/
├── src/
│   ├── __init__.py
│   ├── engram.py          # Engramm-Modell
│   ├── store.py           # ChromaDB-Wrapper
│   ├── embedder.py        # Embedding-Engine
│   ├── scorer.py          # Neural Confidence Scorer
│   ├── retriever.py       # Hybrid Retrieval
│   ├── linker.py          # Verknüpfungs-Engine
│   ├── proactivity.py     # Proaktivitäts-Manager
│   ├── error_handler.py   # Fehlererkennung & Korrektur
│   ├── trainer.py         # RL-Training
│   └── config.py          # Konfiguration
├── data/
│   ├── chromadb/          # Vector DB Files
│   ├── engrams.jsonl      # Backup aller Engramme
│   └── scorer_model.pt    # Trainiertes Scorer-Netz
├── docs/
│   ├── ARCHITECTURE.md
│   └── API.md
├── tests/
│   └── test_core.py
├── scripts/
│   └── init_db.py
└── app.py                 # Streamlit Dashboard

Nächste Schritte

1. Kern-Module implementieren (Store, Embedder, Engram)
2. Scorer mit Dummy-Daten trainieren
3. Retrieval-Engine mit Testdaten validieren
4. Dashboard bauen
5. Cron-Jobs für Proaktivität setup
6. Issue #1 & #2 adressieren (Looping verhindern)