brain-v42

Dauerhaftes Gedächtnis für Coding-Agenten, über MCP bereitgestellt.

brain-v42 gibt Claude Code, Codex und jedem anderen MCP-Client ein dauerhaftes zweites Gehirn: Entscheidungen, Erkenntnisse, Code-Snippets, Runbooks, ADRs, Tickets und Projekt-Roadmaps – gespeichert in PostgreSQL, abgerufen per Volltext- + semantischer Suche mit Re-Ranking und jede Nacht durch eine Agent-Pipeline konsolidiert.

• Typisiertes Wissen, kein Notizdump — eine Entscheidung erfasst ihr WARUM und Alternativen; ein Snippet erfasst seine Absicht; ein Runbook erfasst ausführbare Schritte. Jeder Typ hat seinen eigenen Lebenszyklus (Supersession-Ketten, ADR-Akzeptanz, Lernvalidierung).

• Expliziter Session-Lebenszyklus — der Benutzer kontrolliert jede Session-Grenze. Sessions erfassen die Artefakte, die sie produziert haben, und das Schließen ist fail-closed: Eine Session endet mit entweder erfasstem Wissen oder einem expliziten Grund „nichts zu erfassen“, niemals mit Schweigen.

• Suche mit Ranking — pgvector-semantische Suche + PostgreSQL FTS, fusioniert und neu gerankt durch einen Cross-Encoder.

• Nächtliche Konsolidierung („dream“) — eine Agent-Pipeline bereinigt verwaiste Links, führt Duplikate zusammen, synthetisiert Erkenntnisse und schlägt Hochstufungen vor, hinter Phasen- Killswitches, die alle geschlossen ausgeliefert werden.

• Multi-Projekt — projektbezogener Fokus mit Compare-and-Swap-Revisionen, Roadmaps, projektübergreifenden Tickets.

Architektur

Claude Code / Codex (MCP client)
       │ HTTP loopback :8765/mcp (production) · stdio (dev/fallback)
  brain-v42 (FastMCP)
       ├── SQLAlchemy async ─▶ PostgreSQL 16 + pgvector   (source of truth)
       ├── HTTP ─────────────▶ embedding endpoint :8003   (optional, pluggable)
       ├── HTTP ─────────────▶ :8003/rerank               (optional reranker)
       └── bolt ─────────────▶ Neo4j 5 Community          (relationship index, optional)

MCP-Transport: Produktion = HTTP-Loopback http://127.0.0.1:8765/mcp; Konfigurationsstandard und Dev/Fallback = stdio.

PostgreSQL ist die einzige Quelle der Wahrheit. Neo4j ist eine wegwerfbare Projektion, die von einer relationalen Ledger/Outbox gespeist wird — sie kann jederzeit aus PostgreSQL neu aufgebaut werden, nie umgekehrt. Der kanonische Pfad ist seit dem 22. Juli 2026 in Produktion aktiv; Design und Nachweise befinden sich in docs/ARCHITECTURE.md und dem Graph-Ledger-Runbook.

Embeddings sind optional und austauschbar. Der Server selbst ist modellagnostisch: Er spricht nur einen Drei-Routen-HTTP-Vertrag (POST /embed, POST /embed/query, POST /rerank) und degradiert elegant, wenn der Endpoint nicht erreichbar ist — brain_search fällt auf Volltextsuche zurück, Schreibvorgänge werden mit einem NULL-Embedding persistiert und später nachgefüllt. Jeder Server, der diesen Vertrag implementiert, funktioniert. Der mitgelieferte Referenz- Stack (services/) bedient Qodo-Embed-1-1.5B als GGUF über llama.cpp auf einer lokalen GPU. EMBEDDING_DIMENSION wird bei der Installation gewählt; ein späterer Modellwechsel bedeutet Neu-Einbettung des Korpus (scripts/regen_embeddings.py).

Schnellstart

git clone https://github.com/hawkixs/brain-v42 && cd brain-v42
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 1. Local Neo4j secret (skip if you run without the graph)
install -d -m 0700 .secrets
read -rsp "Neo4j password (same value as NEO4J_PASSWORD in .env): " PW
(umask 0022; printf 'neo4j/%s\n' "$PW" > .secrets/neo4j-auth); unset PW

# 2. Databases (PostgreSQL 16 + pgvector, Neo4j)
docker compose up -d

# 3. Migrations
export POSTGRES_URL="postgresql+asyncpg://brain:REPLACE_WITH_PASSWORD@localhost:5433/brain"
BRAIN_ALEMBIC_ALLOW_PROD=1 alembic upgrade head

