Garry's Opinionated OpenClaw/Hermes Agent Brain
Search Modes
Two decisions shape every gbrain lookup, and this guide covers both:
- Which mode bundle your brain runs —
conservative/balanced/tokenmax, the named cost-knob presets that control cache, token budget, core-library expansion defaults, and result count. This is the config-level decision you make once (atgbrain initor viagbrain config set search.mode). - Which lookup verb to use per call —
gbrain search(keyword),gbrain query(hybrid), orgbrain get(direct). This is the per-lookup decision an agent makes on every question.
To see how a specific result was ranked, or why an expected page is missing,
see Explaining search results.
To find every page containing a literal phrase or identifier (what you would
otherwise grep for), use exact search: gbrain search --exact.
The three mode bundles
A search mode is a named preset for retrieval knobs. Operation-level options
can override it, so the bundle alone does not describe provider calls.
The bundles are frozen in src/core/search/mode.ts (MODE_BUNDLES).
Semantic result caching is temporarily disabled in every mode, regardless of configuration or per-call overrides. The cache settings below are retained configuration values; each request performs fresh retrieval. Stored cache rows and maintenance commands remain available.
| Knob | conservative |
balanced |
tokenmax |
|---|---|---|---|
cache.enabled |
true | true | true |
cache.similarity_threshold |
0.92 | 0.92 | 0.92 |
cache.ttl_seconds |
3600 | 3600 | 3600 |
intentWeighting |
true | true | true |
tokenBudget |
4000 | 12000 | off |
expansion (LLM multi-query) |
false | false | false |
expansion_variant_budget |
null (legacy) |
null (legacy) |
null (legacy) |
relationalRetrieval |
false | true | true |
relational_rerank_pin |
3 | 3 | 3 |
keyword_arm_confidence_floor |
null (off) |
null (off) |
null (off) |
metadata_boost_gate |
lexical |
lexical |
lexical |
searchLimit default |
10 | 25 | 50 |
reranker (cross-encoder) |
off | voyage:rerank-3-lite |
voyage:rerank-3-lite |
autocut (rerank-cliff cut) |
off | off | off |
reranker_gate |
off | off | off |
The expansion row is gbrain query's default: query (the only verb that
can expand) expands when a call leaves expand unset and the resolved row is
on. The row is off in all three modes, so query does not expand by default.
tokenmax turned it off after the 2026-10-14 expansion-latency eval: on 300 LongMemEval-S questions with
the reranker, query without expansion kept retrieval within the noise floor
(strict recall@10 298 vs 299 of 300; the reference's own re-run scored 298)
and its p50 fell from 2,022 to 227 ms (gbrain-evals GBRA-94 report,
2026-10-14). --expand / expand: true forces expansion in any mode and
--no-expand / expand: false skips it in any mode. The search.expansion
config key overrides the row like any other knob. gbrain search, the memory
verbs and the eval harnesses pin expansion per call, so search never
expands, even with search.expansion=true. gbrain search modes reports the
resolved row.
To turn expansion on for one brain without changing its mode, run
gbrain config set search.expansion true on the brain host (false pins it
off). Every query call that leaves expand unset then follows the key: the CLI, MCP over stdio and
gbrain serve --http all resolve the same row. A call that passes
--expand / expand: true or --no-expand / expand: false still wins. gbrain config unset search.expansion
returns to the mode default. The key is per brain and lives in its database,
so a thin client (gbrain init --mcp-only) can't set it; whoever runs the
brain host sets it, and the host needs gbrain v0.60.188.0 or later, because
query ignored search.expansion before that release.
Keyless retrieval takes the keyword-only path before expansion; configured
embedding and expansion providers are prerequisites. Image-only retrieval also
skips expansion. Check response metadata expansion_applied for actual
variant use, not just the requested setting. A configured cloud expander
receives the query; its model's input/output charges are separate from
downstream reading costs.
conservative— smallest payloads. Pairs naturally with a cheap downstream model (Haiku-class) or a high query volume.balanced— the default and the fallback when no mode is set.tokenmax— no token budget, 50 results by default. Pairs with an expensive downstream model you want fully fed.
Several of the knobs deserve a sentence:
expansionrewrites your query into multiple variants via a cheap LLM call when available (the historical Haiku estimate is roughly $1.50 per 1K queries; actual charges depend on model and token counts). It can recover alternate phrasings but can also hurt precision. It isgbrain query's default when a call leavesexpandunset (see the caption under the table);--expand/--no-expandwin per call.expansion_variant_budget(config keysearch.expansion_variant_budget) is the total RRF weight the expansion variants share at fusion time (weight_i = b / n_voting_arms; the original query's list always keeps weight 1).null— the default in every bundle — is the legacy equal-weight fusion, under which the LongMemEval receipt shows expansion halving small-k strict recall (93.19% → 54.89%recall_all@5); a number in (0, 4] caps the variants' total influence (1.0lets two agreeing variants exactly tie the original's top vote;0.5subordinates them). A no-op whenexpansionis off. Ranker-wave receipt (same recorded variants replayed at every budget): strictrecall_all@5climbs monotonically as the budget shrinks — 255/470 legacy → 394/470 at 0.25 — but even 0.25 trails plain hybrid (439/470) by 43 questions on the held-out decision set, so the bundles keepnulland the knob is an operator lever. That receipt predates page-grain fusion and the relaxed-keyword demotion: on the current ranking (halfA430, 215 questions, frozen variants) legacy expansion scores 205/215, budget1.0203/215,0.25202/215 and no expansion 202/215, so capping the variants no longer helps. Say to your agent: "Cap how much query expansion can outvote my original query" (no skill backs this; your agent runsgbrain config set search.expansion_variant_budget <b>, andgbrain config set search.expansion_variant_budget legacyrestores the default).relationalRetrievaladds a graph-walk recall arm for relational questions ("who invested in X", "what connects A and B"). Common rewordings count too: "X's investors", "people who funded X", "who is the founder of X", "which companies has X backed", "relationship between A and B", "who can introduce me to X". It's a pure no-op for non-relational queries, and it only fires when the named entity resolves to a page in your brain. Thequeryop'srelationalflag forces it on/off per call.relational_rerank_pin(config keysearch.relational_rerank_pin; 3 in every bundle) keeps those graph-walk answers from being buried by the cross-encoder reranker: the reranker scores page TEXT, and an edge-derived answer's text need not mention the entity you asked about, so on the relational benchmark the reranker alone dropped hit@1 from 21/39 to 3/39. After the reranker runs, up to this many relational-arm rows are pinned back above the reranked text rows in their fused order;0/offrestores the pre-pin ranking. A pure no-op for non-relational queries and whenever the reranker is off or failed open. It trusts the graph — if your edges are stale, an edge answer now sits at the top rather than at the end of page 1. Say to your agent: "Stop pinning graph answers above the reranked results" (no skill backs this; your agent runsgbrain config set search.relational_rerank_pin off, andgbrain config set search.relational_rerank_pin 3restores the default).metadata_boost_gate(config keysearch.metadata_boost_gate;lexicalin every bundle) decides whether the post-fusion metadata boosts (backlinks, salience, recency, graph adjacency, alias resolution) run when the vector arm was the only voter. Those boosts reward well-connected hub pages; on paraphrase-style concept questions where no keyword, title or relational row fused, they promoted hubs over the page that actually matched.lexicalskips them in that case and keeps the vector order;alwaysrestores the pre-wave pipeline. Supersession, exact-match and reranking are untouched either way. Receipt: conceptual-recall nDCG@5 rose from 53.0 to 57.8 on held-out concepts with the entity, brain and LongMemEval benchmarks byte-identical. Say to your agent: "Always apply backlink and recency boosts, even on vector-only matches" (no skill backs this; your agent runsgbrain config set search.metadata_boost_gate always, andgbrain config set search.metadata_boost_gate lexicalrestores the default).reranker_gate(config keysearch.reranker.gate; off in every bundle) grades the fused candidates before the cross-encoder runs, from what exists before reranking: an exact slug or full-title lookup that finds exactly one page, a declared alias that names exactly one page, or a top result whose raw cosine is at leastsearch.evidence_cosine_floor(0.8) and leads the best other page bysearch.reranker.gate_min_gap(δ, 0.05). Image queries and pages markedexternal_untrustednever grade strong.shadowrecords the grade in the response'srerank_gatemetadata, on the--explainheader and ingbrain search stats, and still reranks: results are identical tooff. Use it to see how often the reranker is paying for an answer retrieval already found. No mode skips the reranker: on the memory-proof dev sets no question's top cosine reached 0.8 with voyage-4 embeddings, and the reranker changed about half of the delivered evidence. The floor and δ are part of the cache key. Say to your agent: "Show me how often my searches would not need the reranker" (no skill backs this; your agent runsgbrain config set search.reranker.gate shadow, latergbrain search stats, andgbrain config set search.reranker.gate offrestores the default).keyword_arm_confidence_floor(config keysearch.keyword_arm_confidence_floor; off in every bundle) down-weights the keyword and title arms in the fusion when the keyword arm's top-vs-second margin ratio is below the floor (only when a vector arm also voted and the query is not relational). It ships off: its pre-registered conceptual-recall test did not move the held-out score, and most of that gap came from pages the keyword arm never matched at all. Operators with a noisy keyword arm can set a floor in(0, 1];offrestores the default.keywordOrFallback(on in every mode; config keysearch.keywordOrFallback) relaxes the keyword and title arms from AND to OR when strict AND matching finds nothing, so a multi-word query still gets keyword recall instead of leaning on vectors alone. Set the config key tofalseto keep strict AND matching.cjk_keyword_deadline_ms(config keysearch.cjk_keyword_deadline_ms, integer milliseconds, default 3000, range 500 to 30000; for examplegbrain config set search.cjk_keyword_deadline_ms 5000) is the total time budget of hybrid search's CJK keyword arm, split between full scoring and one capped retry (see multi-language FTS). A cut arm reportskeyword_candidates_incomplete; another value is refused with exit 2.keyword_statement_timeout_ms(Postgres only; config keysearch.keyword_statement_timeout_ms, integer milliseconds, default 8000, range 1000 to 60000; for examplegbrain config set search.keyword_statement_timeout_ms 20000) is the transaction-localstatement_timeoutaround every keyword, keyword-count, keyword-page, title and CJK search statement. It is an operator knob, read once per connection (restartgbrain serveor the workers after setting it) and never taken from a request; another value is refused with exit 2. A keyword statement the bound cancels fails open to the vector arm (keyword_arm_failed); doctor'skeyword_plancheck warns when the brain's commonest term is near the bound (see troubleshooting).hnsw_iterative_scan(Postgres with pgvector 0.8+; config keysearch.hnsw_iterative_scan, string, defaultrelaxed_order, one ofrelaxed_order | strict_order | off; envGBRAIN_HNSW_ITERATIVE_SCANwins) is the iterative HNSW scan mode for filtered vector search. Relaxed order keeps closer in-filter candidates that strict order drops; results are re-sorted either way.gbrain config set search.hnsw_iterative_scan strict_orderrestores the older mode (restart serve and autopilot: it is read once per engine, so once per process on a one-brain server); another value is refused with exit 2.
Setting and resolving the mode
gbrain config set search.mode tokenmax
Per-knob resolution (highest first):
per-call SearchOpts → per-key config override (search.cache.enabled, …) →
MODE_BUNDLES[search.mode] → MODE_BUNDLES.balanced (fallback)
Mode resolution lives in bare hybridSearch, not just the cached wrapper,
so eval replays test the same mode-affected behavior as the production
query op. Result counts follow the per-call limit, or the mode's
searchLimit when no limit is supplied. The wrapper does not read or write
stored semantic results while caching is disabled. gbrain search modes
reports effective cache_enabled: false, and cache stats reports
enabled: false, even when retained configuration enables the cache.
Cost intuition
The table estimates only the tokens your downstream agent pays to read
per query: an assumed payload per mode times 10K queries a month times the
model's input rate from gbrain's pricing table (src/core/model-pricing.ts).
Embedding, reranking and expansion calls are separate charges. The
corner-to-corner spread is about 200x once you pair mode with downstream model.
The install picker and the upgrade banner print the same matrix from
src/core/search/mode-advice.ts.
| Mode \ Downstream | Haiku 5.5 ($0.10/M in) | Sonnet 5.5 ($2/M in) | Opus 5.5 ($4/M in) |
|---|---|---|---|
| conservative (~4K tok) | $4/mo | $80/mo | $160/mo |
| balanced (~10K tok) | $10/mo | $200/mo | $400/mo |
| tokenmax (~20K tok) | $20/mo | $400/mo | $800/mo |
Scales linearly with volume. Budget for fresh retrieval on every query while
semantic result caching is disabled; repeated searches may take longer and use
more provider calls. Downstream prompt caching in the agent loop is independent.
Mismatched pairings waste capacity in both directions — a tokenmax payload overwhelms a cheap model,
a conservative payload starves an expensive one. The full methodology and
realistic-scale walkthrough live in
docs/eval/SEARCH_MODE_METHODOLOGY.md.
CLI surfaces
gbrain search modes # what is running, with per-knob attribution
gbrain search modes --reset # clear search.* overrides (mode bundle wins)
gbrain search stats [--days N] # cache hit rate, intent mix, budget drops,
# rerank gate counts when the gate is on
gbrain search tune [--apply] # data-driven recommendations
gbrain search diagnose "<query>" --target <slug>
# trace where a page surfaces (or fails to)
# across the keyword/vector/alias/hybrid layers
gbrain search modes also answers the question the knob table cannot: is
the resolved reranker actually going to run? Below the attribution table it
prints one runtime line — Reranker: voyage:rerank-3-lite (enabled) — VOYAGE_API_KEY present, Reranker: off (resolved) — …, or Reranker: <model> (enabled but NOT running) — <paste-ready fix> — and each bundle row
carries reranker=… topNIn=… autocut=…. --json exposes the same verdict
as reranker_readiness. Without the key, search still works: results come
back in fusion order, gbrain search "<query>" --explain shows
degraded: reranker_skipped (no_key), and gbrain doctor's
reranker_health names the fix. Say to your agent: "check whether my
brain's reranker is actually running" — "turn reranking off for now" —
your agent runs gbrain search modes / gbrain doctor, then either exports
VOYAGE_API_KEY or runs gbrain config set search.reranker.enabled false.
The default reranker is Voyage rerank-3-lite. It replaced rerank-2.5
after gbrain-evals #148 (v0.10.93) measured 60% lower rerank cost at 50
candidates × 1,400 tokens with quality within noise. It applies only to
brains that never set search.reranker.model; a brain with an explicit
model keeps it. To go back to the previous default, run
gbrain config set search.reranker.model voyage:rerank-2.5.
TypeSafe's Jev can be the reranker instead of Voyage (gbrain decide enable rerank sets it and gbrain decide disable rerank restores your previous
reranker; setup in TypeSafe (Jev)). The same
provider also powers System One, a set of off-by-default decision slots in
the search path, such as an evidence gate that drops results with no evidence
for the question but, by default, never below three results and never an exact match.
None of them changes a mode bundle. See System One.
The mode picker runs inside gbrain init. Non-TTY and --json initialization
tentatively applies its recommendation: tokenmax with a chat key (Anthropic,
OpenAI or Google), balanced with a ready reranker but no chat key (nothing in
balanced needs a chat model), and conservative for a Haiku subagent or when
neither exists. Keys count whether they are exported or saved in
~/.gbrain/config.json. Existing valid selections are preserved, and the
picker asks agents to confirm the choice with their operator before
continuing a real setup.
An agent that already knows the operator's choice records it at install time
with gbrain init --search-mode <conservative|balanced|tokenmax>: no
recommendation, no first-run search_mode question, and the brain records
search.mode_source: operator (picker choices record auto; gbrain config set search.mode records operator). On a brain that already has a different
mode, --search-mode refuses unless you also pass --force.
Query instruction prefix
Instruction-style embedding models (Qwen3-Embedding, e5, BGE v1.5, nomic-embed, EmbeddingGemma)
expect a query instruction in front of each search query and none in front of
documents. GBrain sends no instruction unless you set one for the brain;
nothing is guessed from the model id at query time. gbrain doctor reports
embedding_query_prefix when the configured model belongs to one of those
families and no prefix is set, and prints the model card's value as a command
you can run as printed.
| Family | Documented value |
|---|---|
| Qwen3-Embedding | Instruct: Given a web search query, retrieve relevant passages that answer the query + newline + Query: |
| e5 | query: |
| BGE v1.5 | Represent this sentence for searching relevant passages: |
| nomic-embed | search_query: |
| EmbeddingGemma | task: search result | query: |
Set. Quote the value so trailing spaces and newlines survive the shell; a newline needs ANSI-C quoting:
gbrain config set embedding_query_prefix "query: "
gbrain config set embedding_query_prefix $'Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:'
The prefix is stored in the brain's database config, so each brain (and each mounted brain in one MCP server) uses its own. It applies to query embeddings only: keyword search uses the original query, stored document vectors are not re-embedded, and the query-cache key includes the prefix. It takes effect on the next CLI or MCP query without restarting a running server.
Verify. gbrain config get embedding_query_prefix --raw prints the stored
bytes, and gbrain doctor stops reporting embedding_query_prefix.
Unset. gbrain config unset embedding_query_prefix restores bare query
embeddings on the next query.
nomic-embed also expects search_document: in front of documents, and
EmbeddingGemma's card formats documents as title: {title} | text: {text}.
GBrain does not prefix or format documents, so on those models the query prefix
is a partial fix (#3783, #5215).
Choosing a lookup verb (search vs query vs get)
Independent of which bundle is active, every individual lookup should use the cheapest verb that answers the question.
on user_asks_about(topic):
# Decision tree: pick the right lookup verb
if know_exact_slug(topic):
# Direct get -- instant, no search overhead
result = gbrain get <slug>
# e.g., "Tell me about Alice" -> gbrain get alice-example
# Returns the FULL page -- compiled truth + timeline
elif topic.is_exact_name or topic.is_keyword:
# MODE 1: Cheap-hybrid search -- vector + keyword + RRF, NO LLM
# expansion. Embeds the query when embeddings are configured; the
# keyword arm still works day-one without them (keyword-only is
# also available via the search.mcp_keyword_only opt-out).
results = gbrain search "{name_or_keyword}"
# e.g., "Find anything about Series A" -> gbrain search "Series A"
# Returns CHUNKS, not full pages
# IMPORTANT: search returns chunks
# If the chunk confirms relevance, THEN load the full page:
if chunk.confirms_relevance:
full_page = gbrain get <slug_from_chunk>
elif topic.is_semantic_question or topic.is_concept_or_landscape:
# MODE 2: Full hybrid -- vector + keyword + RRF + reranking. Owns
# concept / landscape / "all-of-X" questions. Pass --expand to add
# one LLM expansion call when the original wording is weak; it is
# off by default because it measured no retrieval gain (GBRA-94).
results = gbrain query "{natural language question}"
# e.g., "Who do I know at fintech companies?" -> gbrain query "fintech contacts"
# e.g., "all the companies doing offshore wind" -> gbrain query "..."
# Returns ranked chunks via vector + keyword + RRF (+ expansion with --expand)
# Same rule: chunks first, then get full page if needed
if chunk.confirms_relevance:
full_page = gbrain get <slug_from_chunk>
# Quick reference:
# | Mode | Command | Needs Embeddings | Speed | Best For |
# |-------------|----------------------|------------------|---------|-------------------------------------------|
# | Cheap-hybrid| gbrain search "term" | Uses if present | Fastest | Known names, exact tokens |
# | Full hybrid | gbrain query "..." | Yes | Fast | Concept / landscape / "all-of-X", synonyms |
# | Direct | gbrain get <slug> | No | Instant | When you know the slug |
# Progression over time:
# Day 1: search (keyword arm works without embeddings)
# After first embed: vector arm + full hybrid (query) unlocked
# Once you know slugs: direct get for speed
# Precedence for conflicting information within a page:
# 1. User's direct statements (always wins)
# 2. Compiled truth sections (synthesized from evidence)
# 3. Timeline entries (raw signal, reverse chronological)
# 4. External sources (web search, APIs)
Tricky Spots
- Search returns chunks, not full pages. After
gbrain searchorgbrain query, you get excerpts. Always rungbrain get <slug>to load the full page when the chunk confirms relevance. Don't answer questions from chunks alone when the full context matters. - Search works without embeddings. On day one before any embedding run,
gbrain searchstill works (the keyword arm carries it; the vector arm joins once embeddings exist). Don't tell the user "search isn't available yet" -- search is always available. - Don't use full hybrid for known names.
gbrain query "Alice Example" --expandwastes an LLM expansion call, and barequeryreturns the larger evidence payload. Usegbrain search "Alice Example"or better yetgbrain get alice-exampleif you know the slug. - Token budget awareness. A full page via
gbrain getcan be large. Read the search chunks first to confirm relevance before pulling the full page. "Did anyone mention the Series A?" -- search results (chunks) are probably enough. "Tell me everything about Alice" -- get the full page. - Full hybrid needs embeddings to have been run. If
gbrain queryreturns nothing butgbrain searchfinds results, the embeddings haven't been generated yet. Run the embedding pipeline first. - A populated
gbrain searchresult set is not proof you found everything. Neither verb expands by default, so synonym- and outcome-phrased matches can be missed even when a search returns plenty of hits. For "find every / all / the landscape of" questions, usegbrain query, adding--expand(one call to the configured expansion model, which needs an expansion provider) when the wording is likely to differ from the notes; expanded results are still a ranked top-K; for literal exhaustive enumeration ("list every page of type X"), uselist_pagespagination. A nonzero count is not a completeness signal. - A remote
searchorquerywith nolimitreturns at most a few pages that matched only by meaning. Over MCP (HTTP or stdio), every page that matched the query's words, a name, an alias or an exact identity comes back, but pages that only the vector arm found fill the result only up tosearch.remote_page_capdistinct pages in total (default 3). Without the cap, an embedding-backed search on a small brain returned most of the brain on every call, pages from other members' sources included. When the cap leaves pages out, a line after the results says how many (_meta.retrieval.page_capcounts them); passlimitfor the full ranked list, which landscape and "find every" questions usually want. Local CLI calls, an explicitlimit, paged calls, image queries and host-run subagent tool calls are never capped; a thin-client CLI call is remote, so it is capped and prints the line on stderr (pass--limit). Set the cap withgbrain config set search.remote_page_cap <n>;0turns it off.
How to Verify
- Run
gbrain search "Alice"-- confirm it returns chunks with matching text and slug references. - Run
gbrain query "who works at fintech companies"-- confirm it returns semantically relevant results (not just keyword matches on "fintech"). - Run
gbrain get alice-example-- confirm it returns the full page with compiled truth and timeline. - Compare: search for the same entity using all three modes. Keyword should be fastest, hybrid should surface conceptual matches, direct should return the complete page.
- After a search returns a chunk, run
gbrain geton the slug from that chunk. Confirm the full page contains more context than the chunk alone. - Run
gbrain search modes-- confirm the active mode bundle, any per-key overrides, and theReranker:line (enabledwith the key present, oroff) are what you expect.
Part of the GBrain Skillpack.