Garry's Opinionated OpenClaw/Hermes Agent Brain
Evidence delivery (return_unit)
Status: the default is
auto(v0.60.23.0): conversation pages come back whole, every other hit is its unchanged ranked chunk. On LongMemEval-S (500 questions, development data)autoat a 16,000-token budget answered 445 against 312 for chunks (+145 / −12, p = 4e-30) and 457 for whole pages, at about 15,100 reader tokens per question against about 3,500. The preregistered sealed confirmation set (150 new questions) returnedfailat a ceiling: chunks 147,auto149 (+2 / −0), because its chats are short. It showed no benefit and no harm.autoships on the development-data evidence while a harder sealed set is built. The default budget was then raised to 24,000 tokens to cut session trimming (81 of 500 questions were trimmed at 16,000), and a follow-up check measures it. Report: gbrain-evals PR #49 (docs/benchmarks/2026-09-30-evidence-auto-v2.md). Earlier history: whole sessions beat chunks 361/400 against 253/400 while neighbor windows reached only 285–292, and a lexical excerpt selector lost 53/60 → 48/60 (seedocs/eval/ANSWER_PACKET_RESULTS.md).
Search returns ranked chunks. An agent that needs the surrounding
conversation or section has to call get_page for each hit. Evidence delivery
lets search, query, recall and think return the surrounding evidence in
the same call: a window of neighboring chunks, the enclosing section, or the
whole page, packed into a token budget.
With return_unit omitted the unit is auto: hits on conversation pages
(see Conversation detection) come back as the whole
page, every other hit stays the ranked chunk it was. A response with no
conversation hit is byte-identical to earlier releases. return_unit: "chunk"
(or gbrain config set search.return_unit chunk) turns the stage off
entirely.
A budget you pass under auto is a hard cap: everything delivered (titles,
evidence text and every marker in it) fits inside it, on query, search,
recall's results and assemble_evidence. A call that passes no budget gets
exactly what earlier releases returned. See Explicit budgets.
Say to your agent: "Search my brain for what alice-example said about the launch date, and read the whole conversation, not just the snippet."
Say to your agent: "Find every session where we discussed the acme-example renewal and give me the full sessions within about 6,000 tokens."
Say to your agent: "What did we decide about the widget-co launch? Keep the evidence under 8,000 tokens."
Quick start
# CLI
gbrain query "when did we move the launch?" --return-unit page --token-budget 6000
gbrain search "acme-example renewal" --return-unit window --return-window 2
gbrain recall --query "renewal terms" --return-unit section --budget-tokens 4000
// MCP
{ "name": "query", "arguments": { "query": "when did we move the launch?", "return_unit": "page", "token_budget": 6000 } }
Units
return_unit |
What each result's chunk_text holds |
Typical cost |
|---|---|---|
chunk |
The ranked chunk only (the pre-0.60.23 default). | ~300–450 tokens per result |
window |
The hit chunk plus return_window (1–3, default 1) neighbor chunks on each side, same page. Overlapping windows merge. |
~3× chunk per result |
section |
The enclosing markdown section (by ATX heading). On conversation pages: the user→assistant rounds that overlap the hit. No structure → falls back to window. |
varies |
page |
The whole page or session, capped at 60,000 characters and by the budget. | whole page |
auto (default) |
Per hit: page for conversation pages, the unchanged ranked chunk for everything else. Each result's delivered.unit and delivered.reason say which, and why. |
whole sessions, 24,000-token default budget |
Use page for multi-session / temporal questions where the answer depends on
the whole conversation. Use window when you only need local context.
With return_unit: page, query sizes its hit list to the budget so the
budget fills. Autocut stays off unless you set autocut, and a budget above
about 6,250 tokens raises the row count to one row per 250 tokens, up to 100.
An explicit limit or autocut still wins.
Parameters and config
Per-call params on search, query, recall:
return_unit:chunk|window|section|page|auto. Default from configsearch.return_unit(defaultauto).search.long_page_unit(config only, defaultoff):window|section|pagefor long non-conversation hits under the impliedauto; see Long pages.search.long_page_min_chars(config only, default 20,000): the rendered-body length in characters at which a page counts as long forsearch.long_page_unit.return_window: integer 1–3, default fromsearch.return_window(default 1). Used bywindow(and by thesectionfallback towindow).- Budget:
token_budgetonsearch/query,budget_tokensonrecall. When no budget is given,autousessearch.return_budget_conversation(default 24,000: chat sessions run about 15K tokens, and at 16,000 some long sessions were still trimmed) and the other units usesearch.return_budget_default(default 6,000). Remote callers are clamped tosearch.return_budget_max_remote(default 32,000); the clamp is reported indelivery.budget_clampedanddelivery.fallbacks, never raised per call. A trusted brain that needs more over stdio MCP (an eval cell's hermetic brain, for example) raises the ceiling once withgbrain config set search.return_budget_max_remote 200000and asserts thatdelivery.budget_clampedis absent; trusted local CLI calls are never clamped. - An explicit budget under
auto(return_unit: "auto", orautofrom config onsearch) is a hard cap, packed bysearch.auto_packing(see Explicit budgets); it must be at least 32 tokens. - Legacy budget knobs keep their meaning: with
return_unitomitted,query'stoken_budgetstill prunes chunks (chunk mode), andrecall'sbudget_tokens/budget_policystill pack chunks (facts first), so any of them keeps an impliedautoonchunk. recallwith a unit andbudget_tokenspacks saved facts first (unlessbudget_policyisquery_first). Delivery gets the budget the facts leave, and each delivered block costs what delivery counted (text and title, indelivery.tokenizer), so the facts and blocks together fillbudget_tokensand no delivered block is dropped afterwards.- Page-unit ranking cut (
search.page_rank_cut, defaultwhole_pages). Areturn_unit: "page"call that passes its own budget onsearch,queryorrecalllifts the search mode's chunk-token cut (search.tokenBudget: 4,000 under conservative, none under tokenmax), and delivery walks the ranked pages, costing each at what it would deliver whole (text, title and date header indelivery.tokenizer, within the block char cap). It stops once they fillsearch.page_rank_cut_factor(default 1.5) × the budget the pages share; the page that crosses it stays only if its matching span still fits what the whole pages before it leave, and later pages are dropped asrank_cut(so a short page ranked after one that cannot be delivered even in part is not reached). Without the cut, a mode cut under-filled the budget on small pages, and tokenmax handed delivery more pages than it could deliver whole, so each arrived as a sliver.delivery.page_rank_cutreportsmode,factor,caller_budget,target,applied_cost(the kept pages' whole cost),candidatesandkept. A page call without a budget and every other unit are unchanged.gbrain config set search.page_rank_cut offrestores the old path. Evidence: on 72 BEAM conversations the cut at 1.5 was non-inferior to the cut off (−0.25 points, lower bound −1.00 against a −3 margin) with delivered context at budget. Those conversations are regression evidence, not a held-out test, and 1.5 was picked under a rule amended after the dev results (gbrain-evals #126, wave 2 results).
Think reads think.return_unit (default auto) and never
search.return_unit, so changing search's default does not change think.
Under auto, think renders conversation pages whole and keeps its usual
excerpts for every other page.
Query budgets (GBRA-205)
query's token_budget without a return_unit keeps its chunk-mode
meaning by default. gbrain config set search.query_budget_unit auto makes
it the same hard cap search uses: conversations come back whole or cut,
packed by search.auto_packing. A budget below 32 is then refused.
search.evidence_titles (default off) appends each page block's title to
its date header line when date headers are on.
Date headers
With search.evidence_date_header on (default off), every delivered block,
including auto's unchanged chunks, starts with one fixed line, and
delivery.date_header is true:
[observed 2026-03-05]
observed is when the page's text was written or said: its filename or slug
date, frontmatter date, published or a created key, in effective-date
precedence with event_date removed. An event date (when something happened)
and the row's own timestamps are never shown as observed; a page without an
observation date reads [observed unknown]. A date stored at midnight UTC
renders as written, any other instant in brain.timezone. The header line
and its newline are part of chunk_text: they count in delivered.tokens,
tokens_delivered and the budget, match_spans offsets include them, and
evidenceFingerprint hashes them; under an explicit auto budget the cap pays for
them first and a cut keeps the header line whole. recall facts gain
date_header: "[observed 2026-02-10; valid 2026-03-01 to unknown]". A fact's
observed date is the observation date of the page it came from
(source_markdown_slug, such as the conversation it was extracted from), read
under the caller's own page access, and it reads unknown for a fact kept only
in its entity page's facts fence or taken from a page the caller may not read.
If that read fails, the header reads unknown and the response reports the
degraded stage fact_observed_date_unavailable (recall:
facts_degraded.reason). The facts block, the temporal fact reserve and the
facts arm date their fact rows the same way. In the facts block, when the
question names one date (questionDate, the shared temporal grammar), a fact
said after it ends its header ; told after DATE and a fact whose observed
is unknown ends it ; learn date unknown:
[observed 2026-06-30; valid 2026-02-15 to unknown; told after 2026-04-01].
On a history cue (a word such as before, earlier or previously, or a time the
question names that has already passed) the block also takes the named
entity's ended facts, superseded or closed by a past valid_until, each with
its window; a forgotten or withdrawn fact never appears. A fact in a pending
supersede proposal ends with (contested by #<id>) when the caller can read
the other fact, as recall labels it; if that lookup fails the rows carry no
label and the response reports the degraded stage contested_unavailable. valid
starts at the fact's valid_from: remember sets it from its valid_from
parameter (when the fact was said or became true). A valid_from that only
records the write time (within a minute of created_at) reads unknown, so a
header never presents when a fact was written as when it became true. An open
validity end reads unknown. When a conversation fact carries a slot
(location, employer or role, tagged by a second small call after
extraction on facts about a person whose page the extractor named exactly),
the facts block and the temporal fact reserve work out its end
at read time: the start of the next different value for the same person, when
that value came from the same conversation or its fact says the value changed
(moved, joined, left and similar words). Otherwise both values stay open and
the end reads unknown. Nothing is written. A question that asks for history
(a history word, "oldest first", "held", or the slot named in the plural, such
as job titles, employers or cities) about one slot of one named person or
company, and not for its current value ("now", "currently", "these days"),
also gets every value that entity has had in that slot that the caller may
read, oldest first, each with its own window, inside the block's share and
row count. The entity is the page the question names or, when no page
matches, the one name tag (a name of two or more words saved with no page)
whose words the question holds in order; two candidates match none. A page
written later at people/<tag> takes over the tag's facts on this read. If
that read fails the block keeps its other rows and the response reports the
degraded stage facts_history_unavailable. The setting
applies to search, query, recall, think and assemble_evidence.
Tail trim
With search.evidence_tail_trim on (default off), an auto delivery for
search or query drops whole-conversation blocks past the top 3 whose
search score is under half of rank one's. A block that holds the query's terms
nearly as fully as rank one (at least 80% of rank one's share of them) is kept:
a low-scoring session can restate the asked fact with an earlier value, which
an update question needs. Ranked chunks, saved facts and long pages are never
dropped, and a delivery without a usable score on every row is unchanged.
delivery.tail_trim reports { dropped, kept_by_query_terms } and
dropped_reasons.tail_trim counts the dropped blocks. On LongMemEval-S
(development evidence), the trim cut delivered tokens by about 36% on the
questions it touched, with no measurable loss on three reader models
(gbrain-evals#185). The
library assembleEvidenceForHits runs it when the call passes query and
each hit's score.
Config keys: search.return_unit, search.return_window,
search.return_budget_default, search.return_budget_conversation,
search.return_budget_max_remote, search.evidence_date_header, search.evidence_titles, search.evidence_tail_trim, search.auto_packing, search.query_budget_unit,
search.page_rank_cut, search.page_rank_cut_factor, think.return_unit. Kill switch:
gbrain config set search.return_unit chunk and
gbrain config set think.return_unit chunk (or pass return_unit: "chunk"
per call).
Conversation detection
auto decides per hit from fields every search row already carries, with no
extra query and no model call:
- Page type is one of
conversation(whatgbrain transcripts ingestand the chat connectors write),transcript,chat,meeting,slack,slack-dm-day,slack-thread,imessageorimessage-daily(case-insensitive). Reason:conversation_type. - Otherwise the slug starts with
chat/(chat imports and the LongMemEval adapter) orconversations/(the transcripts and connectors ingest directory). Reason:conversation_slug. - Anything else keeps its ranked chunk unchanged. Reason:
not_conversation.
Pages the transcripts and connectors paths write carry both signals (type
conversation under conversations/), so their transcript_import
frontmatter is not read separately. Detection never looks at body text, so a
curated note that happens to quote a dialogue stays on the chunk path.
With no budget passed (the 24,000-token default), conversation hits share the
budget in rank order, after the unchanged chunks are paid for. Each
conversation page first reserves its matching span, then the pages grow toward
complete in rank order, so a lower-ranked session still keeps the part that
matched. A conversation whose matching span no longer fits keeps its ranked
chunks unchanged (reason conversation_over_budget), so auto without an
explicit budget never returns less than chunk would, and budget_used
exceeds budget_tokens only by such unchanged chunks. An explicit budget
changes this; see the next section.
Long pages (search.long_page_unit)
Off by default. gbrain config set search.long_page_unit section (or window,
page; off turns it back off) makes search and query deliver a long
non-conversation hit in that unit under the implied auto, the way auto
already delivers conversations whole. Every other hit keeps its ranked chunk
unchanged. The value is a delivery unit from the table above and the unit
algorithms are the same; nothing selects passages by term overlap, so the
delivered unit is always the one around the ranked hit.
Which unit applies. One table decides, per call and hit:
| # | Source | When it applies | Unit |
|---|---|---|---|
| 1 | return_unit on the call |
always (auto included: an explicit auto keeps every non-conversation chunk) |
that unit |
| 2 | search.return_unit set to anything but auto |
return_unit omitted |
that unit, every hit |
| 3 | search.long_page_unit (not off) |
return_unit omitted, search.return_unit unset or auto, no explicit token_budget, and the hit is a long non-conversation page |
that unit (delivered.reason: "long_page") |
| 4 | implied auto |
everything else | conversations whole, other hits their ranked chunk |
The policy is resolved at the search/query caller and passed to the
assembler, so recall, think (think.return_unit) and assemble_evidence
never read the key and stay byte-identical with it on. snippet_chars does
not turn it off: a row widened by it (delivered: {unit, reason: "long_page"})
is exempt from snippet_chars and comes back whole, because a head cut would
drop the tail the unit was widened to reach. The widened row still sits inside
search.return_budget_conversation and the long-page page and input-byte
limits below, and snippet_chars still cuts every other row, ranked chunks
included (those rows report delivered: {truncated: true}). The
delivered.unit and reason on the row are what tell the reader why it is
longer than snippet_chars. An explicit token_budget keeps it off because the cap (next section) keeps
its own rules, and query's bare token_budget is chunk-mode budgeting anyway.
The subagent default snippet cap already keeps the implied auto on chunk.
What is long. A page whose rendered body (compiled truth plus timeline;
compiled truth only under detail: "low") holds at least
search.long_page_min_chars characters (default 20,000;
gbrain config set refuses anything but a positive whole number, and an
unusable stored value reads as the default). The size preflight compares the
stored body's character count; delivery confirms the threshold on the rendered
text (pageEvidenceText), and a page under it keeps its ranked chunk with no
fallback code. Conversation pages
(see Conversation detection) and saved-fact rows are
never long pages.
Limits. One size preflight query reads the character and byte counts of the hit pages
under the caller's read scope; it never reads a body. Then, in rank order, at
most 5 long pages (LONG_PAGE_MAX_PAGES) holding at most 1,000,000
stored-body bytes together (LONG_PAGE_MAX_INPUT_BYTES) are fetched in one
bounded batched call of their own, so they can neither slow nor fail the
conversation fetch. A page that would cross a limit is skipped whole, never
sliced: bodies are sanitized whole before any cut. Preflight plus fetch share
a cooperative 2,000 ms deadline (LONG_PAGE_DEADLINE_MS). A long page that
cannot be delivered in its unit keeps its ranked chunk, byte-identical to the
off path, with delivered.reason: "long_page_chunk" and a fallback code
saying why (below). A preflight that fails or misses the deadline leaves the
call on the off path.
Budget. Long pages are counted in the same delivery budget as
conversations (search.return_budget_conversation, default 24,000, clamped for
remote callers): unchanged chunks are paid for first, then conversations and
long pages reserve their matching span and grow in rank order. A long page
whose matching span no longer fits keeps its ranked chunk
(long_page_chunk, fallback long_page_over_budget), so the key never returns
less than chunk would.
Response. A long-page block is an ordinary delivered row (delivered.unit
is the unit that ran; a section with no structure falls back to window
with no_section_structure). Lean rows (the remote default) keep
delivered: { unit, reason } on both long-page reasons, plus truncated: true
when cut; every other lean row keeps only { truncated: true }. A response
with no long page and no conversation is byte-identical to the key off.
Explicit budgets (the cap)
When the caller passes a budget (token_budget on query, search and
assemble_evidence, budget_tokens on recall) and the unit is auto, the
budget is a hard cap on the delivered evidence: the recount of every result's
title plus chunk_text (the evidence, its omission lines, cut markers and
snippet markers) never exceeds it, except that a quoted conversation row at
rank one is kept when its quote fence alone exceeds a very small budget (see
Response shape). JSON fields outside those two (delivered,
spans, scores, the delivery meta) are not counted. The four operations share
one rule:
- Rank one first. The best-ranked hit, note or conversation, is reserved
first. If it alone exceeds the budget it is cut at a piece boundary (a
line, or a 400-character run of a long line) and ends with the cut marker
\n\n[…]; it is never dropped. - Notes get a prefix. The other non-conversation chunks, in rank order,
are kept while they fit; the first that does not fit and every one after
it are dropped (
budget_note). A lower-ranked note never crowds out a leading conversation. - No spill. A conversation that does not fit is dropped (
budget_floor, orbreadth_capunderbreadth_capped), never appended outside the budget as chunks. - The cap holds at the final boundary. Secret redaction and an explicit
snippet_charsrun before the last recount. A snippet's recovery marker is paid from the row's own allocation (the body shrinks to make room, or the marker is left out with fallbacksnippet_marker_omittedwhen even it does not fit). A row that would still cross the budget is cut with the marker, or dropped asbudget_recount.budget_usedis that recount.
How conversations share what is left is search.auto_packing:
| Value | Conversations |
|---|---|
cap_only (default) |
Every conversation's matching span first, in rank order, then pages grow toward complete in rank order: the no-budget order, with the four rules above. |
breadth_capped |
Keeps the longest rank-order prefix of conversations whose title, matching span and target window (the window unit's neighbor chunks at return_window) all fit; the rest are dropped as breadth_cap. What is left grows those pages toward complete, in rank order. |
depth_first |
Takes conversations in rank order, each whole if it fits what is left, else as much around its matching span as fits; one whose matching span no longer fits is skipped, and later ones are still tried. |
off |
The no-budget behavior, even with an explicit budget (unchanged chunks paid first, conversations that do not fit spill as chunks, no minimum). |
gbrain config set search.auto_packing <value> refuses any other value.
delivery.auto_packing names the packing that ran; it is present only when
the cap engaged. The packing reads nothing but the plan, so think (which
passes no budget) and every call without a budget are byte-identical whatever
it is set to.
The smallest explicit auto budget is 32 tokens (room for a cut marker, a
shortened title and a non-empty body). A smaller budget fails with
invalid_params naming the minimum, and so does a zero, negative or
non-finite one when the call passes return_unit: "auto" (with the unit
omitted such a budget still means no budget, as before). Above the minimum, a
non-empty, readable hit list always returns non-empty evidence. A remote
budget is clamped first (search.return_budget_max_remote), and the cap
applies to the clamped value.
query's token_budget without return_unit still selects legacy chunk
budgeting (and recall's budget_tokens / budget_policy legacy packing),
so a bare budget does not engage the cap.
Precedence with snippet_chars
- An explicit
snippet_charswins: delivered blocks are capped at that many characters (spans are clipped,delivered.truncatedbecomes true andsnippet_capis reported). The one exemption is a row widened bysearch.long_page_unit(delivered.reason: "long_page"): it comes back whole, withinsearch.return_budget_conversationand the long-page limits. - Then an explicit
return_unit: the subagent default snippet cap is skipped for its blocks. - Then the subagent default snippet cap (
agent.search_snippet_chars, 300): when it applies, neither the impliedautonor a config-levelsearch.return_unitexpands. - Then
search.return_unitfrom config, elseauto(withsearch.long_page_unitfor long non-conversation hits, whose widened rows are exempt from an explicitsnippet_chars; see rule 1).
Response shape (additive)
When a non-chunk unit is applied, each result's existing chunk_text
carries the delivered evidence (no duplicated body field), and each result
gains delivered. An implied auto with no conversation hit is not applied,
so those responses carry neither delivered nor delivery.
"delivered": {
"unit": "page", // applied unit for this block: window | section | page | chunk (fallback)
"chunk_ids": [812, 815], // every ranked hit merged into this block, rank order (first = the result's own chunk_id)
"match_spans": [ // where each hit chunk sits in chunk_text
{ "chunk_id": 812, "start": 0, "end": 1840 },
{ "chunk_id": 815, "start": 5210, "end": 6933 }
],
"tokens": 2311, // tokens of chunk_text (delivery.tokenizer)
"truncated": false, // true when the unit was cut (budget, 60,000-char cap, fetch radius, snippet cap)
"revision": "3f0c…", // pages.knowledge_revision the text was read from
"unmapped_chunk_ids": [], // hits whose chunk is no longer in the current revision (present only when non-empty)
"fallback_reason": "fetch_failed", // present only when the block fell back to the hit chunk text
"reason": "conversation_type" // auto only: conversation_type | conversation_slug | not_conversation | conversation_over_budget | saved_fact | long_page | long_page_chunk
}
Under auto, a not_conversation or conversation_over_budget result is the
ranked row unchanged (same chunk_text, including a code chunk's header line)
with delivered: { unit: "chunk", chunk_ids: [its chunk_id], match_spans: [the whole text], tokens, truncated: false, reason }. Those rows are not grouped
by page. gbrain search --explain prints each result's unit and reason
(evidence: page (conversation_type)).
match_spans are UTF-16 code-unit offsets (JavaScript string indices) into
the returned chunk_text, computed after every text transformation (sanitizing,
cuts, omission lines and secret redaction). The text carries no inline markers.
A hit whose chunk cannot be located is listed in unmapped_chunk_ids instead.
A row of third-party text is returned as a quoted excerpt (#7600, #8042,
search/transcript-quote.ts): a page whose type holds someone else's words
(conversation, meeting, slack, slack-dm-day, slack-thread,
email, email-digest, imessage, imessage-daily, transcript, chat)
or a fact row taken from one (marker fact <id>): facts.source
cli:extract-conversation-facts…, or a fact whose source_markdown_slug,
derivation_inputs or backstop source_session page (sync:<slug>,
put_page:<slug>) is such a page (the facts backstop's facts).
Tool-call blocks become a one-line summary, then a marker line and a code
fence wrap the text. assemble_evidence, search and query quote these
rows for every caller; recall quotes its results and facts for remote
callers, and think's prompt quotes them on every run. A remote (MCP)
reader also gets a row below the owner's trust tier (agent-written, tool
data, external or unverified origin; GST-687) quoted the same way, by its
stored tier; only third-party types get tool calls summarized. Its
match_spans index that returned text (a span inside a summarized block
covers the summary), and its tokens, the meta tokens_delivered and
budget_used and evidenceFingerprint count or hash the fenced text. An
explicit snippet_chars caps the text inside the fence, so the row can run
longer than the cap by the marker and fence lines. Under auto an explicit
budget pays for the fence, except that a rank-one row is kept when the fence
alone exceeds a very small budget; budgets under other units do not count it.
With date_header, the header stays the first line of the row, ahead of the marker and the fence.
One result is returned per expanded page, at the page's best rank. chunk_id,
chunk_index, score and the other ranking fields stay those of the page's
best-ranked hit (anchor provenance).
Response meta (_meta.retrieval.delivery over MCP; top-level delivery on
recall):
"delivery": {
"requested_unit": "auto",
"applied_unit": "auto", // "chunk" when the stage could not run at all
"return_window": 1,
"budget_tokens": 6000,
"budget_used": 5874, // title + chunk_text tokens of every delivered block (≤ budget_tokens)
"tokens_delivered": 5790, // Σ delivered.tokens
"tokenizer": "cl100k", // "heuristic" when the encoder is unavailable
"coordinates": "utf16",
"blocks": 4,
"dropped": 1, // hits/pages not delivered
"dropped_reasons": { "budget_floor": 1 },
"fallbacks": ["budget_clamped"], // distinct non-fatal problem codes, never silent
"budget_clamped": { "requested": 50000, "max": 32000 },
"date_header": true, // only when search.evidence_date_header is on
"tail_trim": { "dropped": 1, "kept_by_query_terms": 0 }, // only when search.evidence_tail_trim ran
"auto_packing": "cap_only" // explicit auto budgets only: the packing that ran
}
recall keeps its frozen v1 fields (chunk, evidence, char/4 packing via
budget_tokens); with a non-chunk unit its results[].chunk carries the
delivered text and each result gains delivered.
Fallback and drop codes
| Code | Meaning | What the caller gets |
|---|---|---|
fetch_failed / fetch_timeout |
The neighbor fetch errored or exceeded 5 s. | The hit chunk (from this request's live retrieval), fallback_reason set. |
unsealed_page |
The page's chunks predate the protected-body index (gbrain repair safe-chunks). |
The hit chunk, fallback_reason set. |
row_limit |
The request hit the budget-derived row cap before this page's rows. | The hit chunk, fallback_reason set. |
no_section_structure |
section found no headings or speaker turns. |
A window block (delivered.unit: "window"). |
no_text_chunks / anchor_not_located |
No hit could be placed in the page text: no text chunk was in reach and the hit text itself was not found, or none of the located chunks overlap a hit. | The hit chunk (a code chunk without its synthesized header line), fallback_reason set. |
page_missing |
A hit carried no page id (cannot be re-authorized by id). | The hit chunk (live hits only), fallback_reason set. |
segment_read_failed |
A page stored in segments could not be read around its hits (its stored projection metadata was unusable, or a segment read failed). | The hit chunk (live hits only; cached hits are dropped as not_readable), fallback_reason set. |
redaction_unmapped |
Secret redaction changed a block. | Redacted block; its spans move to unmapped_chunk_ids. |
image_query_unsupported |
query with image: image hits are never expanded. |
Plain image results; meta says so. |
snippet_cap |
An explicit snippet_chars cut a block. |
Capped block, truncated: true. |
budget_clamped |
A remote budget above the max was clamped. | Clamped budget. |
tokenizer_heuristic |
cl100k unavailable; char/4 heuristic used. | Counts from the heuristic. |
date_header_unavailable |
Date headers are on but the page dates could not be read. | Every header reads [observed unknown]. |
long_page_pages / long_page_bytes |
search.long_page_unit: the long page came after 5 long pages, or would cross 1,000,000 stored-body bytes. |
Its ranked chunk (reason: long_page_chunk). |
long_page_over_budget |
search.long_page_unit: the long page's matching span no longer fit the budget. |
Its ranked chunk (reason: long_page_chunk). |
long_page_deadline / long_page_fetch_failed / long_page_preflight_failed |
search.long_page_unit: the size preflight or the long-page fetch missed the 2,000 ms deadline or failed. |
Its ranked chunk (reason: long_page_chunk); a failed preflight leaves the call on the off path. |
drop not_readable |
The page is no longer readable by this caller (deleted, private, grant revoked, quarantined, archived source, source outside scope). | Result removed. Never falls back to cached text. |
snippet_marker_omitted |
Under an explicit auto budget, a row's allocation could not hold the snippet recovery marker. |
Capped block without the marker, truncated: true. |
drop budget_floor |
Not even the block's matching span fits the remaining budget. | Result removed (rank one is instead cut to fit). Under auto without an explicit budget nothing is dropped for budget: the conversation keeps its ranked chunks. |
drop budget_note |
Explicit auto budget: a non-conversation chunk after rank one did not fit, or came after one that did not. |
Result removed. |
drop breadth_cap |
breadth_capped: the conversation is past the prefix whose target windows fit. |
Result removed. |
drop budget_recount |
Explicit auto budget: the final recount (after redaction and snippet markers) left no room for the row's title and a body. |
Result removed. |
Errors
An unknown return_unit or an out-of-range return_window fails with
invalid_params, naming the allowed values and an example call, e.g.
return_window must be an integer from 1 to 3 (got 7). Example: {"query": "launch date", "return_unit": "window", "return_window": 2}
An explicit auto budget below 32 tokens (or a zero, negative or non-finite
one passed with return_unit: "auto") fails with invalid_params, e.g.
token_budget must be at least 32 tokens under return_unit auto (got 10): an explicit budget is a hard cap, and a smaller one cannot hold a title, a cut marker and any evidence.
A thin client talking to an older server that ignores return_unit prints one
warning naming the minimum server version.
Guarantees
- Authorization. Every delivered block is re-read under the caller's
current read scope (source scope,
visibility: private, deleted, quarantined, archived sources, current text projection) in one batched query keyed bypage_id, never by slug. A page that no longer passes is dropped. - Protected content. Evidence text is cut from the page's stored body,
sanitized WHOLE before any slicing with the same strict boundary the chunker
uses (Takes fences removed, only world and not-withdrawn Facts rows kept,
malformed or unterminated protected tails dropped, materialized markers
stripped),
compiled_truthandtimelineeach sanitized whole, then run through the credential-safe projection the chunkers also cut from: every private-key span (complete, or cut off at itsBEGINorENDline) becomes<REDACTED:private_key_pem>followed by as many newlines as the span held, so line positions and chunk anchors stay aligned and no key material is delivered. This applies to every caller, including trusted local ones. Chunks only anchor the hits in that text, and the page must hold a sealed chunk index. Delivered text never contains anythingget_pagewould not return to the same caller.detail: "low"never adds timeline text. - Frontmatter is not evidence. Page frontmatter (YAML metadata) is never
part of delivered text;
pagetext is the sanitized body only. - Non-mutation. The stage returns new result objects and never mutates or caches expanded text.
- Bounded work. One engine query per request (with
search.long_page_uniton and a long page among the hits: plus one size preflight and one bounded long-page fetch, see Long pages). It reads each hit page's body once (bounded by the import size cap) plus the chunks within ±return_windowof each hit; each block ≤ 60,000 characters (under the 64 KiB output-redaction field limit).
Algorithms (normative; E1 depends on them)
- Group. Hits are grouped by
page_idin rank order; the block takes the page's best rank. Fenced-code chunks (duplicates of page text) and image chunks never contribute neighbor text. - Fetch. One query returns each page's authorization, seal, stored body
and the chunks within ±
return_windowof each hit (at most 1,024 rows). - Page text and anchors. The page text is
project(sanitize(compiled_truth)), plus\n\n<!-- timeline -->\n\n+project(sanitize(timeline))when the timeline is non-empty after sanitizing anddetailis notlow(the joinserializeMarkdownwrites);projectiscredentialSafeProjection(src/core/credential-projection.ts), the function the markdown and code chunkers apply before splitting, so chunks and page text agree on every redacted key. Each fetched chunk is located in that text inchunk_indexorder: exact match first, then a whitespace-insensitive match (the chunker trims chunks and folds some whitespace-only runs, so chunk text is not always verbatim). A fenced-code hit is placed by its code without the code chunker's synthesized[Lang] fence.ts:N-M symbolheader line (itschunk_indexfollows every prose chunk, so it carries no position; its window grows from the prose chunk holding the fence, when fetched). Fallback text for such a hit omits the header too, so delivered text is always page text. Overlapping chunks therefore never duplicate text:pageevidence with an unlimited budget is byte-identical to the page text (trailing whitespace trimmed). Non-contiguous selections join with the omission line\n\n[…]\n\n. - Units.
section: the nearest preceding ATX heading (outside fenced code) through the next heading of the same or higher level; unioned across hits. Conversation pages (≥ 4 speaker-turn lines such as**user:**/**assistant:**,User:,Speaker 2:, with ≥ 2 distinct labels and ≥ 3 label changes; pagetypeis ignored) use rounds: a round starts at eachuser/humanturn (or the first label seen).auto: per hit, a conversation page (by type or slug, see Conversation detection) →page; anything else → its ranked chunk, unchanged and unbudgeted by this stage beyond its cost. - Pieces. The unit text is split into lines; lines over 400 characters split at whitespace. Token counts are the sum of per-piece cl100k counts (plus the omission line and the title), so the count is deterministic and CJK-correct.
- Allocate. Budget
Bcovers title +chunk_textof every block. Reserve: walk blocks by rank; each block's floor is its title plus the pieces covering its best hit; a block whose floor does not fit is dropped (budget_floor), later smaller blocks may still fit; if rank one alone exceedsBit is cut to fit (truncated). Enrich: walk kept blocks by rank; add pieces in priority order (other hits' pieces by hit rank, then by distance to the nearest hit piece, earlier position first on ties) until the unit is complete or the budget is spent. Selected pieces are emitted in document order; gaps become the omission line. The 60,000-character cap applies the same selection. Under an explicitautobudget the order is Explicit budgets: rank one, the note prefix, then the packing's conversation rule;breadth_cappedprices each conversation as title + matching span + itswindowcandidates atreturn_window(pieces in priority order, omission lines counted) and keeps the longest prefix that fits. - Redact. Blocks pass through the same secret redaction as every search response before spans and tokens are computed.
Latency (added by the stage)
bun scripts/bench-evidence-delivery.ts --pages 10000 --iterations 200 [--postgres <url>]
builds a synthetic brain (60% curated notes of 3–12 chunks, 30% conversation
sessions of 6–24 chunks, 5% 120-chunk pages, 5% CJK pages; sealed and
projection-current) and times deliverEvidence on ranked lists of 5 hits over
distinct random pages with a 6,000-token budget. Measured 2026-09-30 on a
4-vCPU / 15 GB cloud VM, Bun 1.3.14; PGLite in-memory; Postgres 16 + pgvector
in local Docker. Milliseconds.
| Engine | Unit | Cold | Warm p50 | Warm p95 | Large-page p95 | CJK p95 | 8 concurrent p95 | Rows / KB read per request |
|---|---|---|---|---|---|---|---|---|
| PGLite | window | 86.0 | 8.4 | 10.4 | 12.1 | 4.8 | 67.5 | 13.8 / 93.1 |
| PGLite | section | 8.6 | 7.8 | 9.6 | 14.9 | 4.8 | 66.0 | 13.6 / 87.6 |
| PGLite | page | 14.8 | 14.7 | 16.0 | 27.9 | 5.7 | 113.2 | 13.8 / 87.8 |
| PGLite | auto | 14.8 | 13.4 | 17.2 | 15.2 | 6.7 | 112.0 | 13.7 / 83.6 |
| Postgres | window | 176.7 | 8.3 | 11.8 | 12.8 | 5.3 | 64.2 | 13.8 / 93.1 |
| Postgres | section | 8.5 | 7.8 | 10.8 | 18.6 | 10.5 | 57.6 | 13.6 / 87.6 |
| Postgres | page | 17.0 | 15.5 | 22.6 | 26.6 | 7.3 | 108.7 | 13.8 / 87.8 |
| Postgres | auto | 15.4 | 13.3 | 16.5 | 14.7 | 5.6 | 104.8 | 13.7 / 83.6 |
Every unit stays under the 50 ms warm p95 target on the 10K-page brain. Every
request made exactly one engine call (no N+1); it reads the hit chunks and
each hit page's body once. The first call in a process pays a one-time cl100k
encoder load and query planning (the "cold" window row). Tails are noisy on a
shared VM: an earlier PGLite run with another process busy measured 56.5 ms
large-page p95 for page and 34.8 ms warm p95 for auto. Under 8
concurrent requests each request waits for the others' JavaScript work
(sanitizing, chunk location and token counting run on the single event loop), so per-request
p95 grows to about 8 × the warm cost while throughput stays the same.
Frozen-candidate interface (gbrain-evals, E1/E3 parity)
Evaluations must measure the code that ships. Two entry points produce, for an
ordered hit list, exactly the evidence the query op would return:
Library (trusted local, in-process)
import { assembleEvidenceForHits, evidenceFingerprint } from 'gbrain/search/evidence-delivery';
const out = await assembleEvidenceForHits(engine, {
hits: [ { source_id: 'default', slug: 'chat/session-0412', chunk_id: 8812 }, /* rank order */ ],
return_unit: 'page', // chunk | window | section | page | auto (the product default)
return_window: 1, // optional
budget_tokens: 6000, // optional; same default/clamp rules as query (explicit: the cap under auto)
detail: 'medium', // optional, as query
caller: { remote: false }, // optional; { remote: true, sourceIds: [...] } emulates a remote caller
auto_packing: 'breadth_capped', // optional, library only: wins over search.auto_packing for this call
});
// out.results — the redacted result array (JSON-serializable), same objects the query op returns
// for these hits: { slug, source_id, page_id, title, type, chunk_id, chunk_index,
// chunk_source, chunk_text, effective_date, effective_date_source, delivered, ... }
// out.delivery — the delivery meta block
// out.unresolved — hits that could not be resolved in the caller's scope (dropped)
const fp = evidenceFingerprint(out.results); // sha256 hex
Each result carries the page's effective_date (YYYY-MM-DD) and
effective_date_source exactly as the live query row does, null for a
page without a date, so a frozen delivery hands a reader the same dates.
auto_packing exists only on the library call (never an MCP parameter), so an
evaluation can compare packings on one frozen hit list without switching the
brain's config between calls.
chunk_id: 0 addresses the page's first chunk (the synthetic rows exact-slug
and alias hits carry). Hits outside the caller's scope, deleted pages and
unknown chunk ids are dropped and listed in unresolved (by input index).
Op assemble_evidence (any transport: local CLI, MCP stdio, HTTP)
Read scope. Params: hits (array of { source_id, slug, chunk_id }, rank
order, max 50), return_unit (default page; pass auto to measure the product default), return_window, token_budget,
detail. Returns { results, delivery, unresolved } with the same content as
the library call for that caller. Remote callers get the same filtering as
query (private pages hidden, sealed pages only, grants enforced).
Fingerprint
evidenceFingerprint(results) is the SHA-256 (hex) of
JSON.stringify(results.map(r => [r.source_id ?? 'default', r.slug, r.chunk_text, r.delivered?.unit ?? 'chunk', r.delivered?.chunk_ids ?? [r.chunk_id]])).
It is identical for the query op's results and for assemble_evidence /
assembleEvidenceForHits given the same ordered hits, unit, window, budget and
caller class, on both engines. test/e2e/evidence-delivery-parity.test.ts pins
this.
Parity recipe for E3
- Run
querywithreturn_unit: "chunk"and notoken_budgetto get the ranked hits (or use the frozen list). With a non-chunkunit,token_budgetbudgets the delivered evidence instead of pruning chunks, so the ranked list the stage sees equals the chunk-mode list without a budget. - Run
assemble_evidencewith those hits and the policy, andquerywith the same policy and budget. - Fingerprints must match; any difference means the product path does not deliver the evidence the experiment assumed.
For the default, compare query with return_unit omitted (and no
token_budget, which would keep the legacy chunk budget) against
assemble_evidence with return_unit: "auto". When no hit is a conversation
the default returns plain rows; their fingerprint equals the auto one.
Always pass expand: false to query for E3. query otherwise runs LLM
multi-query expansion by default, which can change the ranked list from run to
run (retrieval drift, not a delivery difference). assemble_evidence does no
retrieval at all, so it is deterministic for a given hit list, page revision,
unit, window and budget.