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