Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
27.9 KB
Raw Blame

Search Modes

Two decisions shape every gbrain lookup, and this guide covers both:

  1. 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 (at gbrain init or via gbrain config set search.mode).
  2. Which lookup verb to use per call — gbrain search (keyword), gbrain query (hybrid), or gbrain 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:

  • expansion rewrites 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 is gbrain query's default when a call leaves expand unset (see the caption under the table); --expand / --no-expand win per call.
  • expansion_variant_budget (config key search.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.0 lets two agreeing variants exactly tie the original's top vote; 0.5 subordinates them). A no-op when expansion is off. Ranker-wave receipt (same recorded variants replayed at every budget): strict recall_all@5 climbs 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 keep null and 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, budget 1.0 203/215, 0.25 202/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 runs gbrain config set search.expansion_variant_budget <b>, and gbrain config set search.expansion_variant_budget legacy restores the default).
  • relationalRetrieval adds 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. The query op's relational flag forces it on/off per call.
  • relational_rerank_pin (config key search.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/off restores 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 runs gbrain config set search.relational_rerank_pin off, and gbrain config set search.relational_rerank_pin 3 restores the default).
  • metadata_boost_gate (config key search.metadata_boost_gate; lexical in 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. lexical skips them in that case and keeps the vector order; always restores 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 runs gbrain config set search.metadata_boost_gate always, and gbrain config set search.metadata_boost_gate lexical restores the default).
  • reranker_gate (config key search.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 least search.evidence_cosine_floor (0.8) and leads the best other page by search.reranker.gate_min_gap (δ, 0.05). Image queries and pages marked external_untrusted never grade strong. shadow records the grade in the response's rerank_gate metadata, on the --explain header and in gbrain search stats, and still reranks: results are identical to off. 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 runs gbrain config set search.reranker.gate shadow, later gbrain search stats, and gbrain config set search.reranker.gate off restores the default).
  • keyword_arm_confidence_floor (config key search.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]; off restores the default.
  • keywordOrFallback (on in every mode; config key search.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 to false to keep strict AND matching.
  • cjk_keyword_deadline_ms (config key search.cjk_keyword_deadline_ms, integer milliseconds, default 3000, range 500 to 30000; for example gbrain 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 reports keyword_candidates_incomplete; another value is refused with exit 2.
  • keyword_statement_timeout_ms (Postgres only; config key search.keyword_statement_timeout_ms, integer milliseconds, default 8000, range 1000 to 60000; for example gbrain config set search.keyword_statement_timeout_ms 20000) is the transaction-local statement_timeout around every keyword, keyword-count, keyword-page, title and CJK search statement. It is an operator knob, read once per connection (restart gbrain serve or 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's keyword_plan check warns when the brain's commonest term is near the bound (see troubleshooting).
  • hnsw_iterative_scan (Postgres with pgvector 0.8+; config key search.hnsw_iterative_scan, string, default relaxed_order, one of relaxed_order | strict_order | off; env GBRAIN_HNSW_ITERATIVE_SCAN wins) 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_order restores 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

  1. Search returns chunks, not full pages. After gbrain search or gbrain query, you get excerpts. Always run gbrain get <slug> to load the full page when the chunk confirms relevance. Don't answer questions from chunks alone when the full context matters.
  2. Search works without embeddings. On day one before any embedding run, gbrain search still 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.
  3. Don't use full hybrid for known names. gbrain query "Alice Example" --expand wastes an LLM expansion call, and bare query returns the larger evidence payload. Use gbrain search "Alice Example" or better yet gbrain get alice-example if you know the slug.
  4. Token budget awareness. A full page via gbrain get can 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.
  5. Full hybrid needs embeddings to have been run. If gbrain query returns nothing but gbrain search finds results, the embeddings haven't been generated yet. Run the embedding pipeline first.
  6. A populated gbrain search result 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, use gbrain 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"), use list_pages pagination. A nonzero count is not a completeness signal.
  7. A remote search or query with no limit returns 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 to search.remote_page_cap distinct 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_cap counts them); pass limit for the full ranked list, which landscape and "find every" questions usually want. Local CLI calls, an explicit limit, 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 with gbrain config set search.remote_page_cap <n>; 0 turns it off.

How to Verify

  1. Run gbrain search "Alice" -- confirm it returns chunks with matching text and slug references.
  2. Run gbrain query "who works at fintech companies" -- confirm it returns semantically relevant results (not just keyword matches on "fintech").
  3. Run gbrain get alice-example -- confirm it returns the full page with compiled truth and timeline.
  4. 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.
  5. After a search returns a chunk, run gbrain get on the slug from that chunk. Confirm the full page contains more context than the chunk alone.
  6. Run gbrain search modes -- confirm the active mode bundle, any per-key overrides, and the Reranker: line (enabled with the key present, or off) are what you expect.

Part of the GBrain Skillpack.