Garry's Opinionated OpenClaw/Hermes Agent Brain
Brain-First Lookup Convention
Read this before doing ANY entity/person/company/fact lookup.
Sub-agents and fresh sessions inherit gbrain tools but not the knowledge of when and how to use them. This file is that knowledge.
Which gbrain call for which lookup
Ask gbrain before you grep, cat, ls or run SQL on the brain checkout: it
reads the index across every source, ranks, filters and names the slug to read
next. With the gbrain MCP server connected, call the tool of the same name
instead of the CLI (one connection, no per-call startup).
| Lookup | CLI | MCP tool |
|---|---|---|
| Find a page by name or path | gbrain find <name|prefix|glob> [--type T] [--source S] |
find_pages |
| Count pages by kind or source | gbrain stats --by source,type [--since 30d] [--collapse-aliases] |
get_stats (needs an admin-scope token) |
| Answer a question, search a topic | gbrain query "<question>" [--types '["meeting"]'] [--since 30d] |
query |
| Pages with these words | gbrain search "<words>" [--match keyword] [--source S] |
search |
| Read a known page | gbrain get <slug> |
get_page |
| Read only the part a search hit points at | gbrain get <slug> --around-chunk-id <chunk_id> or --lines '{"from":1,"count":200}' |
get_page |
| What the brain knows about a person or company | gbrain entity <slug>, then gbrain recall "<topic>" --json |
entity, recall |
| Links, dated events, every page of a type | gbrain backlinks <slug>, gbrain timeline <slug>, gbrain list --type T |
get_backlinks, get_timeline, list_pages |
| Save a fact the user stated | gbrain remember "<fact>" --entity <slug> --content-origin user_said --provenance "<where>" |
remember |
| Why a page didn't rank | gbrain query "<q>" --explain-target <slug> |
query |
| Which installed skill fits a request | gbrain skills resolve --text "<request>" --json (after gbrain skills index build) |
none (CLI only) |
| Find something archived to B2, Supabase or S3 | gbrain storage-find "<phrase>" |
storage_find |
Parse --json output instead of matching the text; notices go to stderr. Never
send stderr to /dev/null: a refusal there (no_brain, GBRAIN_DB_ACCESS)
then reads as "no results"; check the exit code too. Take
chunk_id from a fresh search --json hit (an old one fails revision_changed),
and read a degraded notice before concluding the brain has nothing.
A row with origin: guest is an outside guest's words, never the owner's; never copy it into owner pages unasked; promote it only on the owner's word.
Dated questions: read by valid time
When the user asks what a page said, or what was in force, on a date, read it
with get_page {slug, as_of: 'YYYY-MM-DD'} (CLI: gbrain get <slug> --as-of <date>), not the current page. Quote text only from an in_force answer; any
other status puts the edition under last_in_force or earliest_known, and
says so. When valid_time.uncertain is true, tell the user why and follow the
fix (it asks the user for a date or a backup; never invent either). A reply
without valid_time is the current page.
When you edit a page whose text takes effect on a date, keep its valid_from
for a correction, or set a new quoted valid_from for a new edition. Read the
write result's valid_time advisory and ask the user when it asks a question.
Which record to use for a change in effect (edit in place, amendment record,
supersedes link): the page history guide (docs/guides/page-history.md, Valid time).
Identity needs an exact match
Resolving an email sender, a calendar attendee or a contact to a person page is an identity decision, and a search's top hit is not one: ranking always returns something, so taking it files strangers onto known contacts. Use the exact lookup:
gbrain whois [email protected] --source-id __all__ --json # an email address
gbrain whois "Alice Example" --source-id __all__ --json # a display name
whois returns the entity pages whose frontmatter email, title or declared
alias equals the query, ignoring case, accents and quotes, and never anything
fuzzy. Look up the email address first and the display name only when the
address has no match. One match is the person. matches: [] means no exact
match: treat the sender as new or ask the user. ambiguous: true means
several pages match: ask, or resolve by the email address. Never fall back to
a search's top hit, a partial name or a similar address, and never merge a
stranger into a known contact's page.
Available GBrain Tools
Your tool inventory includes these (prefixed gbrain__ in OpenClaw):
| Tool | Use for |
|---|---|
gbrain__search / search |
Exact tokens / known names — cheap hybrid, no expansion |
gbrain__query / query |
Concept / landscape questions — hybrid; expand: true adds LLM expansion |
gbrain__get_page / get_page |
Direct page read when you know the slug |
gbrain__get_links / get_links |
Outgoing links from a page |
gbrain__get_backlinks / get_backlinks |
Who references this entity |
gbrain__get_timeline / get_timeline |
Dated events for an entity |
gbrain__resolve_slugs / resolve_slugs |
Fuzzy slug resolution |
gbrain__traverse_graph / traverse_graph |
Walk the relationship graph |
gbrain__put_page / put_page |
Create or update a brain page |
gbrain__add_timeline_entry |
Add a dated event |
gbrain__add_link |
Add a relationship edge |
Tool names vary by transport (MCP uses short names, OpenClaw plugin uses
gbrain__ prefix). Both work. Use whichever your environment provides.
The Lookup Chain (MANDATORY ORDER)
Route by the SHAPE of the question, then escalate:
- Exact known token / name / structured field →
search— cheap hybrid (vector + keyword, no expansion; embedding-only cost). - Concept / landscape / synonym-phrased question ("all the X that do Y",
"the landscape of Z") →
queryFIRST — meaning-match and reranking recover phrasingssearchmisses.expand: trueadds one LLM expansion call when the results look thin. get_pageif you found a slug — read the full compiled truth.- External APIs only after steps 1-2 return nothing useful.
A nonzero search count is NOT a completeness signal. For "did I capture
everything about X?" run query even if search already returned hits —
synonym- and outcome-phrased matches drop silently otherwise. And query is
still top-K: for literal "list every page that…" enumeration, use list_pages
with pagination.
Never skip to external APIs without completing steps 1-2. The brain has thousands of pages. The answer is almost always there.
Rules
- Score > 0.5 = use it. Don't reach for external APIs when the brain answered.
- User's direct statements are highest-authority data. The brain captures what the user said in meetings, conversations, and notes. External sources are supplementary.
- After any brain page write: trigger a sync so new pages are searchable.
In OpenClaw:
gbrain__sync_brain. From CLI:gbrain sync --no-pull. - Bank every notable external API pull via
gbrain captureinto the inbox before the conversation moves on — the cycle enriches it later. A lookup you paid for and didn't bank is a lookup you'll pay for again. - Every brain page reference in output should use a clickable link format appropriate to the deployment (GitHub URL, local path, or slug).
- Never use
memory_searchfor entity lookups. Memory tools search session notes (MEMORY.md), not the brain knowledge graph. Usesearchorqueryfor entity lookups.
Entity Page Conventions
Standard directory structure:
| Directory | Type | Example |
|---|---|---|
people/ |
person | people/paul-graham.md |
companies/ |
company | companies/stripe.md |
deals/ |
deal | deals/stripe-series-c.md |
meetings/ |
meeting | meetings/2026-04-23-weekly-sync.md |
projects/ |
project | projects/gbrain.md |
yc/ |
yc | yc/batch-w26.md |
When creating new pages, include proper frontmatter with type, title,
and tags fields.
When Spawning Further Sub-agents
If you spawn your own sub-agents, include this line in their task prompt:
Read
skills/conventions/brain-first.mdbefore starting work.
This ensures the convention propagates through any depth of sub-agent chain.
Declarative opt-out (v0.36.x)
A skill can declare it does not need brain-first by adding this line to its frontmatter:
brain_first: exempt
Use this for pure-infra skills (cron schedulers, container managers,
ask-user prompters, browser drivers) whose entire job is to operate without
consulting the brain. The doctor skill_brain_first check honors this opt-
out; the gbrain doctor --fix auto-add of the canonical Convention callout
skips opted-out skills.
Strict canonical form (the parser is loud about typos):
| Form | Result |
|---|---|
brain_first: exempt |
✅ matches |
brain-first: exempt |
⚠ doctor hint — snake_case required |
BrainFirst: exempt |
⚠ doctor hint — snake_case required |
brain_first: "exempt" |
⚠ doctor hint — drop the quotes |
brain_first: Exempt |
⚠ doctor hint — value must be lowercase |
brain_first: required |
⚠ doctor hint — only exempt is supported in v0.36 |
A near-miss prints a paste-ready fix line and the skill stays flagged until the canonical form lands. Silent typos would be the worst outcome ("I declared exempt and it still flags!"), so the parser refuses to guess.
You do NOT need to declare brain_first: exempt when:
- The skill ALREADY includes the canonical Convention callout above
(this file's path). The compliance check matches
> **Convention:**blockquotes referencingbrain-first.mdand short-circuits to OK.brain-ops,signal-detector,idea-ingest,enrich,perplexity-research, andacademic-verifyall pass via this path. - The skill has no external-lookup references at all (
web_search,exa,perplexity,happenstance,crustdata,captain-api,firecrawl). Trivially exempt.
When in doubt: declare brain_first: exempt explicitly OR add the
canonical Convention callout near the top of the skill body. Both are
zero-friction one-line operations.
Recording why a page changed
When you edit a policy, contract, plan or any document page, pass reason on
put_page or edit_page with one line on why, in the user's words where you
have them ("Client asked for the 30-day window."). Edit the existing page with
its expected_revision; don't create a second page for a new edition.
get_versions shows each version's replaced_because. Never put a credential
in a reason: it can be pushed in a Git commit message, and gbrain refuses it.