# 4. Run the MCP server (stdio)
python -m brain_v42.mcp.server

Binde es in Claude Code ein — .mcp.json im Repository-Root zielt bereits auf den Produktions- HTTP-Loopback-Endpoint; für ein einfaches Stdio-Dev-Setup:

claude mcp add brain-v42 -- python -m brain_v42.mcp.server

BRAIN_ALEMBIC_ALLOW_PROD wird nur benötigt, wenn der Datenbankname exakt brain lautet; behalte es als Ein-Befehl-Opt-in bei und exportiere es niemals dauerhaft. Alembic lehnt DSN-Abfrageparameter ab; verwende die obige einfache Form mit Host, Port, Benutzername und Passwort.

MCP-Tools

Vollständiger Katalog mit Signaturen: docs/MCP_TOOLS.md.

Das Standard-Katalogprofil ist compact: Die sieben Session-Lebenszyklus-Tools bleiben sichtbar, und jedes andere Tool wird über zwei Gateways erreicht — brain_find_tool zum Entdecken, brain_call_tool zum Aufrufen. Setze BRAIN_MCP_PROFILE=native, um jedes Tool direkt verfügbar zu machen.

Sitzungen

Der Benutzer kontrolliert jede Session-Grenze: start, resume, end und abandon sind explizite Befehle, die nie von einem Hook, einem Agenten oder einem Client abgeleitet werden. Sessions erfassen die dauerhaften Artefakte, die sie produziert haben, in einem exklusiven Ledger, und das Schließen ist fail-closed: erfasstes Wissen oder ein expliziter Grund „nichts zu erfassen“, niemals Stille.

Nach 24 Stunden ohne Heartbeat zeigt eine offene Session is_stale=true an; der Marker wird abgeleitet, der persistente Status bleibt open, und nur der serverseitige Sieben-Tage-Sweep bricht eine Session ohne expliziten Benutzerbefehl ab.

Der vollständige Lebenszyklus-Vertrag (Erfassungsregeln, Fokus-Semantik, Briefing) befindet sich in docs/MCP_TOOLS.md; der Vertrag ist v4 und befindet sich noch in der Entwicklung.

Konfiguration (.env)

# Required
POSTGRES_URL=postgresql+asyncpg://brain:REPLACE_WITH_PASSWORD@localhost:5433/brain

# Optional — semantic search and reranking
EMBEDDING_SERVICE_URL=http://localhost:8003
EMBEDDING_DIMENSION=1536
RERANKER_URL=http://localhost:8003

# Optional — relationship graph (safe defaults for a fresh environment)
GRAPH_ENABLED=false
GRAPH_LEDGER_WRITE_ENABLED=false

# Tool catalog profile
BRAIN_MCP_PROFILE=compact   # compact (default) or native

LOG_LEVEL=INFO

Platziere MCP_HTTP_TOKEN oder MCP_HTTP_DREAM_TOKENS niemals in der gemeinsamen .env: Bearer- Tokens leben in einer privaten 0600-Datei (~/.config/brain-v42/mcp-token.env), und die Graph-Projector-Anmeldedaten in einer eigenen (~/.config/brain-v42/graph-projector.env). Vollständige Referenz — jede Variable, die privaten Secret-Dateien, Preflights und Rollout- Gates: docs/OPERATIONS.md.

Netzwerk-Vertrauensmodell

Das Deployment zielt auf persönliche Agenten in einem vertrauenswürdigen LAN. MCP, PostgreSQL und Neo4j binden an Loopback; Metriken und Automatisierung verwenden standardmäßig Loopback.

Embedding-Topologie: Produktion/Standard = lokaler einheitlicher Endpoint http://localhost:8003; deploy/dev-pc ist ein überholter Rollback-/Referenzpfad.

Der Reranker teilt sich den einheitlichen Embedding-Endpoint :8003/rerank. Behandle :8003 als LAN-exponiert, bis du selbst das Live-Bind nachgewiesen hast, und setze es – oder den MCP-Port – niemals dem Internet aus. Der Repository-Code allein beweist keinen Live-Firewall-Zustand.

Dream-Modus

Nächtliche Agent-Pipeline (scripts/dream.sh: scan → clean → connect → synth → promote → reorg) plus serverseitige Ticket-Extraktions-, Roadmap-Kurations- und Session-Sweep-Jobs. Jede mutierende Phase sitzt hinter einem Killswitch, und jeder Killswitch wird geschlossen ausgeliefert; Dry-run ist die ausgelieferte Standardeinstellung. Jede Phase läuft unter einer exakten MCP-Tool-Allowlist. Details: docs/ARCHITECTURE.md und docs/OPERATIONS.md.

