Brain Auto-Routing

Most things that reach BlackOps without a brain_id — a capture from the extension, a quick idea in the admin inbox, a note written over MCP with no brain named — used to stay unassigned until someone picked a brain by hand. Brain auto-routing asks Jev (TypeSafe's System One model) which brain an item belongs to, the same way Brain Watches already score content against keywords, just for anything arriving unrouted rather than a monitored feed.

Off by default

Auto-routing is a per-site setting, off until you turn it on: brain_auto_routing_enabled in Settings → Brain Auto-Routing. A site with it off behaves exactly as before — nothing changes by this feature shipping. Turn it on only after running the replay calibration script (below) and seeing Auto-band precision at or above 90% for your own brains; the setting exists precisely so a site can wait for that before anything routes automatically.

An explicit brain never goes through any of this — passing brain_id (or a brain name to post_brain_ingest) always wins, with no Jev call.

What decides where an item lands

1. Code shortcuts, no Jev call. A single brain on the site gets everything. An exact match between a typed hint ("for the lawn brain") and a brain's name or alias routes there. A URL domain that has already landed in one brain three or more times, with no later reroute, routes there too.
2. One Jev call. Jev sees the item's title, the first ~2,000 characters of content, its URL domain, and picks the best-fitting brain from a routing card per eligible brain (name, description, aliases, recent note titles) — plus whether the item fits any brain at all.
3. A close call gets double-checked. When the top two brains are within 2x of each other, a second Jev call asks directly "does this belong in brain X" for each of the top three, before anything is decided.
4. One of three outcomes:

Band	What happens
Auto	Lands straight in that brain's Triage lane — never straight into the compiled knowledge map. Needs high confidence and a clear margin over the runner-up.
Suggest	Stays wherever it would have landed anyway (the admin inbox, or unassigned from post_notes), with the top 2–3 candidate brains attached so you can route it with one tap instead of searching.
No home	Stays wherever an unrouted item already goes. Unchanged everywhere except opted-in post_notes, where even a No-home verdict now returns its (low-confidence) top candidates, so there is always something to offer rather than a bare dead end.

A brain can opt out of being considered at all (auto_route: off) or accept only Suggest-band mentions, never Auto (suggest_only) — useful for a private or narrow brain (a to-do list, a log) that should never silently receive something it didn't ask for.

A brain marked private is always treated as suggest_only at most: auto-routing can suggest it, but never files into it on its own. Set it to off to keep it out entirely, or make the brain non-private if you want Auto to file into it.

Where it runs today

• Browser extension capture (/api/ext/inbox/capture) and highlights (/api/ext/highlights): an Auto verdict routes the capture straight into that brain's Triage lane.
• Admin quick capture (/api/admin/inbox/capture, idea mode): an Auto verdict skips the inbox entirely and files into the brain's Triage lane; a Suggest verdict still lands in the inbox with chips on the item.
• post_notes (MCP): a site that has opted in gets the full behavior, not just a surfaced suggestion. An Auto verdict files the note straight into that brain's Triage lane the same way an explicit brain_id + triage_state: 'pending' call would — the response carries routing: { band: "auto", filed: true, brain_id, brain_name, probability, verdict_id }. An Auto-filed note is a behavior change worth knowing about even if you only read this page: like every other Triage-lane item it is excluded from list_notes, search and get_recent_notes until promoted — an agent that writes a note on an opted-in site and immediately reads it back may not find it. routing.message on the write response says so explicitly. A Suggest or No-home verdict leaves the note unfiled, same as before, but the response carries needs_brain_choice: a question, up to 3 ranked options (each with a one-line reason pulled from the brain's routing card — no extra Jev call), also entries for "Leave unfiled" and "Create a new brain", and a resolve_with call (patch_notes with the chosen brain_id) that closes the loop — picking the top-ranked option records promoted on the verdict, picking anything else records rerouted. A site that has not opted in behaves exactly as before: the note is saved unfiled and no brain is queried at all. An explicit brain_id, target_id, or override_folder_path always skips this, same as every other surface's brain_id bypass.

Content Monitoring finds are not routed by this feature — a Brain Watch hit already knows which brain it belongs to and always stays there.

One-tap chips in the inbox

An item in the admin inbox that landed in the Suggest band shows small brain-name buttons under its preview. Tapping one routes it exactly like the Quick Fix brain picker does — into that brain's Triage lane, with the inbox item marked routed.

Correcting a pick

Auto-routing never writes straight to a brain's compiled knowledge map — every Auto pick lands in Triage first, so a wrong guess is a dismiss, not a cleanup. From a brain's Triage tab (or dismiss_triage_item / promote_triage_item over MCP), promote it, dismiss it, or move it to the right brain the same way you would any other triage item. Every decision — which brains were considered, what Jev answered, and later whether the item was promoted, dismissed, or moved — is kept in brain_routing_verdicts, so a pattern of corrections is visible rather than silently repeated.

Calibrating before you turn it on

scripts/brain-routing-calibrate.ts is a read-only replay: it samples notes already filed in your brains, hides which brain each came from, asks the same question auto-routing would ask on arrival, and reports top-1 accuracy, Auto-band precision, and the most-confused brain pairs.

tsx scripts/brain-routing-calibrate.ts --site=<your-site-uuid> --sample=10

If a pair of brains keeps getting confused (two near-duplicate names, or descriptions that don't say what the other one is for), the fix is usually a sharper description or alias on one of them — see Brain Ingest for how a brain's identity gets set.

Related

• Brain Triage Lane: where every Auto-band pick lands, and how to promote or dismiss it.
• Brain Watches: the other source of Triage items — monitored content, which auto-routing never touches.
• Brain Ingest: post_brain_ingest, the explicit-brain path this feature sits alongside.