Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.5 KB
Raw Blame

Explaining search results

query (and the CLI gbrain search) explain their own ranking. With explain: true every returned row carries score_details: which retrieval arms found it and at what rank, how fusion scored it, and every boost or demotion applied after fusion. With explain_target the response says what happened to a page you expected but did not get, and what to do next.

Say to your agent:

  • "Why is this page ranked first for my question?"
  • "I know there is a note about the acme-example renewal — why didn't search find it?"
  • "Show me how the search scored these results."

Explain a result list

MCP:

{ "tool": "query", "arguments": { "query": "acme-example renewal terms", "expand": false, "explain": true } }

CLI:

gbrain search "acme-example renewal terms" --explain          # readable breakdown
gbrain search "acme-example renewal terms" --explain --json   # the same score_details per row

Each row's score_details:

Field Meaning
arms One entry per retrieval arm instance that returned the row: vector, vector_variant#N, vector_clause#N, image, keyword, title, relational. rank is 1-based; fusion_rank is the 0-based rank fusion used; contribution = weight / (k + fusion_rank). vote: "page" means the vote counts for the whole page (carried by its lead chunk).
rrf raw (summed votes), normalized (divided by the best row), compiled_truth_boost. state: "not_run" on single-arm paths.
blend The cosine blend: 0.7 × norm_rrf + 0.3 × cosine. not_run without a query embedding.
base_score The score entering the post-fusion boosts.
boosts Every factor that changed this row, by stage: backlink (with its inbound links), salience, recency, chronicle, title, adjacency, cross_source, session_demote, alias_resolved, supersede, exact_match.
rerank Cross-encoder score and rank delta, or not_run.
final The row's score.

A stage the search did not run is reported as not_run or skipped with a reason, never as an invented value.

See where the time went

Every search and query response carries its stage timings in _meta.retrieval.timings (MCP and thin clients; never in the result text), and gbrain search --explain / gbrain query --explain print them as the first header line, on empty and degraded responses too:

timings: 74ms total — setup 1, lexical 12, relational 0, embed 0, vector 16, fuse 26, post_fusion 9, rerank 2, alias_fanout 0, anchoring 0, facts_arm 5, response 3, other 0 (overlapped: keyword_arm 12, title_arm 12)

Say to your agent: "Why was that search slow? Show me where the time went."

