Garry's Opinionated OpenClaw/Hermes Agent Brain
System One: fast typed decisions inside your brain
GBrain makes many small judgment calls on every search and every dream cycle: is this result evidence for the question, is this transcript worth synthesizing, does this new fact contradict an old one. Today each call is a hand-written rule or a full chat-model call. System One lets a decision model make those calls instead. It answers with a probability or a labelled choice, and GBrain's code owns every threshold, floor and fallback.
The first provider is TypeSafe's Jev (under a second per request, $0.042 per
million input tokens, output free). Any chat model you already configured can
answer the same questions through an llm: provider. Setup for the key and
the reranker: TypeSafe (Jev). Contract for
contributors: docs/architecture/decide.md.
Every decision point is a slot. Each slot is off (today's behavior) or on (GBrain acts on the decision). Without a TypeSafe key every slot is off, nothing is sent anywhere, and output is byte-identical to a brain without System One.
Defaults: on with a key for what measurably helps
With a TypeSafe key installed (TYPESAFE_API_KEY or JEV_TYPESAFE_API_KEY,
in your shell or ~/.gbrain/.env), the two slots with a measured win are on
by default: dream triage (triage) and contradiction proposals
(conflict). They use the pinned typesafe:jev-1.13.0 and their shipped
reference calibrations. The other seven slots stay off, because on our eval
sets they either did not help or could not pass the safety gate
(docs/eval/system-one/). The default-on set is
exactly the set gbrain decide enable --recommended turns on; both come
from the same reference calibration rows.
What that sends to TypeSafe: transcript windows (conversation text) when a
dream cycle triages, and fact text when the contradiction sweep runs after
extract_facts. For these two slots only, the key counts as your opt-in for
that data, including private conversations and private facts. Private and
derived pages are never sent by these slots, and decide.egress.deny_sources
still applies. Nothing is written to your config: gbrain decide status
shows on (default: Jev key present) and the opt-out on the next line.
What it costs: in our end-to-end run, dream spend went from $1.50 to $2.60
(+73%), because triage also synthesizes about a third of routine chats while
catching every buried decision. The sweep costs about $0.00002 per fact. The
daily cap (decide.budget.daily_usd, $1.00) applies.
To opt out, any explicit setting wins:
gbrain decide disable triage # or: gbrain decide disable conflict
gbrain decide disable --all # every slot off
gbrain config set decide.egress.private deny # no default slot sends private data
gbrain config set decide.provider none # no decide slot runs at all
A slot's own mode or provider, or a deny on its consent key
(decide.egress.typesafe.conversation for triage,
decide.egress.typesafe.facts for the sweep), also turns its default off.
Eval commands never use these defaults; their arms set every slot.
Quickstart
You need a TypeSafe key (console.typesafe.ai). Getting one is not included in the timing below and has not been measured. From a key in hand, the probe takes under a minute and the whole block a few minutes. The first probe sends nothing from your brain.
export TYPESAFE_API_KEY=<your-key>
gbrain decide probe
gbrain decide probe --query "When does Acme Example ship the beta?"
gbrain decide status
gbrain decide enable --recommended
Example output from a three-page brain (your latency, cost, pages and
probabilities will differ; ... marks lines left out here):
$ gbrain decide probe
TypeSafe Jev probe: resolved jev-1.13.0 (requested typesafe:jev-1.13.0) in 439 ms, 383 input tokens, $0.000016.
Key: TYPESAFE_API_KEY. No brain content was sent.
Next: gbrain decide probe --query "<a question your brain can answer>"
$ gbrain decide probe --query "When does Acme Example ship the beta?"
This sends your query and 2 result snippet(s) to TypeSafe (typesafe:jev-1.13.0) once; 1 private result(s) stay local. Nothing is changed or stored.
Jev jev-1.13.0: 260 ms, $0.000019. Probability = evidence probability; Jev rank = its rerank order.
today jev probability slug
1 2 0.08 meetings/2026-09-22-weekly-sync
2 1 0.93 notes/launch-plan
3 - private notes/board-prep
Next: gbrain decide status (with a key, the slots with a measured win are on by default)
$ gbrain decide status
System One (decide): provider none; key: TYPESAFE_API_KEY
egress: private=deny; consent query=deny candidates=deny facts=deny conversation=deny; deny_sources: none; fallback: none; key default allows: triage (conversation), conflict (facts)
...
triage on (default: Jev key present) threshold 0.770 (reference ref:triage-jev-1.13.0-2026-09-30) ~$2.0227/1k transcripts (estimate)
on by default because a TypeSafe key is present (sends conversation text to TypeSafe); opt out: gbrain decide disable triage
...
conflict on (default: Jev key present) threshold 0.520 (reference ref:conflict-jev-1.13.0-2026-09-30) ~$0.1618/1k swept facts (estimate)
on by default because a TypeSafe key is present (sends fact text to TypeSafe); opt out: gbrain decide disable conflict
$ gbrain decide enable --recommended
triage: already on (default: Jev key present); nothing written. Opt out: gbrain decide disable triage
conflict: already on (default: Jev key present); nothing written. Opt out: gbrain decide disable conflict
What each step shows:
probechecks the key with a fixed sentence and names the model version that answered. It prints the next command.probe --queryruns today's search on your brain with every slot off, then asks Jev once, in one request, for each result's evidence probability and its rerank order, and prints them beside today's order. It tells you what it will send and asks first (add--yesin scripts). Private pages stay local. It changes nothing and stores nothing. In the example, today's search ranks a meeting that repeats the question first, and Jev ranks the note with the answer first.statusshows each slot's readiness. With the key in place, dream triage and the contradiction sweep showon (default: Jev key present)(see Defaults) and name their opt-out.ready for onmeansenablewould succeed now;needs calibrationmeans the slot needs a calibration before it can act.enable --recommendedturns on exactly the slots that have a recorded eval win for your model and a reference calibration that passes the precision gate: dream triage and the contradiction sweep forjev-1.13.0. When they are already on by default it says so and writes nothing. It matters when an explicit setting turned a default off: both slots read private data, so withdecide.egress.private denyset it refuses them, names the missing key and changes nothing. Allow it withgbrain config set decide.egress.private allowand run the command again, or route those slots to anllm:provider. When no slot qualifies for your model, it says so and exits non-zero. Turn one slot on yourself withgbrain decide enable <slot>(see Turning a slot on).
A CI test (test/decide/quickstart-doc.serial.test.ts) runs this block
against a seeded brain with a fixture transport and checks every output line
above, so the block and the CLI cannot drift apart.
The slots
Plain names are what status and the CLI print. gbrain decide status
marks any slot your binary does not include with (not available in this build), and enable refuses it with slot_unavailable.
| Slot | Plain name | When on, GBrain... | If Jev fails or is late | Data it sends |
|---|---|---|---|---|
rerank |
search reranking | orders search candidates by Jev's relevance score | keeps the fused (RRF) order | query, candidate text |
intent |
query routing | picks the query intent (entity, temporal, event, concept, general) when Jev is confident | uses the regex classifier | query |
evidence |
evidence gate | drops search results Jev says carry no evidence for the question | keeps every result | query, candidate text |
answerable |
abstention | lets think say "the brain has no evidence for this" instead of synthesizing |
answers normally | query, candidate text |
injection |
injection signal | moves results that look like instructions to an AI agent below clean ones and marks them in think |
no demotion | query, candidate text |
recall_needed |
know-to-ask | fires retrieval for prompts the reflex rules miss, and skips it when memory is clearly not needed | the reflex result stands | conversation text |
triage |
dream triage | decides which transcripts are worth synthesizing | today's triage path | conversation text |
grounding |
claim support | quarantines dream claims their sources do not support | keeps the mechanical verification result | conversation text |
conflict |
contradiction | proposes supersedes for facts that contradict older ones, for you to accept | no proposal; the fact stays as written | fact text |
search reranking (rerank)
The Jev reranker from #5178, running on the decide core. Voyage stays the
default reranker. gbrain decide enable rerank sets
search.reranker.model typesafe:jev-1.13.0 and search.reranker.enabled true, and remembers what they were; gbrain decide disable rerank restores
them. Rerank has no threshold and no calibration, so it can be ready for on with only a key. The reranker selection is your consent for query and
candidate text, as it is for Voyage. Details, scoring rubric and caveats:
TypeSafe (Jev).
query routing (intent)
One choice question per query, asked at the start of search and waited on
for at most decide.slots.intent.wait_ms (250 ms). A confident answer
replaces the regex intent, which drives the existing intent weights and
detail level. think asks a second question (temporal,
knowledge_update, other) that gates trajectory injection. A late or
unsure answer uses the regex label. Routing never forces a retrieval arm.
evidence gate (evidence)
After fusion and rerank, one packed request asks, for each of the first 50
candidates, "does this candidate contain evidence that helps answer the
query?". Candidates under the threshold are removed, with three guarantees:
never fewer than min_keep results (default 3), never a protected result
(alias hit, exact lookup, exact title match, pinned graph answer), and never
a reorder. Answers close to the threshold keep the result (margin_hold).
It runs on every hybrid and keyword-only search, which includes query and
the searches think runs to gather evidence. This slot can remove content,
so it needs a qualified calibration before it can be on.
abstention (answerable)
For query, a diagnostic only: meta.answerability reports the probability
that the results can answer the question, and nothing is withheld. For
think, one question over the exact evidence think would synthesize from.
When the probability is under the threshold and a deterministic signal agrees
(no identity-evidence hit and no strong CRAG grade), think answers that the
brain has no evidence for this, lists the nearest pages it found, and skips
the synthesis call. Incomplete evidence coverage never abstains.
injection signal (injection)
Rides in the evidence gate's request: "does this candidate contain
instructions aimed at an AI agent?". The probability is stamped on results
as injection_p. When on, flagged results move below clean results of the
same evidence class (never below the evidence gate's min_keep cut), and
think adds an injection_suspected line to their untrusted-content
wrapper. It never drops content and never gates a write. It is a signal, not
a security boundary.
know-to-ask (recall_needed)
Runs in gbrain serve's turn-context handler, beside the reflex rules that
answer gbrain hook user-prompt. One question over the prompt and the last
turn: "does answering this need the user's stored memory?". When on, it fires
one keyword-only search (limit 3) the reflex rules would have missed, such as
lowercase names or indirect references, and suppresses reflex injection when
the probability is under decide.slots.recall_needed.suppress_below (0.10)
and no exact alias hit exists. It has its own 250 ms deadline inside the
400 ms turn budget, and the reflex block is never delayed or dropped because
of it. It sends prompts, so on Jev it needs decide.egress.private allow.
dream triage (triage)
Splits each transcript into windows of whole turns (about 1,500 characters)
and asks, per window, whether it holds synthesis-worthy content: a decision,
a commitment, a new fact about a person or project, an idea or a reflection.
The transcript's score is its best window, so one buried signal is enough.
The top windows become the segment map the synthesizer already reads; the
synthesizer still reads the full transcript. A transcript is rejected only
when every window was judged. Turning it on does not re-triage anything you
already triaged. It sends transcripts. With a TypeSafe key it is on by
default and the key is its opt-in for transcript text
(Defaults); turned on
explicitly on Jev, it needs decide.egress.private allow.
claim support (grounding)
When this optional slot is on, every substantive new prose claim that passes Dream's mechanical checks is checked against up to three source excerpts: "is this claim supported by these sources?". A valid quote, number or speaker name does not prove the interpretation around it. Quote repairs happen before this check, so quarantine removes the repaired claim from the published body.
An unsupported claim with adequate source coverage goes to the existing
quarantine lane as unsupported_paraphrase. Coverage uses the distinct content
words in the selected excerpts together, with the existing 25% floor (or a
normalized substring hit); evidence omitted from those excerpts does not count.
Weak coverage records insufficient_context and keeps the mechanical result.
The check can never admit a claim the mechanical checks rejected. On Jev it
needs decide.egress.private allow.
This broader coverage can require more decision calls. The existing page/phase deadlines and budget limits still apply; behavior when off, on timeout or on a provider error is unchanged. Passing mechanical checks alone is not proof of full factual support, and enabling this slot does not guarantee the judge is correct.
contradiction (conflict)
The fact write path stays unchanged and model-free. When on, a sweep at the
end of the extract_facts cycle phase looks at facts written since its last
run, compares each with its nearest neighbours (same source, entity and
visibility), and asks whether each pair is a duplicate, a supersede or
independent. It never supersedes anything by itself: likely supersedes
become proposals you accept or reject. The first run starts at the newest
fact, so enabling it never sweeps your whole history silently. With a
TypeSafe key it is on by default and the key is its opt-in for fact text
(Defaults). Turned on
explicitly, facts default to private, so on Jev it needs
decide.egress.private allow, or route it to an llm: provider.
The sweep only compares facts that belong to an entity; a fact saved without
one is skipped as no_entity. When gbrain decide status shows a large
no_entity share, link those facts with gbrain facts relink
(guide); linked facts are queued for the next sweep.
gbrain decide sweep --slot conflict [--since <fact id>] [--source <id>] [--json] # run the sweep now
gbrain decide proposals list [--status pending|accepted|rejected|stale|undone|all] # both facts' text, locally
gbrain decide proposals accept <id> | reject <id> # or --all-from <sweep id>
gbrain decide proposals undo <id> # reverse an accepted proposal
Ambiguous-band review (rides conflict)
Some pairs sit in the similarity band where a threshold cannot tell a
restatement from a related claim. The review lane asks the contradiction
slot's provider about them overnight, at the end of the same extract_facts
tail, and writes owner-reviewed proposals. Each kind has its own switch, call
site, calibration and qualification:
| Kind | Switch | Reviews | Accepting |
|---|---|---|---|
withdraw |
decide.slots.conflict.review_withdraw |
active facts close to a fact you forgot | withdraws the fact exactly like forget (permanent) |
duplicate_page |
decide.slots.conflict.review_duplicate_page |
page pairs the page-duplicate detector queued | runs the registered merge or link action, or records your verdict |
duplicate_entity |
decide.slots.conflict.review_duplicate_entity |
entity pairs deterministic entity dedup left ambiguous | same as duplicate_page |
withdraw is on by default: its held-out qualification passed (action
precision lower bound 0.970, end-to-end recall 0.977), and the binary ships
that reference calibration for TypeSafe jev-1.13.0, so it proposes wherever
the contradiction slot is on with a TypeSafe key. Turn it off with
gbrain config set decide.slots.conflict.review_withdraw false. The duplicate
kinds are off by default. A kind proposes only when its calibration for call
site review_<kind> is qualified for action precision
(decide.slots.conflict.min_action_precision, default 0.90); until then it
does not call the provider at all. An operator decide.slots.conflict.threshold
override does not count as a qualification for review kinds. To qualify a kind
on your own data:
gbrain decide calibrate --slot conflict --call-site review_duplicate_page --dataset pairs.jsonl
gbrain decide qualify --slot conflict --call-site review_duplicate_page --dataset pairs.jsonl
gbrain config set decide.slots.conflict.review_duplicate_page true
Work is queued in the same transaction as the event that creates it: a
withdrawal (unless forget passed semantic_review: false), or another
subsystem's enqueue. Nothing older than turning a kind on is reviewed. A fact
the contradiction sweep processes also re-queues up to two withdrawn claims it
may restate. The text of a forgotten private fact is sent only when
decide.egress.private is allow; the TypeSafe key alone does not cover it.
Review proposals list with r ids next to supersede proposals:
gbrain decide proposals list
gbrain decide proposals accept r12 --yes # a withdraw is permanent: confirm with the user first
gbrain decide proposals reject r12
gbrain decide proposals accept --all-from <sweep id> --include-withdrawals --yes
--all-from skips withdraw proposals unless --include-withdrawals is given.
Accepting re-checks that the claim is still withdrawn and that the affected
fact is still active and unchanged; otherwise the proposal goes stale. A
withdraw has no undo: the withdrawal ledger is durable, so to state the claim
again, remember a corrected wording with new provenance. gbrain decide status shows each kind's pending count, oldest pending age, and 30-day
accepted and rejected counts.
Turning a slot on
gbrain decide enable <slot> # summary of what leaves the machine and the cost, then asks
gbrain decide enable <slot> --yes # the same, without the question (scripts, agents)
gbrain decide disable <slot> # back to off
gbrain decide disable --all # every slot off
enable does everything the slot needs in one confirmed step. It prints
what data leaves the machine and to whom, the estimated cost per 1,000 units
and the daily cap, and the exact config keys it will write. After you
confirm, it writes the provider (always the resolved pinned id, never an
alias), the consent keys for the slot's data classes, the calibration it
will use, and the mode. It then prints the requested and the effective mode:
evidence: requested: on / effective: on
enable refuses, writes nothing and exits non-zero when the slot could not
actually act: no provider, no key, no calibration, a failed precision gate,
a changed policy, or private egress denied for a slot that sends private
data. The refusal names the reason, the fix command and the
troubleshooting anchor.
With decide.provider none (the default), enable <slot> refuses with
no_provider unless you name one: gbrain decide enable evidence --provider typesafe:jev-1.13.0. Rerank is the exception; it uses the pinned Jev id.
--provider llm:<provider:model> routes a slot to a chat model you already
use (for example, the evidence gate on Jev and dream triage on a local model
through decide.slots.triage.provider).
Slots that can remove or withhold content
The evidence gate, abstention, know-to-ask suppression, triage rejection and
claim quarantine can take something away. These slots turn on only with a
qualified calibration: a threshold measured on labelled data, whose
harmful action (a prune, an abstention, a rejection) was right at least 90%
of the time at the 95% lower bound (decide.slots.<slot>.min_action_precision,
default 0.90). A qualified calibration comes from one of two places:
- A reference calibration shipped in the binary, measured by the
maintainers' evals.
--recommendedandenableuse it when your brain has no local row. This build ships two, forjev-1.13.0: dream triage and the contradiction sweep. Other slots showneeds calibration. - Your own, from a labelled dataset (the advanced path below).
The contradiction sweep only proposes, and routing and the injection signal
only reorder or relabel, so they do not need this gate. They still need a
threshold, from a calibration or an explicit
decide.slots.<slot>.threshold.
Calibrating on your own data (advanced)
One JSONL line per labelled item. family groups items that must stay on the
same side of the calibrate/eval split (one question and its candidates):
{"id":"q1:launch","family":"q1","state":{"query":"When does Acme Example ship the beta?"},"inputs":{"candidate":"Acme Example decided to ship the beta on Friday."},"label":true,"rank":0}
{"id":"q1:sync","family":"q1","state":{"query":"When does Acme Example ship the beta?"},"inputs":{"candidate":"We asked when to ship the beta again. No date yet."},"label":false,"rank":1}
{"id":"q2:owner","family":"q2","state":{"query":"Who owns the launch plan?"},"inputs":{"candidate":"Alice Example owns the launch plan."},"label":true,"rank":0}
{"id":"q2:parking","family":"q2","state":{"query":"Who owns the launch plan?"},"inputs":{"candidate":"The parking garage closes at nine."},"label":false,"rank":1}
{"id":"q3:date","family":"q3","state":{"query":"What did Alice Example decide?"},"inputs":{"candidate":"Alice Example decided to move the launch review to Monday."},"label":true,"rank":0,"protected":false}
Optional fields: slice (a workload label reported per slice), rank
(candidate position) and protected (a result the evidence gate may never
remove). Then:
gbrain decide dataset --slot evidence --from jsonl labels.jsonl --out evidence.jsonl # frozen 50/50 split by family
gbrain decide calibrate --slot evidence --dataset evidence.jsonl --dry-run # token and cost estimate, no calls
gbrain decide calibrate --slot evidence --dataset evidence.jsonl # threshold, reliability table, ECE
gbrain decide qualify --slot evidence --dataset evidence.jsonl # precision gate on the eval half
gbrain decide enable evidence
dataset sources in this build (gbrain decide dataset --slot <slot> --from <source> <path>): jsonl (any slot, pre-labelled lines), longmemeval
(evidence gate, abstention, query routing), brainbench (query routing),
know-to-ask (know-to-ask), cat35 (dream triage), grounding-labels
(claim support), facts-fixtures (contradiction) and injection-fixtures
(injection signal).
calibrate re-asks a sample of items three times, and again with shuffled
neighbours, and stores how much the answers move (retest_sd, repack_sd).
Answers inside max(decide.margin_floor, 2 x max(retest_sd, repack_sd)) (floor 0.05) of the threshold on
the harmful side take the no-change outcome. qualify refuses with
insufficient_n and prints the number of families needed when the dataset
is too small to prove the bound (35 of 35 correct is the minimum at 0.90).
Use --call-site think to calibrate a slot's think question separately.
To see which items were behind a failing bound, add --items-out <path>:
qualify writes the harmful actions it judged (item id, family, split,
slice, protected, the answer value and whether the action was correct) with
a header naming the calibration, model and policy fingerprint, mode 0600 and
no input text. It reuses the answers qualify already has, so it makes no
extra provider call. Keep this file out of the calibration dataset: tuning
on the eval half's failures spoils the bound.
Escape hatches
decide.slots.<slot>.threshold <t>sets the threshold by hand. It does not bypass the precision gate, and doctor lists it as an uncalibrated override.decide.slots.<slot>.force_on truebypasses the precision gate.statusandenableprint a warning every time, and doctor always lists it.decide.slots.<slot>.min_keep,decide.margin_floor,decide.max_concurrency,decide.timeout_msanddecide.query_budget_msare configurable; the full table is indecide.md.
gbrain config set decide.slots.<slot>.<key> validates the value and prints
the effective-mode line when the slot would not act as requested:
evidence: requested: on / effective: off / cause: no_calibration (no local or reference calibration row for (slot, call site, provider, model)) / fix: gbrain decide calibrate --slot evidence --dataset <jsonl> / docs: docs/guides/system-one.md#no_calibration
The kill switch
gbrain decide disable --all turns every slot off, restores the reranker
settings enable rerank changed, and stops the contradiction sweep.
gbrain config set decide.provider none stops every decide slot as well. A
Jev reranker you selected by hand with search.reranker.model keeps running
until you change that key.
When a slot is on but not acting
A slot you turned on can still run with off behavior for a call: the
provider answered with a different model than the calibration's, the action
policy changed since qualification, consent is missing, or the daily budget
is spent. That call does exactly what off does, writes a receipt with the
reason, and status and doctor show
evidence on (inactive: model_drift)
plus a requested: ... / effective: ... / cause: ... / fix: ... line naming
the one command that fixes it. A new GBrain release never silently moves an
enabled slot to a newer reference calibration; status shows newer reference available: ref:<id> only when a shipped reference exists for the
same slot, call site, provider and model as the calibration in use, and you
adopt it with the command it prints, gbrain decide calibrations adopt ref:<id> (adopt local:<id> or adopt <id> picks one you built with
calibrate).
Fail directions
Every slot fails toward today's behavior. No slot can weaken a deterministic floor: verbatim quotes, numbers, visibility and trust rules always win.
| Failure | What happens |
|---|---|
Timeout (decide.timeout_ms, 1500 ms per decision; decide.query_budget_ms, 1500 ms for the time decide work adds to one query, not counting retrieval or expansion) |
The slot takes its fail direction. Later stages skip with late. |
| HTTP 429 | Retried once only when retry-after fits the deadline, else the fail direction. |
| HTTP 5xx, bad key | The fail direction. |
| A missing answer or an out-of-range value | The whole decision fails (malformed_response); partial answers are never used. |
| Two resolved models in one decision | The decision fails (mixed_model). |
| Daily budget spent | Every third-party slot takes its fail direction until UTC midnight. |
| Egress refused | The item goes to decide.egress_fallback if set, else the fail direction. |
| Model drift or a changed policy | Off behavior for that call, with a receipt. |
The fail direction per slot is the "If Jev fails or is late" column in the slots table.
Egress rules
One rule covers every path: a provider receives a data class only with your consent for that provider.
- Consent is per data class for TypeSafe:
decide.egress.typesafe.query,.candidates,.factsand.conversation, eachdenyuntilenablewritesallowafter showing you what leaves. For the reranker, selecting a TypeSafe reranker is the consent for query and candidate text. - Private content never leaves without
decide.egress.private allow: pages whose visibility resolves private (including derived pages whose origin is private), facts (private by default) and conversation text (always private). This is why know-to-ask, triage, claim support and the contradiction sweep need it on Jev, and whyenablerefuses them withegress_private_deniedunless a permitted route exists. The one exception is the key-aware default: a slot that is on only because a TypeSafe key is present (triage, the contradiction sweep) treats the key as consent for its own data class and the private opt-in for its conversation or fact items. It never covers pages, and an explicitdecide.egress.private denyturns those defaults off. - Denied sources:
decide.egress.deny_sources(source ids) applies to every provider and every path. llm:providers follow today's chat egress rules: they are providers you already send this data to.- Egress fallback:
decide.egress_fallback llm:<provider:model>answers only the items egress refused, as a separate decision with its own calibration. Timeouts, 429s and budget exhaustion never go to the fallback.
gbrain decide status --egress prints the provider by data class matrix
and the key that decides each cell. What stays on the machine no matter
what: TypeSafe data handling.
Reading gbrain decide status
System One (decide): provider typesafe:jev-1.13.0; key: TYPESAFE_API_KEY
egress: private=deny; consent query=allow candidates=allow facts=deny conversation=deny; deny_sources: none; fallback: none
budget: $0.0002 of $1.00 today (remote $0.0000, cap 50%); not covered: S1 on: reranker spend controls (BudgetKind rerank); llm: providers: chat spend controls (BudgetKind chat)
reranker: voyage:rerank-3-lite (enabled, mode balanced); Jev called: no
rerank ready for on ~$0.5377/1k queries (estimate)
evidence on threshold 0.300 (override) ~$0.3873/1k queries (estimate) 24h: 12 decisions, 0.0% errors
WARN: decide.slots.evidence.force_on bypasses the action-precision gate
- Line 1: the default provider (with an alias warning when it is not pinned) and which variable supplied the key.
egress: private-content rule, consent per data class, denied sources and the egress fallback.budget: third-party decide spend today againstdecide.budget.daily_usd, the remote-caller share and its cap (decide.budget.remote_share), and the spend the cap does not cover.reranker: the active search reranker, whether it is enabled, the search mode, and whether Jev is being called.- One line per slot: its readiness, then its threshold and where it came
from (
override, a local calibrationlocal:<id>or a referenceref:<id>), the estimated cost per 1,000 units (receiptswhen measured from the last 24 hours,estimatefrom the pack planner), and 24-hour decisions and error rate.
Readiness values:
| Readiness | Meaning | Next step |
|---|---|---|
off |
The slot is off (or cannot be enabled yet, for example no key). | gbrain decide enable <slot> names what is missing. |
ready for on |
enable would succeed now. |
gbrain decide enable <slot> |
needs calibration |
The slot needs a calibration or qualification first. | A reference calibration, or your own. |
on |
GBrain acts on the slot's decisions. | Nothing. |
on (inactive: <reason>) |
Requested on, running with off behavior. | The printed fix, or troubleshooting. |
gbrain decide status --json carries the same data plus per-slot status:
pending (no receipts yet), active, blocked (every receipt skipped) or
demoted (skipped because the slot is inactive).
Reading doctor
gbrain doctor has one System One check, decide_health. With every slot
off it reports System One is off (every decide slot is off; nothing is sent). Otherwise it summarizes each active slot (a key-aware default reads
triage=on (default: Jev key present), followed by the opt-out command)
and warns about:
- a TypeSafe provider configured without a key;
- an alias (
jev-latest,jev-preview) in use, and decisions that failed on mixed resolved models while an alias rolls out; - slots requested on but inactive, with cause and fix;
- a calibration made for a different model than the one now answering (drift);
- a 24-hour error rate over 5% (with at least 20 receipts);
- an exhausted daily budget;
- a pinned model the provider no longer serves;
- every
force_onbypass and every uncalibrated threshold override; - egress refusals in the last 24 hours (a note, not a warning).
Receipts
Every decision writes one receipt row per question to decision_receipts in
your database: slot, mode, provider, requested and resolved model, the
answer's number, threshold, outcome, reason, latency and token count. Pages,
facts and transcripts are referenced by an HMAC under a per-brain salt that
no config surface prints. No query, prompt, page or transcript text is
stored.
gbrain decide receipts [--slot <slot>] [--since <hours>] [--json] # aggregates only
gbrain decide receipts --slot evidence --what-if-threshold 0.4 # replay a threshold, no provider call
--what-if-threshold works for slots whose decision can be replayed exactly
from receipts (the evidence gate, triage and claim support) and says "not
reproducible" for the others.
Volume: rerank on writes one row per reranked candidate (at most
search.reranker.top_n_in, 30 by default) and the evidence gate one row per
judged candidate (at most 50). A brain running 1,000 searches a day with both
on writes roughly 50,000 to 80,000 rows a day. Rows are kept for
decide.receipts.retention_days (7) and pruned by the dream cycle's purge
phase.
gbrain search "<query>" --explain prints one decide <slot>: ... line per
slot that ran on the query (mode, provider and resolved model, threshold and
outcome counts), and a skipped slot's reason. With every slot off, explain
output is unchanged.
Budget and cost
decide.budget.daily_usd (default $1.00) caps third-party decide spend per
brain per UTC day, summed from a local spend ledger that charges failed and
timed-out requests their estimated tokens. Over the cap, slots take their
fail direction. Remote callers (MCP query and think) may use at most
decide.budget.remote_share of it (default 0.5). The cap is soft in both
directions: buffered ledger rows and concurrent processes can overshoot it
slightly. Two paths sit outside it: the Jev reranker under rerank on uses
the reranker spend controls, and llm: providers use the chat spend
controls. Concurrency limits apply per process.
Estimates at the pinned price, from the pack planner for a typical input:
about $0.54 per 1,000 queries for rerank (30 candidates) and about $0.39 per
1,000 queries for the evidence gate. status switches to measured figures
once receipts exist.
Say to your agent
Check whether my TypeSafe key works without sending anything from my brain.
Show me, on my own brain, what System One would change for "When does Acme Example ship the beta?", without changing anything.
Turn on the System One slots that have a recorded win, and show me what data leaves the machine before you confirm.
Is System One doing anything right now? Show me its status and doctor's System One check.
Why is the evidence gate on but not acting?
Turn System One off everywhere.
Your agent runs gbrain decide probe, gbrain decide probe --query "..."
(showing you the egress line before adding --yes), gbrain decide enable --recommended, gbrain decide status and gbrain doctor, the fix command
from the requested / effective / cause / fix line, and
gbrain decide disable --all. gbrain decide runs only on the brain host;
a thin client refuses it.
Troubleshooting
Every refusal and inactive cause prints the problem, the reason code, the cause, a fix command and a link to a row here.
| Reason | What it means | Recovery |
|---|---|---|
no_provider |
decide.provider is none, so the slot has no provider. |
gbrain decide enable <slot> --provider typesafe:jev-1.13.0 (or --provider llm:<provider:model>). |
no_key |
Neither TYPESAFE_API_KEY nor JEV_TYPESAFE_API_KEY is set in the process or ~/.gbrain/.env. |
export TYPESAFE_API_KEY=... && gbrain decide probe. |
no_calibration |
No local or reference calibration exists for this slot, call site, provider and model. | A reference calibration for your model, or gbrain decide calibrate --slot <slot> --dataset <jsonl>. |
no_qualification |
The calibration has no precision bound yet. | gbrain decide qualify --slot <slot> --dataset <jsonl>. |
pack_shape_mismatch |
The calibration was measured with a different request shape (for example, another slot is now packed into the same request). | Recalibrate: gbrain decide calibrate --slot <slot> --dataset <jsonl>. |
action_precision_low |
The slot's harmful action was not precise enough on the eval half. | Leave it off, calibrate on better data, or bypass on purpose with gbrain config set decide.slots.<slot>.force_on true (doctor lists it). |
insufficient_n |
Too few harmful actions to prove the bound, even if all were right. | Build a larger dataset: gbrain decide dataset --slot <slot> --from <source> <path>. |
policy_changed |
The threshold, margin, floors, question version or request shape changed since qualification. | gbrain decide qualify --slot <slot> --dataset <jsonl>. |
model_drift |
The provider answered with a different model than the calibration's. Calls run with off behavior. | gbrain decide calibrations list --slot <slot>, then adopt a calibration for the new model, or pin the old id. |
egress_private_denied |
The slot sends private content and decide.egress.private is deny. |
gbrain config set decide.egress.private allow, or route the slot to an llm: provider (decide.slots.<slot>.provider) or set decide.egress_fallback. |
egress_class_denied |
The data class has no consent for this provider. | gbrain decide enable <slot> shows what leaves the machine, then writes consent. |
egress_fallback_missing |
Items egress refused have no fallback provider. | gbrain config set decide.egress_fallback llm:<provider:model>, or accept the fail direction for them. |
split_mismatch |
The calibration was built from a different dataset split, or not from the calibrate half only. | gbrain decide calibrate --slot <slot> --dataset <jsonl> on the same dataset file. |
pinned_model_unavailable |
The provider no longer serves the pinned model. Calls take the fail direction. | gbrain config set decide.provider typesafe:<new-id> && gbrain decide calibrations list, then recalibrate or adopt a reference calibration for the new id. |
unpriced_model |
The configured typesafe:<model> id has no shipped tariff and no operator price, so its spend cannot be metered against decide.budget.daily_usd. Nothing was sent. |
Register the price the endpoint bills: gbrain pricing set typesafe:<model> --rate <usd-per-1M-input-tokens> --source <pricing-page-url>, then gbrain decide probe. |
budget_exhausted |
Today's third-party decide spend reached decide.budget.daily_usd. Slots take their fail direction until UTC midnight. |
Wait, or gbrain config set decide.budget.daily_usd <usd>. |
thin_client |
This install is a thin client; gbrain decide runs on the brain host. |
Run gbrain decide on the brain host. |
malformed_response |
The response missed a question or carried an invalid value. The decision took its fail direction. | gbrain decide probe; if it persists, check TypeSafe's status. |
reranker_not_jev |
rerank is on but search.reranker.model is not a TypeSafe model, so it behaves as off. |
gbrain decide enable rerank. |
slot_unavailable |
The slot is not included in this build. | gbrain decide status; upgrade when the slot ships. |
llm_capability |
The llm: route cannot enforce structured output or report its model identity. |
Use a structured-output route: gbrain config set decide.slots.<slot>.provider llm:<provider:model>. |
no_recorded_win |
enable --recommended found no slot with a recorded win and a passing reference calibration for your model. Nothing changed. |
See docs/eval/system-one/; enable a single slot with gbrain decide enable <slot>. |
Receipt skip reasons (error_reason on skipped or error rows) also include
egress, late, timeout, rate_limited, provider_error, mixed_model,
no_embedding, no_entity, missing_provenance, denied_source,
payload_too_large, unpriced_model, cache_hit and no_candidates.
Advanced diagnostics
This section is for diagnosing System One itself. It is not a step toward turning a slot on, and nothing requires it.
shadow mode makes the provider call and writes a receipt, but changes no
ranking, pruning, gating or write:
gbrain decide enable <slot> --shadow # same summary and consent as enable
gbrain decide disable <slot>
- On search paths shadow runs in the background and adds no latency and no
meta. It samples by
decide.slots.<slot>.shadow_sample(the evidence gate and injection signal default to 0.1, the rest to 1.0). gbrain search "<query>" --explainwaits for shadow on that one query and prints itsdecidelines.decide.slots.<slot>.shadow_wait ondoes this for every query, which adds the slot's real latency to every search.- Rerank in shadow beside a non-Jev reranker (Voyage or none) scores the
same candidates with Jev using the TypeSafe key, through the decide egress
consent, and records rank agreement (top-1 match, Kendall tau). Results do
not change. Without a key it is skipped with
no_key. - Shadow receipts hold predictions, not correctness labels, so they cannot produce a calibration. Use them to see traffic, latency, drift and agreement.
- On a search cache hit, shadow makes no call and writes no receipt.
statusshowsshadoworshadow (inactive: <reason>)for these slots, anddecide.provider nonestops shadow along with everything else.
Evals can set slot modes for one process with GBRAIN_DECIDE_SLOTS (for
example triage=on). Only eval commands and gbrain dream --eval-run honor
it, it never bypasses consent, egress or the daily cap, and every receipt
records it.
gbrain dream --eval-run honors it for dream cycles. The eval commands
take the same setting as flags, so matched pairs differ only in the slot
under test:
gbrain eval longmemeval <data.jsonl> --no-trajectory --decide <slot>=<off|on|shadow> [--decide ...]
[--decide-provider <id>] [--decide-calibration <file|ref:<id>>] [--decide-threshold <slot>=<x>]
[--decide-force-on <slot>] [--decide-dataset <jsonl>] [--eval-pool-depth <N>]
gbrain eval brainbench [--suite know-to-ask] --decide recall_needed=on [same --decide-* flags]
gbrain eval retrieval-quality <fixture.jsonl> --json --decide <slot>=<mode> [--decide-provider <id>] [--decide-dataset <jsonl>]
gbrain decide judge-agreement --suite <longmemeval|grounding> --input <file> [--limit N]
[--provider <id>] [--threshold 0.5] [--dry-run] [--json] [--out FILE]
- Flags win over an inherited
GBRAIN_DECIDE_SLOTS; the effective value is set for the run and recorded in its metadata. No slot on or shadow means output identical to a run without the flags. - LongMemEval and BrainBench write what the slot needs into their throwaway
benchmark brains (provider, consent,
decide.egress.private allow, thresholds,force_on, awaited shadow, calibrations).retrieval-qualityruns on your brain and never writes its config: it refuses with the catalogued line when the provider, key or consent is missing. --decide-calibrationtakes the JSONgbrain decide calibrate --slot <slot> --jsonprints (or a reference id). With--decide-dataset, a calibration whosesplit_hashdiffers from that dataset, or that is not calibrate-only, is refused withsplit_mismatch, and LongMemEval runs only the eval half.--decide rerank=onpins the Jev reranker for the run.--eval-pool-depth <N>(N up to 300, LongMemEval only) lifts the per-arm candidate cap for that run and setssearch.reranker.top_n_into N; production depth is unchanged.--decide-force-onbypasses the action-precision gate so an eval can measure a slot that has not qualified; it prints a warning and is recorded.judge-agreementruns Jev beside the existing LLM judge (a--judgeoutput, or grounding labels) and reports Cohen's kappa. It needs no brain, and nothing is substituted at runtime.
Know-to-ask (recall_needed) turn latency: bun scripts/bench-s6-turn-context.ts [--rounds 3] [--delays-ms 120,160,300] [--json] replays every BrainBench
know-to-ask turn through the hook's turn-context path in an in-memory brain,
with S6 off and then on against a fixture transport drawing delays from a
measured latency sample, and reports p50/p95/p99, the added latency per turn,
the outcome mix and the deadline miss rate. It calls no provider.
Row and summary fields: docs/eval-bench.md.
Protocols and verdicts: docs/eval/system-one/.