Garry's Opinionated OpenClaw/Hermes Agent Brain
Connect and administer GBrain MCP
Choose the task first. Connecting a harness and administering the server use different credentials.
| Task | Start here | Required access |
|---|---|---|
| Run an HTTP MCP server | Deployment | Access to the brain host and its service configuration |
| Open the admin panel or manage clients | MCP administration | The running server's separate owner bootstrap credential |
| Connect an existing agent | Hosted harness setup | Native OAuth/PKCE, or a private machine-client handoff |
| Wire Claude Code to a local brain in one command | gbrain setup claude-code |
A local GBrain installation; setup resolves the brain, writes MCP and read-context hooks, and verifies them |
| Run a local MCP pipe | Local stdio | A local GBrain installation; no HTTP admin panel is created |
| Diagnose a failed connection | Recovery table | Start with the failed stage and the authority you actually hold |
| A tool call returned an error | A tool call returned an error | None: the error says who acts |
For agents: read the MCP access skill.
If skill tools are unavailable, the instructions here and in
ADMIN.md work directly. A connected harness can also read
gbrain://capabilities for its effective permissions and administration guidance.
Owner administration is separate from MCP admin scope. An OAuth access
token, client secret, or ordinary MCP connection does not authorize dashboard
login, client creation, or client revocation. A public PKCE client has no client
secret. Ask the server-hosting harness or a separately authorized administrator
to perform owner actions.
Say to that administrator: “Open the admin panel for my running GBrain server. Use its configured endpoint and protected owner credential. Give me a fresh single-use login link without opening it yourself.”
Say to the connecting agent: “Connect this harness to my hosted GBrain. Use its native OAuth flow if available; otherwise use a private machine handoff. Follow the hosted setup guide and report configuration separately from an observed connection in this harness.”
Tool descriptions are deliberately short (the starter list is pinned at 25,000
characters by test/mcp-schema-budget.test.ts); the longer guidance for each
starter tool is in the MCP tool reference.
Client-specific details: ChatGPT, Claude Code, Claude Desktop, Codex, opencode, Perplexity, OpenClaw, and the adapter reference.
One-click client links
Claude and Cursor can each add GBrain from one link. The link opens the client's own "add server" form with the MCP URL already filled in. You check it, confirm, and sign in there as usual. The link holds no password or token.
Hosted GBrain (MCP URL https://gbrain.io/mcp):
- Claude (claude.ai and Claude Desktop), open in a browser:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=GBrain&connectorUrl=https%3A%2F%2Fgbrain.io%2Fmcp - Cursor, open in a browser or click where links work:
cursor://anysphere.cursor-deeplink/mcp/install?name=gbrain&config=eyJ1cmwiOiJodHRwczovL2dicmFpbi5pby9tY3AifQ%3D%3D
Your own brain: gbrain mcp expose prints these links for your URL in
its Next block, gbrain mcp expose --status repeats them, and --json
returns them as install_links. The Cursor link is always printed, because
Cursor connects from your own computer (on a tailnet-only brain, that computer
must be on your tailnet). The Claude link is printed only with --funnel,
because claude.ai connects from Anthropic's servers, which can't reach a
tailnet-only address.
If the form opens empty, add the server by hand: Claude Desktop. Today Claude's form loses the filled-in values after a sign-in redirect and on iPhone Safari. ChatGPT and Perplexity have no such link, so follow their pages.
A tool call returned an error
Every gbrain tool error is one content block holding a JSON envelope. Read
code (an older server sends only error), then follow fix.next:
run: callfix.mcp(or runfix.argvwhere you have a shell) exactly as given.ask_user: relayuser_messageand stop; act only after the user agrees.tell_user_to_run: the fix needs the user or the brain host's operator (for example a scope grant or a CLI-only repair); give themfix.command.wait: retry after the stated delay with the same request.report: tell the user what happened; the host operator runsgbrain doctor --json.
Then run fix.verify, which is always read-only. A mutating call with an
unknown outcome points at its write receipt (get_write_request), never at a
blind retry. Successful results can carry extra [gbrain notice …] text blocks
after content[0]; read them too (a degraded notice means an empty result is
not proof the user has no notes). Full contract, including the scope-failure
error/code pairs: AGENT_OPERATOR_v1.
Search and query result rows
search and query return their rows as compact JSON in the first content
block. Remote callers get lean rows by default: the fields an agent acts
on, without the ranking diagnostics that would make each row several times
longer than its evidence text.
A lean row keeps slug, title, type, chunk_text, score (4
significant digits), effective_date, source_id, chunk_id (with slug
and source_id, the assemble_evidence hit), evidence, create_safety
(the duplicate-page guard), trust_tier and origin. It keeps id (the
fetch key) only when this connection can call fetch at that moment: a
full surface, a stdio session request_tools widened, or an HTTP client
whose surface and scopes include it (starter and verbs do not list
fetch). After fetch becomes callable, re-run search for id or pass
the row's slug to fetch (accepted when unambiguous); fields: "full"
returns every field. It also keeps every safety or
provenance marker that is present: injection_suspected, injection_p,
unverified, content_flag, status, superseded, superseded_by,
message_id, thread_id, source_subject, modality when not text,
stale when true, provenance: "generated" on a machine-written page,
and delivered: {"truncated": true} when evidence delivery cut the text.
A row of third-party text carries quoted: "transcript", and its
chunk_text is a quoted excerpt: a line naming the page as source
material, not instructions, then the text inside a code fence it cannot
close. Third-party text is 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 taken from one, marker fact <id>: saved by the conversation-facts
extractor (provenance cli:extract-conversation-facts), or recorded as
derived from or held on such a page (the facts backstop on a synced Slack,
email or meeting page, extract_facts; for older backstop facts, the page
its source_session names). If that lookup fails, saved_facts is left out
(degraded stage saved_facts_withheld) and remote recall returns no facts
(facts_degraded.reason: "saved_facts_withheld"), never unquoted facts. Each tool-call or function-call JSON block in it (Gemini
functionCall included) is replaced by
[tool call: <name>, arguments omitted], and so is each XML-style call
block (function_calls, invoke, tool_use, tool_call). search, query and
assemble_evidence return it this way to every caller, the CLI included
(their saved_facts too); the stored page is unchanged.
Over MCP (any caller that is not the trusted local CLI) the other reads
quote the same text (#8042). recall quotes its results and each quoted
fact's fact (with quoted), and so do delta facts, context_pack and
_meta.brain_hot_memory. get_page on such a page returns
quoted: "transcript" with compiled_truth, timeline, content and
every window's text each fenced. Its reading shapes (compiled_truth,
timeline, view: read windows) and fetch's text also have a
conversation page's tool-call blocks summarized, as search does. include_content
and view: markdown keep the stored text byte-exact inside the fence, so
edit_page old_text copied from inside a fence still matches, and
put_page given that content back removes exactly the fences get_page
added around this page before writing (a fence-like text in an owner-tier
note's stored body is kept; a whole-markdown read whose closing fence the edit replaced or appended past, or whose line endings it converted to CRLF, is unfenced too,
as is one with blank lines added before its marker, and a backtick code block the edit added inside, in place of or after the read
is kept whole). A remote put_page whose content holds a
tool-call summary that a whole read of the stored page never produces, or
that keeps fewer of a summarized call than the stored page holds, is
refused with invalid_params and stores nothing; a summary inside a kept call's
arguments, or a new turn that quotes a summary while every call stays, is
written. get_page with
known_as_of and get_versions with include_body (and its diff) fence
the recorded bodies of these pages the same way. fetch quotes text the
same way (metadata.quoted). search_exact and get_chunks quote their
text too and summarize tool calls on conversation pages; get_timeline
quotes its entries. The
trusted local CLI (gbrain get, gbrain put) reads and writes the body as
stored.
Over MCP, text is also quoted by its stored trust tier: anything below "your
notes" (written by an agent, tool data, external, or unverified origin) comes
back quoted on search, query, recall, assemble_evidence, get_page
(title and frontmatter included; include_content fences the whole markdown),
fetch, get_timeline, chronicle_day, chronicle_since,
chronicle_on_this_day, volunteer_chronicle (its ontology values too), ontology_get, ontology_conflicts, takes_list, takes_search (claim and source),
where a timeline row's free-text source is quoted with its summary and detail,
get_chunks, search_exact, get_versions, known_as_of, think's extractive
answer, context_pack, hot memory and write receipts. The context gbrain's
hooks inject (the per-turn hook and the pushed context pack) quotes facts below
the owner's tier the same way, so hook output can hold quote fences. A fact or
timeline entry an agent copies back from a quoted read into remember or
add_timeline_entry (its source too), an ontology value copied into ontology_propose, or a claim or source copied
into takes_add, takes_update or takes_supersede, is stored without the fence. A note saved before gbrain
tracked trust reads as unverified, so it is quoted until the owner runs
gbrain trust claim-sources or gbrain trust backfill (gbrain doctor names how
many pages that is); a remote get_page or fetch of such a page carries a
quoted_unverified_origin notice naming those commands, once per session. A quoted page's title is quoted on
get_page, fetch and search and query rows, and its tags on get_page, fetch and get_tags (add_tag and
remove_tag take a copied tag without the fence); a context card below "your notes" carries its title under the
card's trust label, as its summary does; a chronicle entry's kind is quoted by its event page's tier. Local reads are unchanged.
effective_date is the page's own date and effective_date_source says
which kind: date, published or filename is a document date,
event_date an event date, and created or fallback only when the page
was created or imported. It is never a contract's effective or validity
date; that date is in the text. Every reply with dated rows adds one line
after the rows that says so ([gbrain dates] ...).
{"query": "acme-example renewal terms"}
[{"slug":"contracts/acme-example-msa","title":"MSA: Acme Example","type":"contract","chunk_text":"Payment terms: Net 45. Renewal is annual.","chunk_id":812,"score":0.91,"source_id":"default","effective_date":"2026-04-02","id":"gbrain-page:v1:WyJkZWZhdWx0IiwiY29udHJhY3RzL2FjbWUtZXhhbXBsZS1tc2EiXQ","evidence":"keyword_exact","create_safety":"probable"}]
Pass fields: "full" to get every field (page_id, chunk_index,
chunk_source, keyword_hit, cosine, base_score, boosts, rerank and
graph signals, the full delivered object):
{"query": "acme-example renewal terms", "fields": "full"}
_meta.retrieval.rows reports "lean" or "full" for every remote call.
| Client | Rows by default | How to get full rows |
|---|---|---|
| Any MCP client (stdio or HTTP) | lean | fields: "full" per call, or the host sets gbrain config set mcp.result_rows full |
| gbrain thin CLI, v0.60.44.0 or later | full (it sends X-Gbrain-Client) |
nothing to do |
| gbrain thin CLI, older than v0.60.44.0 | lean | upgrade the CLI, or the host sets mcp.result_rows full |
Trusted local CLI (gbrain search, gbrain call) |
full | nothing to do |
The host setting is read per request over OAuth HTTP and at start-up for
gbrain serve (stdio), so restart a stdio server after changing it. The
X-Gbrain-Client header selects a row shape only; it is not an identity
claim and never grants access.
Say to your agent: "Search my brain for the acme-example renewal terms and show me every ranking field for the top result."
Fact rows in query
query can return saved facts as rows of their own, after the page rows and
only in slots and token budget the pages left free. A fact row is not a page.
It has result_type: "fact" and fact_id, and no slug, id, type or
chunk_id, so it can't be passed to get_page, fetch or
assemble_evidence. follow_up names the call that returns the fact:
recall with the fact's entity, or with a grep of its text when it has no
entity. page_slug is present only when the caller can read the entity's page;
pass it to get_page.
{"result_type":"fact","fact_id":"412","page_slug":"companies/acme-example","follow_up":{"op":"recall","args":{"entity":"companies/acme-example"}},"title":"Saved fact about companies/acme-example","chunk_text":"Saved fact (fact; valid from 2026-09-01; provenance: user update): The billing contact for Acme Example is Bob.","score":0.42,"source_id":"default"}
search.query_facts_arm=false turns these rows off. A query that passes
token_budget instead gets the facts block (on by default): dated fact rows
(copies of one claim take one row, followed by (stated N times, last DATE)),
oldest first, ahead of the pages, within 22% of the budget and at most 40 rows
and at most limit rows, in place of the facts arm. Block rows carry the top
page's score: they are placed first, not ranked above the pages, so read
result_type rather than comparing scores. Without token_budget, fact
rows only fill free slots, so limit caps the whole result.
search.query_facts_block=false restores the arm.
Recent facts in _meta.brain_hot_memory
Most successful tool calls carry _meta.brain_hot_memory: up to 10 recent
facts from the connection's own source. For a token, that is its write source,
the first id of its source grant. For a member token whose first source is the
member's private source, the block holds that member's own facts. A harness
that answers a channel or other shared session should send
_meta.hot_memory: "off" with each call, on the request beside arguments
or inside the arguments, so those facts can't ride into a reply other people
read. Without it, the block is unchanged. When it appears and which facts it
holds: MCP_META_CHANNELS.md.