Field Meaning
total_ms Wall time of the whole operation, measured on its own clock after the response is assembled.
stages_ms Time the request spent blocked in each stage that ran: setup (scope, config, mode), lexical, relational, expansion, embed, vector, fuse, post_fusion (boosts, dedup, identity tiers, return sizing), rerank, alias_fanout, anchoring, facts_arm (query), response (evidence delivery, response metadata, redaction). A second search the operation runs (a retry, a CRAG re-run) adds to the same stages; the alias fan-out's keyword searches count under alias_fanout.
other_ms Time no stage claimed. sum(stages_ms) + other_ms = total_ms.
overlapped_ms Work that ran alongside a stage, so it is not added to the total: the keyword and title arms run in parallel inside lexical (keyword_arm, title_arm), search's total-match count runs alongside the whole request (keyword_count), and the vector side (query expansion, the query embed and the vector search) starts with the lexical arms, so the part of expansion, embed and vector that finished while they ran is listed here under the stage's name. The rest of those stages, the part the request had to wait for, stays in stages_ms. The response metadata's concurrent reads are listed as meta_saved_facts, meta_entity_facts, meta_held, meta_readiness, meta_freshness, meta_embedding_held, meta_safe_index and meta_filter_hint; response.meta waits for the slowest of them.
parts_ms Present when a stage records its steps: response splits into evidence (evidence delivery), trust (the page-trust stamp), meta (the response metadata), keyword_count (the wait for search's total-match count) and feedback (the answer-feedback record). Parts run one after another and never overlap, so they sum to at most the stage; the rest of response is redaction, snippet caps and row projection. stages_ms.response keeps its whole time.

All values are integer milliseconds.

The whole CLI call and what it spent

gbrain search --json --timings and gbrain query --json --timings print { "results": [...], "timings_ms": {...}, "cost": {...} } instead of the bare result array (plain --json is unchanged); without --json, --timings adds one timings: line on stderr.

timings_ms adds the CLI's own phases to the operation's stages: total (process start to output), startup (module load, config, argument parsing), connect (opening the brain), context (operation context and source resolution), remote (a thin client's round trip to its server), op (the operation's total_ms), stages (its stages_ms plus other), overlapped, parts (the operation's parts_ms) and cli_other (CLI time in no phase: formatting, notices). A phase that did not run is absent; 0 means it took under half a millisecond. On a thin client op and stages are the server's.

cost (also _meta.retrieval.cost over MCP) counts every model call the request made, by kind (embedding, rerank, expansion, chat, decide; expansion is the same call chat_usage_log records with phase expansion), each with calls, input_tokens, output_tokens and usd, plus calls and estimated_usd in total. Tokens are what the provider reported; a call it reported none for counts its request estimate and is tallied in estimated_token_calls. usd comes from the shipped price tables and is left out when a model is not priced. Failed calls count (a provider can bill them); a call a budget guard refused was never sent and does not. A keyword-only search reads { "calls": 0, "estimated_usd": 0 }.

Diagnose a missing page

MCP:

{ "tool": "query", "arguments": { "query": "acme-example renewal terms", "expand": false, "explain_target": "meetings/2026-03-02-acme-example" } }

The response meta explain_target holds the diagnosis, and a notice carries the next step. On the command line, gbrain search|query "<q>" --explain-target <source>:<slug> --json prints { "results": [...], "explain_target": {...} } instead of the bare array, with the fix rendered as a command (next, argv, command); without --explain-target the output stays an array. When an arm failed on the call, why names it, since a failed arm is not evidence of absence:

code What happened Next step
target_returned The page is in the results at rank. Read its score_details.
target_collapsed It is a copy folded into the result at rank, which lists it in collapsed. Read that row, or set search.collapse false to return every copy.
target_beyond_limit It ranked below the requested limit; arms and why give each arm's rank. The notice repeats the search with a limit that reaches it.
target_dropped_dedup Dedup kept a higher-ranked row from the same page or a near-duplicate. Read the page directly with get_page.
target_dropped_return_sizing Autocut or adaptive return trimmed it. get_page, or repeat with autocut: false (query).
target_dropped_token_budget The evidence budget filled first. Repeat with a larger token_budget.
target_dropped_relaxed_keyword Only a loose keyword match found it. get_page, or rephrase with the page's own terms.
target_not_retrieved No arm returned it for this query. query --expand (expand: true; one call to the configured expansion model) or rephrase. The fix carries consent: ["paid", "egress"], so it renders next: ask_user: the agent asks before sending the query to the model.
target_not_embedded Its chunks have no vectors (held from embedding or not embedded yet), so only a keyword or title match can return it. gbrain doctor --json names the held pages and the embed command.
target_not_indexed The page has no indexed chunks. gbrain doctor --json names the re-index command.
target_projection_stale The page changed and its searchable text is still being rebuilt. Retry after gbrain doctor shows the backlog drained.
target_safe_chunks_uncertified Remote reads withhold pages indexed before the current safe-chunk format. The brain host runs gbrain repair safe-chunks.
target_ambiguous The slug exists in several sources. Repeat with explain_target as source:slug.
target_not_found_or_not_visible No page with that slug is readable here. Ask the user whether it exists and where; private pages are never confirmed.

Both params are declared on query on the full MCP tool surface; the cheap search tool and the starter list stay lean because every declared param is re-sent to the model on each turn. A starter-surface session calls request_tools {"surface": "full"} first. Agents on the default seven-verb memory surface do not have query; ask the brain host to run gbrain search "<question>" --explain --json, or enable the full tool surface.