Produktionsstand

Das Migrationsziel des Repositories ist Migration 045. Keine Seite in diesem Repository beweist einen Live-Schema-Head — miss es, lies es hier nicht ab:

docker exec brain_v42_postgres psql -U brain -d brain -Atc "select version_num from alembic_version;"

Der laufende Build nennt sich selbst: GET /health liefert version (die installierte Distribution) und alembic_head (die damit ausgelieferte Revision), beide gemessen, niemals von Hand geschrieben.

Entwicklung

pytest tests/unit -v                          # no PostgreSQL required
pytest --cov=brain_v42 --cov-report=term-missing
ruff check src/ tests/ && ruff format --check src/ tests/
mypy src/

• Stack: Python 3.12+, FastMCP 3.x, SQLAlchemy 2.0 async + asyncpg, Alembic, Pydantic 2, structlog.

• TDD ist Pflicht — Rot, Grün, Refactoring; Tests werden niemals geändert, um Code bestehen zu lassen.

• Coverage-Untergrenze: 60 % (CI blockiert darunter).

• Die Dev-Toolchain ist exakt gepinnt (pip install -e ".[dev]"), sodass lokal immer mit CI übereinstimmt.

Projektstruktur

brain-v42/
├── src/brain_v42/
│   ├── config.py              # pydantic-settings — single config surface
│   ├── db/                    # SQLAlchemy engine + tables
│   ├── models/                # Pydantic models
│   ├── repositories/          # CRUD + FTS + pgvector + graph adapters
│   ├── services/              # business logic, embedding, reranker, dream, dedup
│   ├── metrics/               # sidecar + collector + cockpit endpoint
│   ├── automation/            # independent webhook/dedup runtime (:9201)
│   └── mcp/                   # FastMCP server + brain_*/dream_* tool handlers
├── tests/{unit,integration}
├── alembic/versions/          # migrations (shipped inside the wheel)
├── scripts/                   # operational CLIs (dream.sh, canaries, repair)
├── services/                  # GPU embedding service + shim + supervisor
├── deploy/                    # systemd units, per-host compose, install.sh
└── docs/                      # ARCHITECTURE, SCHEMA, MCP_TOOLS, OPERATIONS, runbooks

Der Top-Level-Modulgraph wird in CI azyklisch erzwungen (scripts/check_module_layering.py): Jedes Modul kann weiterhin in einen eigenständigen Dienst extrahiert werden, ohne einen Zyklus mitzuziehen.

CI/CD

Stufen: lint → test → security → build. Security-Gates: pip-audit, bandit, gitleaks, Container-Image-Pin-Checks. Docker-Images werden auf main gebaut und gepusht; es gibt keine Deploy-Stufe — das Ausrollen auf einen Host ist immer ein manueller, Out-of-Band-Schritt. Releases sind Tag-getrieben: Die Release-Rail baut das Wheel + sdist, weist nach, dass das Wheel seine Migrationen mitliefert, und hängt beides an das GitHub-Release.

Versionierung

• Die ausgelieferte Version ist 0.2.0, und sie bleibt bewusst 0.x: Ein 1.0.0 würde eine stabile Schnittstelle und einen Rückweg versprechen, und dieses Projekt hat beides noch nicht.

• Es wird kein verlustfreies Downgrade versprochen, bei keiner Version. Zwei Migrationen verweigern ihr eigenes downgrade: 037 wirft eine SQL-EXCEPTION, sobald eine Session-Erfassung verloren ginge, und 039 wirft, sofern der Operator kein explizites -x-Opt-in angibt.

• Ein Schema-Rollback ist daher ein Operator-Verfahren mit einem Runbook, niemals eine Versions- garantie — stattdessen aus einem Snapshot wiederherstellen.

Lizenz

Quellcode: Apache-2.0.

Die Modellgewichte sind nicht von dieser Lizenz abgedeckt, und das ist keine Formalität. Das Produktions-Embedding-Modell Qodo/Qodo-Embed-1-1.5B wird unter QodoAI-Open-RAIL-M veröffentlicht – einer Lizenz mit nutzungsbasierten Einschränkungen, nicht einer permissiven. In diesem Repository werden keine Gewichte gespeichert oder verteilt: Jedes Modell wird zur Build-Zeit von seinem Upstream-Host vom Betreiber heruntergeladen, der die Bedingungen jedes Modells direkt von dessen Herausgeber akzeptiert. Siehe NOTICE, bevor Sie etwas weiterverteilen.