glpi-neuroforge-mega/docs/OPERATIONS.md

Betrieb

Standardbefehle

make test
make vet
make build
make up
# optional: Research/SearXNG ohne Autonomy
make research-up
make ps
make status
make logs
make down

Secrets

./scripts/generate-secrets.sh

Die Ausgabe wird nicht automatisch in .env geschrieben. Das verhindert, dass vorhandene Credentials versehentlich überschrieben werden.

Status

Das Control Center ist read-only und fragt parallel ab:

• Agent /readyz
• Knowledgebase /api/health
• NeuroForge /api/v1/stats mit App Key

Es zeigt keine Secrets und besitzt keine Schreibroute.

Knowledge Sync

knowledge/ ist das gemeinsame kanonische Verzeichnis:

• Knowledgebase: read/write
• Agent: read-only

Der Agent erkennt Änderungen inkrementell. In dual/neuroforge werden veränderte Chunk-Vektoren in das NeuroForge-Namespace synchronisiert. Entfernte Dokumente werden dort ebenfalls entfernt.

Externe Knowledge-Connectoren

Connector-Dokumente werden ebenfalls nach NeuroForge gespiegelt. Ihr lokaler Connector-Vektorcache wird derzeit bewusst beibehalten, damit Connector-Neustarts und Fail-open-Betrieb nicht bei jedem Zyklus neu einbetten müssen. Das ist eine Resilienz-/Effizienzentscheidung und unterscheidet sich von der Externalisierung der lokalen produktiven KB.

Obsidian-Export

./scripts/export-obsidian.sh kb ./knowledge-vault.zip
./scripts/export-obsidian.sh agent ./live-vault.zip

Der KB-Export liest die kanonischen JSON-Dateien. Der Agent-Export ergänzt synchronisierte GLPI-KB-Artikel und verfügbare KnowbaseItem_Item-Verknüpfungen. Beide Exporte sind read-only. Details: OBSIDIAN-EXPORT.md.

Research-Drafts

Ein Proposal-JSON kann kontrolliert ins Staging geschrieben werden:

{
  "source": "NeuroForge Research",
  "query": "VPN Fehlerbild",
  "title": "VPN Diagnose",
  "text": "Beobachtetes Symptom ...",
  "answer": "1. ...",
  "categories": ["VPN"],
  "keywords": ["gateway", "token"],
  "min_score": 0.85
}

export KB_INTEGRATION_TOKEN='...'
./scripts/propose-draft.sh proposal.json

Der Server erzwingt auto_reply=false. Promotion erfolgt im normalen Editor.

SQAR

SQAR ist ausschließlich im NeuroForge Vector Journal aktiviert. Nicht komprimiert werden operative Audit-/Policy-Dateien oder zufällig zugreifbare Memory-Segmente. Der Codec wählt nur dann die SQAR-Variante, wenn sie gegenüber der Roh-/DEFLATE-Darstellung tatsächlich kleiner ist.

Controlled Learning / Human Outcomes

Im Standard ist NEUROFORGE_CONTROLLED_LEARNING=true. Rohe Chat-/Assistant-Inhalte werden damit nicht automatisch als Langzeitwissen gelernt. Ein Agent-Run kann im Dashboard explizit bestätigt oder korrigiert werden. Das Outcome wird unter DATA_DIR/ticket-outcomes.json auditiert und erst dann über den App-Key-Pfad an NeuroForge übertragen.

Bei OUTCOME_LEARNING_FAIL_OPEN=false ist ein NeuroForge-Syncfehler für den Techniker sichtbar. Der lokale Outcome-Eintrag bleibt erhalten und kann durch Wiederholen derselben Entscheidung retryt werden. Änderungen am GLPI-Ticket seit dem analysierten Run blockieren die Validierung.

Optionales SearXNG / Research

Der Basisstack startet SearXNG nicht. Für Research zuerst einen echten SEARXNG_SECRET in .env setzen und dann:

./scripts/research-up.sh

Das startet das Compose-Profil research und schaltet Research/SearXNG für NeuroForge ein. NEUROFORGE_AUTONOMY_ENABLED bleibt separat und standardmäßig false. Details: CONTROLLED-AUTONOMY.md.