# 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 drei einfache, exakte `source`-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** werden ausschließlich die exakten Werte des JSON-Feldes `source` ausgewählt. Es gibt keine Kategoriefilter, keine technische `origin`-Aliasauflösung und keine Schnittmenge aus Environment und WebUI mehr. - **Lernen**: Nur Nodes mit exakt passendem `source` erhalten neue Embeddings und dürfen bei semantischen Abfragen verwendet werden. - **Anzeige**: Nur Nodes mit exakt passendem `source` werden gerendert; direkt verbundene Kategorie-, Quellen- und Konzept-Nodes bleiben als visuelle Taxonomie sichtbar. - **Thinking**: Nur Nodes und explizit mit einer Quelle versehene Webbelege mit exakt passendem `source` dürfen neue Relationen und Artikel speisen. Mehrere ausgewählte Quellen verwenden ODER-Semantik. Eine leere Liste bedeutet „alle Quellen“. Der Vergleich ist nach dem Entfernen äußerer Leerzeichen **case-sensitiv und exakt**: ```text source: "internal-category" passt zu internal-category source: "internal-category" passt nicht zu Internal-Category source: "GLPI Knowledge Base" passt nicht zu glpi-kb ``` Der GLPI-Quellenname stammt ausschließlich aus: ```env GLPI_KB_SOURCE=GLPI Knowledge Base ``` Dieser Wert wird in der WebUI immer als Auswahl angeboten, auch wenn GLPI noch nicht synchronisiert wurde oder aktuell 0 Beiträge vorhanden sind. Die folgenden Environment-Variablen sind nur Startwerte, wenn noch keine neue versionierte `runtime-settings.json` existiert. Danach ist die WebUI-Auswahl die einzige aktive Konfiguration; es gibt keine zusätzliche Environment-Obergrenze: ```env BRAIN_LEARNING_ENABLED=true BRAIN_THINKING_ENABLED=true # Exakte Werte des KB-JSON-Feldes source; leer = alle BRAIN_LEARNING_SOURCES= BRAIN_DISPLAY_SOURCES= BRAIN_THINKING_SOURCES= BRAIN_DEFAULT_VIEW=neural # neural | honeycomb | constellation BRAIN_MAX_DISPLAY_NODES=0 # 0 = unbegrenzt; alternativ z. B. 5000 BRAIN_LOW_POWER_MODE=false ``` Alte `learning_categories`, `display_categories`, `thinking_categories` und frühere unversionierte Source-Filter werden beim ersten Start dieser Version bewusst ignoriert. Schalter, Ansicht und Performancewerte bleiben erhalten. Beim nächsten Speichern schreibt die WebUI `source_filter_version: 1`. `graph.db` muss dafür nicht gelöscht werden. 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: [`SOURCE-ONLY-FILTERS.md`](SOURCE-ONLY-FILTERS.md), [`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-, exakte Source- und View-Einstellungen | | `PUT` | `/api/runtime-settings` | Laufzeiteinstellungen ändern und gebündelt persistieren | | `GET` | `/api/sources` | exakte `source`-Werte mit Anzahl; enthält immer `GLPI_KB_SOURCE` | | `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`.