reference.md

Advanced details

Tables and sequence diagrams. Narrative: current.md. Setup: setup.md. Index: ARCHITECTURE.md.

Status vocabulary

Status	Meaning
Implemented	Present in the repository and exercised by an existing runtime path
Experimental	Buildable prototype or alternative implementation, not the canonical production path
Planned	Architectural contract exists, but the component is not yet implemented

Golden Record status: candidate / verified / rejected / stale. set_godbrain_status is the only status door. rejected is terminal. Content never changes; only status does.

Implemented loops

Loop	Discover	Execute	Verify
Heal / Watch	Probe ports + HTTP rag /health.ready and mouth /health; count inbox\*.txt	Start allowlist; one flushdns; rag-rebuild if projection unready (cooldown); one inbox file when mouth is idle; quarantine poison files; POST /api/observe; sre_surgeon --diagnose only when layer ≠ ok	Ports + ready; live inbox=N on /brief; Librarian claims stay candidate; remember on act/fail
Oracle chat	User question or CONTINUE	Mouth on :8000 (llama-server or coli serve)	Fail-closed RAG, loop abort, operator /verify /reject
Librarian	Transcript or inbox\*.txt	Distill claims (not a recap) through the live mouth	Schema/provenance; contradiction and open_question stay candidate
Judgment	Last Oracle turns, host card if candidate, and the newest unverified Golden Records	set_godbrain_status / POST /api/judge	Why string ≥ 4 chars; last-oracle inbox flips with Mongo; cards stay candidate until /verify
Named-card	12-char id in chat	RAG GET /v1/document	Return that Golden Record; no GPU; do not mint a new Oracle turn
Truth loop	Host pin / Learn quote / allowlisted probe	observe + POST /api/truth	Canonical observation only can auto-verify; caller prose stays candidate; pin mismatch → stale

Component inventory

Component	Status	Path	Interface	Responsibility
Mouth (llama-server or coli serve)	Implemented	scripts/Start-LlamaServer.ps1, LLM/colibri_LLM/c/	OpenAI chat on 127.0.0.1:8000	One GPU generate slot. Desk default is bartowski Gemma 12B IT Q6_K_L with MTP when the bartowski draft GGUF exists (-NoDraft to disable). Colibri is the interchangeable engine, not the protocol.
C++ Kernel	Implemented, canonical privileged boundary	godbrain_core/cpp_kernel/	HTTP on 127.0.0.1:8083	Galaxy hosting, Golden Record RAG via :8084, mouth invocation, built-in chat tools (local_tools.cpp, not MCP), privileged command_type dispatch, no-GPU GET doors
Phone Desk	Implemented read-only overview	godbrain_core/cpp_kernel/phone_desk.cpp, godbrain_core/frontend/phone.html	Loopback :8085, private Tailscale Serve HTTPS	Model/profile/VRAM and service status; exact owner proxy identity or local bearer; no recovery/control routes
Root Go router	Experimental alternative	main.go	HTTP on 127.0.0.1:8082	Golden Record RAG via :8084 and mouth invocation
Rust router	Experimental alternative	godbrain_core/rust_router/	HTTP on 127.0.0.1:8082	Golden Record chat via :8084; graph/node still 410
MongoDB knowledge store	Implemented dependency	Local MongoDB	MongoDB protocol on localhost:27017	Source documents and RAG records
C++ Memory Store	Implemented, desk write/retrieval	godbrain_core/cpp_memory_store/ (build/cpp_memory_store/Release)	JSON on stdin + HTTP :8084	Same doors as Go: ingest, judge, skills, search/graph/document. Start/Heal prefer this tree.
Go Memory Store	Implemented rollback	godbrain_core/memory_store/	JSON on stdin, MongoDB driver outbound	Same protocol; do not delete.
Golden Record RAG service	Implemented retrieval path	C++ Release, else Go cmd/rag-service/	HTTP on 127.0.0.1:8084	Bounded committed-only search, graph, and document reads with source-resolved citations
Native Librarian	Implemented	godbrain_core/cpp_tools/librarian.cpp	CLI, scripts/Invoke-Librarian.ps1, Heal inbox, POST /api/librarian	Derive a bounded Golden Record from a transcript and invoke the Memory Store. Uses the live :8000 mouth; does not hold VRAM.
Galaxy UI	Implemented	godbrain_core/frontend/galaxy.html	Browser UI served by the C++ Kernel	Graph browsing, chat, This host vs Pending, SRE glance
Brave extension	Implemented client	brave_extension/	HTTP to 127.0.0.1:8083	Page-context-assisted local chat
Native ingestors and SRE tools	Experimental	godbrain_core/cpp_ingestors/, godbrain_core/cpp_tools/, godbrain_core/sre_agent/	Standalone executables	Ingestors plus sre_surgeon --toolkit / --diagnose. Gated repairs need an operator GO. Heal never --ask.
Heal / Watch	Implemented host loop	Heal-GodBrain.ps1, Watch-GodBrain.ps1	schtasks / /api/heal	Detect TCP then HTTP ready, start missing allowlist, diagnose icmp/dns/nic, flushdns once after a DNS miss, rag-rebuild if unready, drain one inbox file, verify, remember on act/fail. Never kills.
CS2 pause	Implemented manual hold	Start-CS2.ps1, Watch-Cs2Pause.ps1	launch script + optional schtask backup	Stop EXL3/image/legacy model runtimes, pause gym/tasks and Tailscale, launch Steam app 730 and return. Resume only through explicit desk controls.
Agent Factory control plane	Planned, not next	docs/AGENT_FACTORY_ROSTER.md	Versioned job/evidence contracts	Do not staff this to grow the wiki.

