Second Brain — Knowledge Brain Plugin

Karpathy-Pattern Wiki mit automatischer Erfassung und LLM-Compile. Ersetzt manuelles Wissensmanagement durch Hooks + Compile-Schritt.

Was es tut

1. Automatisch: Hooks erfassen Tool-Aktivitaet waehrend jeder Session
2. Bei Session-Ende (Stop): Buffer wird still nach raw/<projekt>/ verschoben — blockt nie
3. Bei Session-Ende (SessionEnd): ab 5 gepufferten Zeilen haengt ein detachter Headless-Agent (claude -p --resume <session-id>) eine kurze Zusammenfassung an die raw-Datei an
4. Bei Session-Start: stiller Catch-Up + Aufraeumen; ein detachter, flock-gesicherter Headless-Agent kompiliert unkompilierte raw/-Dateien ins Wiki — nichts davon wird in die laufende Session injiziert. Der Headless-Compiler committet nur lokal im Vault, gepusht wird weiterhin manuell (z. B. via /brain:compile bzw. git push)

Commands

Command	Zweck
/brain:compile	Manueller Compile — alle raw/ aufs Mal
/brain:init	Vault-Setup auf neuem Rechner
/brain:hygiene	Strukturpruefung
/brain:status	Quick-Check: raw/, Compile, Hygiene

Hooks (automatisch)

Silent Hooks v3: kein Hook blockt und keiner injiziert Kontext in die laufende Session. Zusammenfassen und Kompilieren laufen als eigene, detachte Headless-Agenten (claude -p), abgeschottet ueber die Guard-Variable SB_AGENT=1 (siehe unten).

Hook	Zweck
PostToolUse	Tool-Metadaten in Buffer erfassen
Stop	Buffer still nach raw/ verschieben, zaehlt Zeilen pro Session fuer SessionEnd
SessionEnd	Ab 5 gepufferten Zeilen: detachter Summarizer-Agent haengt Zusammenfassung an die raw-Datei an
SessionStart	Stiller Catch-Up + Aufraeumen, spawnt bei unkompilierten raw/-Dateien einen detachten, flock-gesicherten Compiler-Agent

State, Logs, Env-Overrides

Session-Zaehler, Logs und der Compile-Lock liegen unter ~/.local/state/second-brain/:

Pfad	Inhalt
sessions/<session-id>	Zeilenzaehler + Zielpfad, von Stop geschrieben, von SessionEnd gelesen und geloescht
logs/summarize-YYYY-MM-DD.log	Log des Summarizer-Agenten
logs/compile-YYYY-MM-DD.log	Log des Compiler-Agenten
compile.lock	flock-Datei — verhindert parallele Compile-Laeufe
compile.last	Zeitstempel des letzten Compile-Starts, Basis fuer den Cooldown

Env-Overrides (v.a. fuer Tests):

Variable	Zweck
SB_STATE_DIR	State-Verzeichnis statt ~/.local/state/second-brain
SB_BUFFER	Buffer-Datei statt ~/.second-brain-buffer
SB_CLAUDE_CMD	claude-Binary/Wrapper fuer die Headless-Agenten
SB_SLEEP	Wartezeit vor dem Summarizer-Start (Sekunden)
SB_AGENT	Rekursionsschutz — 1 heisst „ich bin selbst ein Headless-Agent“, alle vier Hooks tun dann nichts
SB_COMPILE_COOLDOWN_MIN	Cooldown in Minuten nach einem Compile-Lauf, bevor ein neuer starten darf (Default 30, 0 deaktiviert) — Bremse gegen Runaway-Loops bei persistent scheiterndem Compile

Hinweis zu den Headless-Agenten: Beide laufen bewusst ohne --bare — auf OAuth-Hosts scheitert --bare am Auth-Check, bevor --resume greift. Der Rekursionsschutz kommt stattdessen ueber SB_AGENT=1, das jeder Hook via sb_guard_agent aus hooks/lib.sh prueft.

Setup

# 1. Vault clonen (falls noch nicht vorhanden)
git clone git@git.waldegg.li:yoshi/second-brain.git ~/Development/second-brain

# 2. Plugin ist ueber waldegg-marketplace installiert

Codex

Dieses Plugin funktioniert auch in Codex. Skills werden ueber Description gematcht (es gibt keine Slash-Commands wie in Claude). Tippe in Codex „kompiliere mein Brain“ / „pruef die Vault-Hygiene“ / „Vault initialisieren“, und der passende Skill greift. Die Hooks laufen wie in Claude still im Hintergrund (Silent Hooks v3) — es erscheint nichts automatisch im Kontext. Catch-Up und Compile laufen auch unter Codex still als detachte Headless-Agenten. Die SessionEnd-Zusammenfassung haengt dagegen an claude -p --resume <session-id> und ist bisher nur fuer Claude-Code-Sessions verifiziert — unter Codex schlaegt der Resume voraussichtlich fehl und landet nur im Summarizer-Log (gutartig, kein Blocker).

Installation siehe waldegg-marketplace/docs/install-codex.md.

Projekt-Konfiguration

Jedes Projekt braucht .second-brain/config.md:

---
vault: ~/Development/second-brain
remote: git@git.waldegg.li:yoshi/second-brain.git
---

Und .second-brain/ in .gitignore.

Architektur

Session → PostToolUse → Buffer → Stop → raw/<projekt>/
                                    ↓
                              SessionEnd → (>=5 Zeilen) → Summarizer-Agent (detacht)
                                                             ↓
                                                    raw/<projekt>/<datum>.md

Naechster SessionStart → Catch-Up + Aufraeumen → Compiler-Agent (detacht, flock) → Wiki

OpenCode

Der OpenCode-Adapter besteht aus einem TS-Plugin (.opencode-plugin/) und vier Slash-Commands (.opencode-commands/). Installation ueber Symlinks — Details in der Marketplace-Doku (docs/install-opencode.md im claude-marketplace-Repo).

Beim Sessionende flusht das Plugin den Buffer nach <vault>/raw/<projekt>/<datum>.md. Buffer-Pfad: ~/.second-brain-buffer-opencode (eigener Pfad, damit OpenCode/Claude/Codex sich nicht in die Quere kommen).