Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.0 KB
Raw Blame

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: call fix.mcp (or run fix.argv where you have a shell) exactly as given.
  • ask_user: relay user_message and 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 them fix.command.
  • wait: retry after the stated delay with the same request.
  • report: tell the user what happened; the host operator runs gbrain 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.