C++ Kernel HTTP (127.0.0.1:8083)

Method	Route	Authentication	Purpose
GET	/	None	Redirect to Galaxy
GET	/galaxy	None	Serve the operator UI
GET	/frontend/*	None	Static frontend assets
GET	/api/test	None	Liveness response
GET	/api/graph	None	Bounded Golden Record graph (rag_documents, max 500 nodes)
GET	/api/node	None	Single Golden Record by node_id or stable_id
GET	/api/status	None on loopback	Kernel, mouth, VRAM, RAG, last Oracle, pending_items, host inventory
GET	/api/brief	None on loopback	One-glance host + mouth + pending + heal + CS2 + last-turn; writes logs/last-brief.txt
GET	/api/heal	None on loopback	Same text as /heal including age=; writes logs/last-heal.txt
GET	/api/sre	None on loopback	Layer + last diagnose snapshot (no GPU); writes logs/last-sre.txt
GET	/api/pending	None on loopback	Candidate Oracle, candidate host, newest unverified cards (skip kind=concept and Heal-loop labels); writes logs/last-pending.json
GET	/api/last	None on loopback	On-disk Oracle glance (no mouth); writes logs/last-oracle.txt
GET	/api/last-edit	None on loopback	Last local-edit result (no GPU); writes logs/last-edit.txt
GET	/api/events	None on loopback	Tail of logs/core-events.jsonl (no GPU); writes logs/last-events.txt
GET	/api/vram	None on loopback	One GPU slot + next worker size; writes logs/last-vram.json
GET	/api/doors	None on loopback	Loopback and Tailscale URLs; chat stays loopback-only
GET	/api/desk	None on loopback	Desk health used by Test-GodBrainDesk.ps1
POST	/api/remember	Bearer; 401 if unset	Save a candidate idea, or Brave selected-text evidence (title/url/selected) as untrusted browser_selection
POST	/api/librarian	Bearer; 401 if unset	Distill text via live :8000; fail-closed if CS2 sleeping, mouth busy, or :8000 down
POST	/api/observe	Bearer; 401 if unset	Host inventory (Heal each tick; unchanged is idempotent)
POST	/api/truth	Bearer; 401 if unset	Caller host_fact / doc_fact / playbook stays candidate; matching quote/probe may return a separate verified assertion
POST	/api/judge	Bearer; 401 if unset	verified or rejected with reasoning; rewrites logs/last-pending.json
POST	/api/index	Bearer; 401 if unset	Exactly {}; persist a bounded untrusted target-host index without a model or RAG rebuild
GET / POST	/api/context	Bearer; 401 if unset	Compose up to 4 KiB of framed shared context; personal/technical scope stays isolated
POST	/api/shelf	Bearer; 401 if unset	Bounded read/post of untrusted discussion/research, not Golden Record ingestion
GET	/api/shelf/schema	Bearer; 401 if unset	Discover the native working-shelf contract
POST	/api/chat	Reads open; bearer for write slashes	RAG plus streamed mouth inference; loopback only. /yolo duration and off, /verify, and /reject need the bearer (401 if unset). Bare /yolo, /yolo status, and /yolo ? stay reads
POST	/api/chat with command_type	Bearer; reasoning for high-risk	Direct privileged kernel dispatch

CORS: exact trusted loopback/Tauri origins only. CORS is not authorization.

Tailscale door

Binds when GODBRAIN_API_TOKEN is set and the adapter has a 100.x. Every route on that listener requires bearer, including GETs. Chat generate is not exposed.

GET: /api/brief, /api/vram, /api/heal, /api/sre, /api/status, /api/last, /api/doors, /api/desk, /api/pending, /api/last-edit.

POST: /api/remember, /api/librarian, /api/observe, /api/truth, /api/judge.

Read-only Phone Desk (127.0.0.1:8085)

GET/HEAD / serves the page; GET/HEAD /api/phone/status returns the bounded cached status snapshot. Requires configured GODBRAIN_API_TOKEN; accepts a local bearer or the exact device-owner identity added by the private Serve proxy, authenticated by live TCP ownership and the installed SYSTEM Tailscale service/worker identity (not headers alone). Direct clients need bearer authentication. Bodies, body framing and query parameters are denied. Never proxy :8083 or enable Funnel. No service/model starts, generation, command dispatch or vault writes. Mobile setup and actions: phone-control.md.

Galaxy slash commands (loopback)

/observe, /vram, /remember, /idea, /ideas, /verify, /reject, /recall (optional query searches verified records), /status, /last, /brief, /pending, /heal, /sre, /edit, /last-edit, /doors, /yolo (/yolo 60 timed mutate/elevate hat, /yolo off).

/verify last <why> and /reject last <why> judge the newest on-disk Oracle turn. /verify <12-char prefix> <why> resolves against /pending.

Privileged command_type

Tool	Purpose
save_godbrain_thought	Candidate Golden Record via memory-store.exe
query_recent_thoughts	Newest active-generation rag_documents
query_godbrain_skills	Promoted skills only; untrusted procedure text
record_godbrain_skill_run	Append-only skill_verification_runs
promote_godbrain_skill	Requires verified origin + latest run passed
set_godbrain_status	verified / rejected / stale with reasoning
get_system_telemetry	Hardware/system awareness
observe_godbrain_host	Windows inventory + os_pin; auto-verified sensor
promote_godbrain_claim	POST /api/truth host_fact / doc_fact / playbook
execute_godbrain_script	PowerShell; requires reasoning + bearer
propose_sovereign_architect_change	PowerShell; requires reasoning + bearer

Golden Record RAG (127.0.0.1:8084)

Method	Route	Authentication	Purpose
GET	/health	None	Readiness, generation, retrieval-mode watermarks
POST	/v1/search	None	Bounded lexical or measured hybrid retrieval
GET	/v1/graph	None	Bounded active-generation node list (limit default 250, max 500)
GET	/v1/document	None	One active-generation document by id (node_id hex or stable_id)
POST	/v1/skills	None	Promoted skills only; procedure text is untrusted. Not mixed into /v1/search.

Unready corpus → 503. Graph links are a bounded star of nodes that share a source_hash (or run_id) in rag_provenance, not semantic edges. Default search is lexical; hybrid is opt-in behind a pinned loopback embedding provider.

Vault mapping and collections

Vault idea	GodBrain
/raw (never edit)	Immutable sources in Memory Store
/wiki (processed)	Committed Golden Records / rag_documents
/questions	open_question candidates
Contradiction flag	contradiction candidate; both sides stay until judge
Weekly digest	Pointer over processed records only (not a scheduler)

Source-of-truth collections:

Collection	Contract
sources	Immutable raw sources keyed by legacy Keccak-256 source hash
knowledge_nodes	Immutable semantic node versions
run_node_links	Append-only run-to-node observations, including evidence spans
source_observations	Append-only external-source ingestion identities
ingestion_runs	Lease-guarded staging -> validated -> committed
skills	Verified committed-node promotions only

Separate working collections discussion_messages and research_notes contain immutable, hash-bound untrusted posts. Their identity includes target host, shelf, scope and request; identical retries are idempotent and changed retries fail. They do not enter canonical ingestion or rag_documents. The native-only stdin extension is command="shelf", action="post"|"read"; existing C++/Go ingestion contracts remain unchanged. See the native store contract.

Derivative collections (rag_documents, rag_provenance, rag_embeddings, rag_metadata) are rebuildable. Cleanup may delete derivative generations, never source/node/run/link/observation/skill records.

Memory Store: one JSON document on stdin, cap 15 MiB. Ingestion accepts only trust_tier == "candidate". Stdout is one receipt; logs go to stderr.

Configuration

Variable	Used by	Purpose
GODBRAIN_API_TOKEN	C++ Kernel	Bearer for command_type, chat writes, and the Tailscale door. An unset token fail-closes those writes
GODBRAIN_COLIBRI_PATH	Heal / spawn path	Override Colibri executable. Kernel does not cold-spawn on 16 GB
GODBRAIN_COLIBRI_DIR	Start-GodBrain	Colibri tree (../colibri/c preferred)
GODBRAIN_COLIBRI_MODEL	C++ Kernel	Model id for coli serve (default glm-5.2-colibri)
GODBRAIN_COLIBRI_KEY	C++ Kernel	Bearer for coli serve if COLI_API_KEY is set
GODBRAIN_FRONTEND_DIR	C++ and Go routers	Override Galaxy static-file directory
GODBRAIN_SNAPSHOT_PATH	Routers and SRE tools	Override model snapshot directory
GODBRAIN_CUDA_EXPERT_GB	C++ Kernel	Override Colibri VRAM expert budget
GODBRAIN_COLI_OVERCOMMIT	C++ Kernel	1 allows experts to spill into RAM. Default off
GODBRAIN_LIBRARIAN_PATH	scripts/trigger_librarian.ps1	Override librarian.exe
GODBRAIN_LIBRARIAN_SPAWN	Native Librarian	1 allows Librarian to cold-spawn Colibri. Default off
LLM_RUNNER_PATH	Native Librarian	Override Colibri executable for framed inference
MONGO_STORE_PATH	Native Librarian	Override memory-store.exe
GODBRAIN_TEMP_DIR	Native ingestors	Override temp script/output location
GODBRAIN_TELEMETRY_LOG	ETW daemon prototype	Override telemetry log location
MONGODB_URI	memory-store.exe and rag-rebuild.exe require it. rag-service.exe defaults if unset. rag-eval.exe does not use it.	Connection string. Start copies it into WMI children; keep-list default is mongodb://127.0.0.1:27017.
MONGODB_DB_NAME	Mongo-backed commands (memory-store, rag-rebuild, rag-service)	Override database. Default godbrain. Copied into Start-GodBrain WMI children.
GODBRAIN_RAG_PORT	RAG service only	Numeric bind port. Do not set on this desk. The C++ kernel is hardcoded to 127.0.0.1:8084. Changing the port desyncs Galaxy/chat.
GODBRAIN_RAG_PREFERRED_SCHEMA_VERSION	RAG service	Optional schema version ranking preference
GODBRAIN_EMBEDDING_ENDPOINT	memory-store.exe, rag-rebuild.exe, rag-service.exe	Optional exact-loopback embedding HTTP origin. All three call rag.EmbeddingRuntimeFromEnvironment().
GODBRAIN_EMBEDDING_MODEL	same three	Optional embedding model id (with revision, sha256, dimension)
GODBRAIN_RAG_EMBEDDING_REQUIRED	same three	1 fail-closes when the embedding provider is down or incomplete
GODBRAIN_LIBRARIAN_MODEL	Native Librarian	Mouth model id override
GODBRAIN_MOUTH_HOST	Native Librarian	Mouth host (default 127.0.0.1)
GODBRAIN_MOUTH_PORT	Native Librarian	Mouth port (default 8000)
PROMPT_TEMPLATE_PATH	Native Librarian	Override extract prompt file
GODBRAIN_SHOW_CONSOLE	C++ Kernel	1 keeps a console window

This table is the operator set, not every env a nested tree reads. Embedding identity also needs GODBRAIN_EMBEDDING_MODEL_REVISION, GODBRAIN_EMBEDDING_MODEL_SHA256, and GODBRAIN_EMBEDDING_DIMENSION together; invalid or incomplete identity fails those three executables, not only search.

Start-GodBrain launches children through WMI with a keep-list: PATH and friends, MONGODB_URI, MONGODB_DB_NAME, GODBRAIN_API_TOKEN, GODBRAIN_RAG_PREFERRED_SCHEMA_VERSION, and the embedding identity (GODBRAIN_EMBEDDING_*, GODBRAIN_RAG_EMBEDDING_REQUIRED). It does not copy GODBRAIN_RAG_PORT (kernel is hardcoded to 127.0.0.1:8084). Empty optional vars stay omitted. The desk default is lexical RAG on :8084.

Secrets must not be committed, logged, inserted into prompts, or stored in graph records.

Runtime flows

Ordinary chat and RAG

sequenceDiagram
    participant U as Galaxy or extension
    participant K as C++ Kernel
    participant R as RAG service
    participant M as MongoDB
    participant Mouth as llama-server or coli :8000

    U->>K: POST /api/chat {"message": "..."}
    K->>K: Attach session-remembered notes if any
    K->>R: POST /v1/search
    R->>M: Active-generation rag_documents
    M-->>R: Bounded results
    R-->>K: Schema-valid untrusted context
    K->>K: Build augmented prompt
    K->>Mouth: POST /v1/chat/completions if :8000 is up
    Mouth-->>K: completion text
    Note over K,Mouth: If :8000 is down, refuse cold-spawn on 16 GB
    K-->>U: {"response": "..."}

Loading

If RAG is down but the kernel has session notes from /remember or /observe, chat still answers from that buffer. Boot hydrates the buffer from the newest Golden Records. If both are empty, fail closed.

Observe, remember, and judge

sequenceDiagram
    participant U as Galaxy
    participant K as C++ Kernel
    participant G as memory-store.exe
    participant M as MongoDB
    participant R as RAG service

    U->>K: /observe or /remember
    K->>G: candidate Golden Record on stdin
    G->>M: commit plus rag_documents projection
    G-->>K: receipt
    K->>K: keep note in process session buffer
    U->>K: /verify, /reject, or POST /api/judge plus reasoning
    K->>G: set_status
    G->>M: status only on knowledge_nodes
    G->>R: sync rag_documents status
    G-->>K: judgment receipt

Loading

Privileged command

sequenceDiagram
    participant O as Trusted caller
    participant K as C++ HTTP boundary
    participant D as Kernel dispatcher
    participant P as PowerShell or native operation

    O->>K: POST /api/chat + command_type + bearer token
    K->>K: Validate origin where applicable and token
    K->>D: Dispatch typed command payload
    D->>D: Validate command and reasoning policy
    D->>P: Execute authorized operation
    P-->>D: Exit status and output
    D-->>O: Structured success or error

Loading

Librarian (Copilot trigger)

sequenceDiagram
    participant T as scripts/trigger_librarian.ps1
    participant L as librarian.exe
    participant G as memory-store.exe
    participant M as MongoDB

    T->>T: Locate latest events.jsonl and extract transcript
    T->>L: session_id --file transcript
    L->>L: Verify source hash and derive candidate records
    L->>G: Golden Record JSON on stdin
    G->>M: Stage immutable records and run links
    M-->>G: Persisted results
    G->>M: Validate and commit ingestion run
    G->>M: Confirm committed RAG projection
    G-->>L: StoreReceipt JSON
    L-->>T: Process exit status

Loading

Heal inbox and scripts/Invoke-Librarian.ps1 use the same Librarian → Memory Store path, with the live :8000 mouth.

Trust zones and controls

1. Untrusted input: browser text, retrieved web, DB documents, model output.
2. Local application zone: UI and ordinary RAG APIs on loopback.
3. Privileged execution zone: authenticated C++ Kernel dispatch.
4. Credential zone: env-provided API and MongoDB credentials.
5. External services: market APIs and other explicitly configured endpoints.

Data never becomes executable merely because it came from a model or database.

Current controls: loopback binds, CORS allowlist, bearer for command_type and the Tailscale door, non-empty reasoning for high-risk commands, exact-child process timeouts, text nodes in the UI (not raw HTML), Heal never kills and never runs the repair cocktail.

Known limitations: bearer is coarse; ordinary loopback GET glances stay open and chat writes fail closed without a configured token; raw PowerShell exists behind the privileged boundary; Galaxy links are provenance stars; Rust router graph/node is 410; structured audit belongs to Factory and is required before anyone enables autonomous privileged execution — which this host is not doing.

Failure and logs

• Start-GodBrain waits up to 30s for Mongo :27017, logs that RAG will fail, then still launches rag-service, mouth, and kernel. Chat/RAG fail closed until Mongo is up. It does not abort the whole desk.
• Spawn/timeout errors return failure, not synthetic model output.
• Projection failure after commit is explicit; rag-rebuild repairs; committed runs never go back to failed.
• Failed inbox extracts move to inbox\failed\.
• If :8000 is down, chat and Librarian fail closed (or Heal/status kick Start-LlamaServer). No 16 GB cold-spawn.

File	Written by
logs/last-brief.txt	/brief, Heal
logs/last-heal.txt	/heal
logs/last-sre.txt	/sre, Start-GodBrain
logs/last-pending.json	/pending, /verify, /reject
logs/last-vram.json	/vram, Heal
logs/last-oracle.txt	/last
logs/last-edit.txt	/last-edit
logs/heal-last.json	Heal
logs/where-we-are.md	scripts/Write-SessionDigest.ps1
logs/mouth.txt	mouth starter
logs/last-doors.json	/api/doors, Heal
logs/last-edit-plan.txt	/edit plan pass
logs/last-edit-result.json	/edit apply
logs/last-desk-test.json	Test-GodBrainDesk.ps1
logs/last-sre-diagnose.txt	Heal sre_surgeon --diagnose
logs/last-skill-lab.json	Verify-SkillLab.ps1
logs/core-events.jsonl	Kernel no-GPU door snapshots (brief/pending/heal/vram/chain/edit)
logs/last-events.txt	GET /api/events glance
logs/last-core-gate.json	scripts\Test-GodBrainCore.ps1
logs/coli-model.txt	Colibri snapshot pin
logs/cs2-pause.json	CS2 pause gate
logs/godbrain-logon.log	Start-GodBrain.ps1
logs/watch.log	Watch tick
logs/heal.jsonl	Heal (one JSON line per tick)
logs/<name>.launch.cmd	Start-LoggedProcess writes a wrapper (stdio redirect + local MONGODB_URI). Canonical Start launches the exe via WMI, not this cmd, so Windows Terminal does not flash. <name>.out.log / .err.log are not filled by that path.

Logs must redact bearer tokens, credentials, private keys, and sensitive prompt content. This list is the glance/Heal/start set, not every file under logs/.