# Neural Knowledge Brain Eigenständiger Go-Dienst für Agent, lokale Knowledgebase, GLPI-Knowledgebase und autonome AI-THINK-Anreicherung. Der Dienst hält einen vollständigen Wissensgraphen im Arbeitsspeicher und rendert eine hierarchisch verdichtete Fullscreen-Ansicht als lebende Hirnaktivität. ## Kernfunktionen - Fullscreen-Canvas mit 3D-Hirnform, semantischen Cortex-Regionen und hierarchischem Level-of-Detail. - Drei Visualisierungen: Neural-Brain, gleichmäßige 3D-Honeycomb-Wabe und semantische Constellation-Ansicht mit Themensternen. - Persistierbarer **ECO**-Modus für schwächere Systeme sowie weiche Node-, Edge- und Ansichtsübergänge ohne sichtbaren Komplett-Reload. - Laufzeitsteuerung für Learning und Thinking sowie getrennte Kategorie-Filter für Lernen, Anzeige und AI-THINK. - Echtzeitaktivierung über Server-Sent Events: Nodes glühen, aggregierte Edges leuchten und Partikel folgen tatsächlichen Wissenspfaden. - Ingest lokaler produktiver Knowledge-JSONs sowie separater AI-THINK-Staging-Dateien. - Optionaler read-only Ingest sichtbarer Beiträge aus der GLPI-Knowledgebase. - Read-only Tailing der Agent-`runs.jsonl` und optionale Suchtelemetrie aus Agent und KB. - Ollama-Pool mit mehreren unabhängigen Instanzen, Routing, Healthchecks, Cooldown und Failover. - Embeddings über `embeddinggemma`, Beziehungsanalyse über `qwen3:8b`. - Mehrstufiger autonomer Worker: Relation Thinking, quellengebundene Wissenskonsolidierung, Recherche offener Punkte und reine Knowledge-Synthesis für vollständige KB-Artikel. - Inkrementelle SQLite/WAL-Persistenz über `modernc.org/sqlite`: binäre Float32-Embeddings und standardmäßig alle fünf Minuten gebündelte Row-Updates. ## Vertrauens- und Schreibgrenzen Das Brain liest produktive Quellen und GLPI-KB ausschließlich. Es schreibt niemals in produktive Knowledge-Dateien oder nach GLPI zurück. Schreibbar sind nur: - das eigene `BRAIN_DATA_DIR` für Graphzustand und GLPI-KB-Cache; - der erste Pfad aus `BRAIN_STAGING_DIRS` für AI-THINK-Entwürfe. AI-THINK bleibt `auto_reply: false`, trägt die Kategorien `AI-THINK` und `AI-Staging` und wird erst nach einer expliziten Freigabe im bestehenden Editor produktiv. Artikelentwürfe erhalten zusätzlich `AI-Synthesis`; `text` und `answer` enthalten ausschließlich den fachlichen Artikel. Planung, Bewertung, Confidence, Quellen-IDs und Rechercheprotokolle werden separat unter `BRAIN_DATA_DIR/article-metadata/` gespeichert. ## Grounded Knowledge Synthesis Verwandtes Wissen wird nicht direkt als Bewertungsbericht gespeichert. Das Brain konsolidiert zunächst belegte Fakten, Lösungsschritte, Widersprüche sowie kritische und optionale Wissenslücken. Kritische Unklarheiten werden iterativ über präzise deutsche und englische SearXNG-Queries recherchiert. Die besten Treffer durchlaufen ein Relevanz- und Quellenqualitäts-Gate, werden als vollständige Webseite geladen und nach einer zweiten Volltextprüfung erneut konsolidiert. Nur akzeptierte Volltextbelege werden sofort eingebettet, mit den Fachkategorien ihrer internen Quellen eingeordnet, unter `BRAIN_DATA_DIR/research-evidence/` für spätere Zyklen aufbewahrt und über `grounded_by` mit dem erzeugten Artikel verbunden. Bereits gelernte Belege werden bei verbundenen Themen erneut konsolidiert, ohne die Webseite unnötig noch einmal abzurufen. Optionale Vertiefungen blockieren keinen ansonsten belastbaren Artikel. Interne Aussagen ohne reale Referenz auf eine tatsächlich vorhandene Quelle werden verworfen. Konzept-, Referenz- und Entscheidungsartikel erhalten eine passende fachliche Struktur statt künstlich erzeugter Schrittfolgen. Details: [`KNOWLEDGE-SYNTHESIS.md`](KNOWLEDGE-SYNTHESIS.md) und [`ITERATIVE-GROUNDED-RESEARCH.md`](ITERATIVE-GROUNDED-RESEARCH.md). ## Schnellstart ```bash cp .env.example .env # Pfade, Ollama-Pool und optional GLPI-Zugangsdaten anpassen. set -a; . ./.env; set +a go run ./cmd/brain ``` Oberfläche: `http://localhost:8090` Docker: ```bash docker compose up -d --build ``` ## Mehrere Ollama-Instanzen `OLLAMA_URLS` hat Vorrang vor dem weiterhin unterstützten `OLLAMA_URL`. ```env OLLAMA_URLS=http://10.20.30.21:11434,http://10.20.30.22:11434,http://10.20.30.23:11434 OLLAMA_NODE_NAMES=gpu-01,gpu-02,gpu-03 OLLAMA_NODE_WEIGHTS=1,1,4 OLLAMA_ROUTING_MODE=least_inflight OLLAMA_NODE_MAX_INFLIGHT=1 OLLAMA_FAILOVER_ENABLED=true OLLAMA_FAILOVER_ATTEMPTS=0 OLLAMA_REQUIRE_SAME_MODEL_DIGEST=true OLLAMA_REQUIRE_EMBEDDING_MODEL=true ``` Unterstützte Routing-Modi: - `least_inflight` – bevorzugt den aktuell am wenigsten belasteten Node; - `round_robin` – zyklische Verteilung; - `weighted` – Verteilung entsprechend `OLLAMA_NODE_WEIGHTS`; - `fastest_recent` – bevorzugt die zuletzt schnellsten Nodes. Jeder Node muss das Chatmodell besitzen. Mit `OLLAMA_REQUIRE_EMBEDDING_MODEL=true` muss außerdem jeder Node das Embeddingmodell besitzen. Bei aktivierter Digest-Prüfung wird ein Pool mit unterschiedlichen Modellständen fail-closed behandelt. Mehr Details: [`OLLAMA-POOL.md`](OLLAMA-POOL.md). ## GLPI-Knowledgebase einbeziehen Die Integration verwendet denselben read-only OAuth-/OpenAPI-Ansatz wie der Agent. GLPI entscheidet anhand des Service-Accounts, welche Beiträge sichtbar sind. ```env GLPI_KB_ENABLED=true GLPI_URL=https://glpi.example.org GLPI_API_VERSION=v2.3 GLPI_CLIENT_ID=... GLPI_CLIENT_SECRET=... GLPI_USERNAME=... GLPI_PASSWORD=... GLPI_KB_PATH=auto GLPI_KB_LIMIT=500 GLPI_KB_SYNC_INTERVAL=10m GLPI_KB_SOURCE=GLPI Knowledge Base ``` Bei `GLPI_KB_PATH=auto` sucht das Brain im GLPI-OpenAPI-Dokument die lesbare `KnowbaseItem`-Collection. Die Beiträge werden als produktive Wissens-Nodes mit `glpi://KnowbaseItem/`-URI aufgenommen. Kategorien und Quelle erzeugen verifizierte Edges. Es gibt keine GLPI-Schreiboperation. Manueller Sync: ```bash curl -X POST http://localhost:8090/api/glpi-kb/sync ``` Mehr Details: [`GLPI-KB.md`](GLPI-KB.md). ## SQLite/WAL-Persistenz und Vorberechnung ```env BRAIN_PERSIST_INTERVAL=5m ``` Der Live-Graph liegt im Arbeitsspeicher. Dauerhaft gespeichert werden nur geänderte Zeilen in `BRAIN_DATA_DIR/graph.db`: 1. AI-THINK-, Metadaten- und Cache-Dateien werden atomar geschrieben; 2. danach folgen geänderte Nodes, Edges und Vektoren in einer SQLite-Transaktion; 3. Embeddings liegen binär als `float32`-BLOBs vor; 4. unveränderte KB-Scans verursachen keine erneuten Graphwrites. Manueller Flush: ```bash curl -X POST http://localhost:8090/api/flush ``` Ein auf einem leistungsfähigen System vorberechneter Graph kann kompakt exportiert und auf ein System mit identischen Dokument-IDs und demselben Embedding-Modell kopiert werden: ```bash curl -fsS http://localhost:8090/api/state/export -o graph.db ``` Mehr Details: [`PERSISTENCE.md`](PERSISTENCE.md) und [`SQLITE-STORAGE.md`](SQLITE-STORAGE.md). ## Laufzeitsteuerung, Visualisierungen und Performance Die untere Steuerleiste enthält direkte Schalter für **LEARNING**, **THINKING**, **NEURAL**, **HONEYCOMB**, **CONSTELLATION** und **ECO**. Sind Learning und Thinking deaktiviert, bleibt das System im Living-Modus; eingehende Agent- oder KB-Anfragen können weiterhin die tatsächlich verwendeten Notes aktivieren. Über **FILTER** lassen sich drei unabhängige Kategorienlisten pflegen: - **Lernen**: neue Embeddings nur für passende Kategorien; - **Anzeige**: Browser-Rendering nur für passende Notes; - **Thinking**: neue AI-THINK-Kandidaten nur innerhalb der gewählten Kategorien. Leere Listen bedeuten „alle Kategorien“. Die Werte werden über die vorhandene Persistenzqueue in `runtime-settings.json` geschrieben. ```env BRAIN_LEARNING_ENABLED=true BRAIN_THINKING_ENABLED=true BRAIN_LEARNING_CATEGORIES= BRAIN_DISPLAY_CATEGORIES= BRAIN_THINKING_CATEGORIES= BRAIN_DEFAULT_VIEW=neural # neural | honeycomb | constellation BRAIN_MAX_DISPLAY_NODES=0 # 0 = unbegrenzt; alternativ z. B. 5000 BRAIN_LOW_POWER_MODE=false ``` Die Ansichten erfüllen unterschiedliche Aufgaben: - **Neural** zeigt das lebende semantische Netz mit LOD, Cortex, Synapsen und Partikeln. - **Honeycomb** rendert `knowledge`, `ai-think` und `external` gleichmäßig in einer 3D-Gehirnwabe. Reguläre Edges und Cortex-Flächen bleiben dort unsichtbar. - **Constellation** ordnet Wissenselemente als Themensterne um semantische Zentren an. Dezente Bahnen und aggregierte Themenverbindungen machen Fachgebiete und Übergänge leichter lesbar als ein dichtes Gesamtnetz. Der **ECO**-Schalter begrenzt die Ausgabe auf ungefähr 30 FPS, reduziert die Device-Pixel-Ratio, teure Gradienten, Hintergrundsterne, gleichzeitig sichtbare inaktive Edges, Partikel und Wolken. Aktivierte Nodes, SearXNG-Animationen, Themenzentren und Übergänge bleiben sichtbar. Das ist zusätzlich zum GPU-Node-Limit; der ECO-Modus entfernt keine Wissenselemente. Graphupdates verändern vorhandene Node-Objekte und Positionen in-place. Neue Elemente blenden ein, entfernte Elemente blenden aus, Ansichtswechsel morphen zwischen den Koordinatenräumen. Unveränderte Snapshots werden übersprungen und reine Edgeupdates lösen keinen vollständigen Layout-Neuaufbau aus. Mehr Details: [`VISUALIZATION-PERFORMANCE.md`](VISUALIZATION-PERFORMANCE.md) und [`RUNTIME-CONTROLS-HONEYCOMB.md`](RUNTIME-CONTROLS-HONEYCOMB.md). ## Autonome Anreicherung Der Worker arbeitet bewusst sequenziell, trennt aber jetzt zwei Aufgaben: 1. Kandidatenpaar aus bestehenden Vektoren auswählen; 2. **Relation Thinking** bewertet ausschließlich die Beziehung und erzeugt eine Edge oder verwirft sie; 3. bei einer bestätigten Relation werden drei bis acht verwandte Quellen gesammelt; 4. ein eigener Planungsaufruf entscheidet `create`, `update`, `merge` oder `skip`; 5. nur bei echtem Mehrwert schreibt ein zweiter Modellaufruf einen strukturierten Helpdesk-Artikel; 6. der Artikel landet als `AI-THINK` / `AI-Staging` / `AI-Synthesis` mit realem `text`- und `answer`-Inhalt im Staging; 7. der In-Memory-Graph sieht den Entwurf sofort, die Datei wird beim nächsten gebündelten Persistenz-Flush atomar geschrieben. Qualitätsregeln verhindern reine AI-THINK-Ketten: standardmäßig mindestens drei produktive Quellen, mindestens 70 Prozent Produktionswissen und maximal Generierungstiefe zwei. ```env BRAIN_AUTO_ENRICH=true BRAIN_ENRICH_INTERVAL=90s BRAIN_ENRICH_BATCH_SIZE=3 BRAIN_ENRICH_STEP_DELAY=3s BRAIN_ARTICLE_SYNTHESIS_ENABLED=true BRAIN_ARTICLE_MIN_SOURCES=3 BRAIN_ARTICLE_MAX_SOURCES=8 BRAIN_ARTICLE_MIN_PRODUCTION_RATIO=0.70 BRAIN_ARTICLE_MAX_GENERATION_DEPTH=2 BRAIN_ARTICLE_MIN_CONFIDENCE=0.74 ``` Details: [`KNOWLEDGE-SYNTHESIS.md`](KNOWLEDGE-SYNTHESIS.md). Der manuelle AI-THINK-Button bleibt vorhanden. Alternativ: ```bash curl -X POST 'http://localhost:8090/api/enrich?async=1' ``` ## HTTP-Endpunkte | Methode | Pfad | Zweck | |---|---|---| | `GET` | `/api/status` | Gesamtstatus inklusive Ollama-Pool, GLPI-KB und Persistenzqueue | | `GET` | `/api/graph` | vollständiger aktueller In-Memory-Graph | | `GET` | `/api/analysis` | strukturelle Graphanalyse | | `GET` | `/api/runtime-settings` | aktuelle Learning-, Thinking-, Filter- und View-Einstellungen | | `PUT` | `/api/runtime-settings` | Laufzeiteinstellungen ändern und gebündelt persistieren | | `GET` | `/api/categories` | verfügbare Note-Kategorien mit Anzahl | | `GET` | `/api/stream` | SSE-Aktivitätsstrom | | `POST` | `/api/query` | programmatische Wissensanfrage; in der Fullscreen-UI verborgen | | `POST` | `/api/events` | optionale Agent-/KB-Telemetrie | | `POST` | `/api/reindex` | lokaler Scan und Embedding-Abgleich | | `POST` | `/api/enrich` | AI-THINK-Zyklus einplanen/ausführen | | `POST` | `/api/glpi-kb/sync` | GLPI-KB manuell synchronisieren | | `POST` | `/api/flush` | ausstehende Dateien und geänderte SQLite-Zeilen sofort persistieren | | `GET` | `/api/state/export` | kompakte, konsistente `graph.db` exportieren | Mit `BRAIN_API_KEY` werden POST-Endpunkte über `Authorization: Bearer …` oder `X-Brain-Key` geschützt. ## Statusdiagnose ```bash curl http://localhost:8090/api/status | jq ``` Wichtige Bereiche: - `ollama_pool.nodes[]`: Health, Kompatibilität, Inflight, Requests, Fehler und mittlere Laufzeit; - `glpi_kb`: letzter Sync, Dokumentanzahl, Pfad und Fehler; - `persistence`: ausstehende Dateien, Dirty-Status, letzter Flush und Flush-Fehler; - `graph_storage`: SQLite-/WAL-Größe, Vector-Bytes, Row-Anzahl und ausstehende Änderungen; - `enrich_*`: Zustand des autonomen AI-THINK-Workers; - `relations_created`, `articles_created`, `articles_skipped`: getrennte Relation- und Artikelergebnisse. ## Validierung ```bash go test ./... go vet ./... node --check internal/web/static/app.js ``` ## Sichtbare SearXNG-Recherche SearXNG-Suchen werden als eigenständige Aktivität visualisiert. Scanringe markieren die laufende Suche, gefundene Quellen erscheinen als externe Quellenpunkte und fließen anschließend in die neu erzeugten Forschungs-Nodes. Die Animation bleibt bei der Aktualisierung des Graphen bestehen und läuft nach dem Einblenden der neuen Nodes mindestens zwei Sekunden weiter. Unter **FILTER → SearXNG-Diagnose** kann eine direkte Testsuche ausgeführt werden. Diese umgeht die fachliche Qwen-Entscheidung, verändert den Graphen nicht und zeigt eindeutig: - die tatsächlich verwendete Basis-URL, - HTTP-Status und Content-Type, - Trefferzahl und Laufzeit, - DNS-, Netzwerk-, TLS-, HTTP- und JSON-Fehler, - bei Fehlern den Antwortausschnitt von SearXNG oder Reverse Proxy. Die automatische Artikelrecherche zeigt zusätzlich Recherche-Runden, deutsch/englische Teilqueries, Kandidatenauswahl, Volltextabruf, Relevanz, Quellenqualität sowie akzeptierte und verworfene Belege. SearXNG-Snippets werden nicht als ausreichender Artikelbeleg verwendet. Die API-Endpunkte sind `GET /api/research/status` und `POST /api/research/test`. Details stehen in `SEARXNG-VISUALIZATION.md` und `ITERATIVE-GROUNDED-RESEARCH.md`.