Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
72.2 KB
Raw Blame

MCP tool reference (starter surface)

The tool descriptions an MCP client receives are kept short, because every connected agent pays for the whole tool list on every turn. This page keeps the longer guidance for people: what each starter-surface tool does, its defaults, and the edge cases behind each parameter. The served schemas remain the contract; when they and this page differ, the schemas win.

The starter surface lists the parameters an agent needs for the common call. Local-only, admin, legacy and tuning parameters stay callable on every surface, and request_tools {tools: ["name"]} returns a tool's full schema with every optional parameter.

Say to your agent: "Before you call a gbrain tool you have not used yet, check docs/mcp/TOOL_REFERENCE.md for its defaults."

Search and query rows are lean for remote callers by default; see Search and query result rows. The fields parameter on search and query (lean or full) selects the row shape per call.

add_timeline_entry

Append an entry to the canonical Markdown timeline and structured timeline store in one committed write. Exact replay changes neither store. The receipt returns bullet, the rendered Markdown line. Entries a dream patterns child appends are quote-verified against that run's reflections; an entry whose quote is not found moves to the page's unverified_claims, and the phase result counts the page in patterns_written (appended_unverified there is a deprecated alias, removed two releases after fix wave 18b). There is no update or remove verb: the page is the system of record, so to change or remove an entry read the page with get_page include_content: true, replace or delete that bullet with edit_page (passing expected_revision), and the timeline row follows the page.

Parameter Type Guidance
request_id string Optional caller-generated UUID for this write. Reuse the same UUID and original arguments to recover its outcome after a timeout; a different intent requires a new UUID.
slug (required) string Slug of the page whose timeline to append to.
date (required) string Entry date, strict YYYY-MM-DD (e.g. '2026-04-03'). Timestamps and non-calendar dates are rejected.
summary (required) string One-line summary of what happened on that date.
detail string Longer free-text detail behind the summary.
source string Provenance ref for the entry, e.g. a meeting slug like 'meetings/2026-04-03' or a URL.

cancel_job

Cancel a waiting, active, or delayed job. Agent-scoped tokens (no admin) can cancel only jobs they own.

Parameter Type Guidance
id (required) number Job ID

cancel_write_request

Cancel your accepted write before publication starts. Returns the actual receipt: running/recovering or already-terminal requests may remain unchanged. Cancellation cannot undo published bytes or a committed fact withdrawal.

Parameter Type Guidance
request_id (required) string The original request UUID. Only this principal’s currently authorized requests are accessible.

capture

Capture a quick note into the brain — the "just remember this" write. Auto-derives a stable inbox/ slug from the content date + hash (recapturing identical text is idempotent), merges frontmatter, refuses binary/empty payloads, then delegates to put_page (inheriting its fences and provenance stamping). Prefer capture for quick notes and put_page when you need to control the slug, type, or an existing page's content. For structured facts about entities, prefer remember.

Parameter Type Guidance
source_id string Source to mutate. Defaults to the selected source. Remote callers may only use their current write source.
expected_revision string Revision returned by the page read. Required when replacing an existing page unless force is true. Omit both for create-only writes. Carry the read's source_id with it: if this revision is the current revision of the same slug in another source you can read, the revision_conflict refusal names that source and its fix re-reads the page there.
force boolean Explicitly overwrite the current revision. Mutually exclusive with expected_revision; does not bypass authorization or the empty-content guard.
request_id string Optional caller-generated UUID for this write. Reuse the same UUID and original arguments to recover its outcome after a timeout; a different intent requires a new UUID.
content_origin string (user_said, tool_output, inferred) Where the content came from. tool_output (web page, email, file or other tool text) stores the write as external, untrusted; user_said and inferred store it as written by an agent. Advertised on the verbs and full surfaces only; a starter client that passes it is still honored.
who string For event captures, comma-separated entity slugs.
what string For event captures, the event description.
where string For event captures, the location.
kind string For event captures, the event kind.
depth string For event captures, the depth page to link.
content (required) string Markdown or plain text to capture. File paths are NOT accepted over MCP — read the file yourself and pass its content (the CLI --file lane is local-only).
local_file string Trusted local CLI only (--file): the absolute path of the captured file. Recorded as the page origin only when it lies inside the source and names the slug; the path itself is never stored. Remote callers are refused.
slug string Target slug. Default: inbox/YYYY-MM-DD- (stable per content — recapturing identical text hits the same slug); type diary/event routes under life/. Fenced clients: the default lands under your first bound prefix.
type string Page type for the stamped frontmatter. Omitted: the content's frontmatter type: when present, else 'note'. An explicit type (this param or a frontmatter type:) must be declared by the active schema pack; undeclared types are rejected before writing, naming the declared vocabulary.

context_pack

MEMORY VERB (v1): budget-packed session-boundary bundle for a set of standing entities — entity cards + open threads + hot facts, zero-LLM, sub-second. Call at session start (warm cold context) and after compaction (rehydrate what the summary lost). WORLD-ONLY by default; pass include_private (honored for LOCAL trusted callers only) to widen all arms. budget_tokens packs server-side (response reports budget_used + dropped_count; cards pack first, then facts). Branch on structured fields, never prose. protocol_version rides every response.

Parameter Type Guidance
entities (required) string Comma-separated entity names/slugs to bundle. Capped at 8.
budget_tokens number Server-side token budget (char/4). Cards pack first, then facts; each item costs its rendered line and the envelope + section headers are reserved, so text fits the budget. Response adds budget_tokens, budget_used (tokens of text), dropped_count.
since string ISO 8601 datetime. When set, open-thread events are filtered to those after this cursor.
session_id string Opaque session id; keys the hot-memory cache and (on the push path) the session cursor.
include_private boolean Local trusted callers only: widen ALL arms to include private facts. Ignored (world-only) for remote callers. Default false.

Each card may carry newer_mentions (since, rows of date/slug/title/preview, more): the newest pages dated after the entity's own page that mention it, at most 8 rows and 2,000 characters per card, rendered in text after hot memory. They follow the entity card's read policy and pack last under budget_tokens. Off with mentions.newer_on_cards false.

The card and each newer_mentions row carry page_status when that page's frontmatter sets status (a string up to 40 characters, never inferred; the convention for a record not yet in force is draft or unsigned). Structured rows only; text is unchanged. Off with entity.row_page_status false; records rows keep theirs.

delta

MEMORY VERB (v1): "what changed since T" for heartbeats — pages updated after since + hot facts newer than since + open-thread events after since, zero-LLM. Lets a periodic wake maintain warm state in O(changes) instead of re-deriving. Optionally scope thread deltas to entities. WORLD-ONLY by default; include_private honored for local trusted callers only. budget_tokens packs server-side (pages first, then facts; threads are never dropped). protocol_version rides every response.

Parameter Type Guidance
since string ISO 8601 cursor. Returns pages/facts/thread-events newer than this timestamp. Optional when session_id carries an established cursor.
since_slug string Stateless keyset resume: pass back next_cursor.slug from the previous response (paired with since=next_cursor.since) to page through pages sharing one timestamp. Ignored when session_id is set (the session cursor carries it).
entities string Optional comma-separated entity scope for thread-event deltas. Capped at 8.
budget_tokens number Server-side token budget (char/4). Pages pack first, then facts; each item costs its rendered line and the envelope + section headers + every thread line are reserved, so text fits the budget. Threads are never dropped (budget_used can exceed the budget only when the header + threads alone do). Response adds budget_tokens, budget_used (tokens of text), dropped_count.
session_id string Opaque session id. Drives the per-session cursor: the first call establishes it, each call advances it to the newest DELIVERED change (at-least-once — with has_more:true the undelivered tail returns on the next wake). Without it, pass an explicit since for a stateless delta.
include_private boolean Local trusted callers only: widen ALL arms to include private facts. Ignored (world-only) for remote callers. Default false.

edit_page

Change part of an existing page without resending it: prefer this over put_page for small changes to large pages. Read get_page with include_content:true and pass its revision as expected_revision. Each edit replaces old_text with new_text; edits apply in order, each to the text the previous edit produced, and each old_text must match exactly once in that content. Protected takes and facts sections never match (use the takes_* operations or remember/forget). All edits publish together or none do, through the same receipts, fences and write-through as put_page. Returns the new revision and a unified diff of your view (at most 8 KB). Refusals name the edit: edit_no_match, edit_ambiguous_match (with match_count), edit_protected_span, edit_invalid; a stale revision returns revision_conflict with current_revision. Retain request_id and repeat identical arguments after a pending receipt.

Parameter Type Guidance
slug (required) string Slug of the existing page to edit.
expected_revision (required) string The revision from get_page include_content:true. The edit is refused if the page changed since.
edits (required) array 1 to 50 replacements, applied in order and all or nothing.
source_id string Source to mutate. Defaults to the selected source. Remote callers may only use their current write source.
request_id string Optional caller-generated UUID for this write. Reuse the same UUID and original arguments to recover its outcome after a timeout; a different intent requires a new UUID.

entity

MEMORY VERB (v1): inspect ONE known person/company/project card — zero LLM calls, sub-100ms. Resolution: alias > exact title > slug-suffix; ties break on most-recently-touched. NEVER errors on a miss: returns found:false plus near-miss suggestions with create_safety hints (exists | probable | unknown — whether writing a new page would duplicate). Routing: for facts/snippets retrieval use recall; for broad questions needing reasoning use synthesize (expensive).

Parameter Type Guidance
name (required) string Free-text name, alias, or slug (e.g. "Alice Example", "people/alice-example").

find_anomalies

Returns statistical anomalies in recent page activity, grouped by cohort (tag or type). Use this for questions about what stood out, what's unusual, or what changed recently. Returns explanatory cohorts (e.g. '15 pages tagged wedding touched on 2026-04-28, baseline 0.3/day') so you can speak about patterns the user wouldn't have searched for. Cohort kinds: tag, type. Year cohort is deferred to a later release.

Parameter Type Guidance
since string ISO date YYYY-MM-DD. Default = today (UTC).
lookback_days number Days of history for the baseline. Default 30.
sigma number Sigma threshold. Default 3.0.

forget

MEMORY VERB (v1): expire a remembered fact by id — the protocol delete verb. id is the opaque string id returned by remember and recall (facts[].fact_id) — never a page slug. Idempotent: forgetting an already-expired fact returns expired:false (success), unknown id returns a not_found error. The fact is expired (audit trail kept), not deleted.

Parameter Type Guidance
request_id string Optional caller-generated UUID for this write. Reuse the same UUID and original arguments to recover its outcome after a timeout; a different intent requires a new UUID.
id (required) string Opaque fact id from remember/recall (facts[].fact_id). Never a page slug.
reason string Optional reason, written to the fact's audit trail. Default: "forgotten".

get_agent_job

Poll an agent job submitted via submit_agent. Returns a trimmed status view (id, status, timestamps, error_text, result) plus queue_position (waiting jobs ahead in claim order; 0 = next) while the job is still waiting. Requires the agent OAuth scope; only jobs owned by the calling client are visible.

Parameter Type Guidance
id (required) number Job id returned by submit_agent

get_backlinks

List incoming links to a page

Link rows come 500 per call by default (limit, up to 5000), in link order. When more match, the last row carries truncated: true and next_cursor; pass it back as cursor with the same parameters for the next rows (a cursor from another listing is refused link_cursor_invalid). get_links pages the same way. Each row's context is cut to 2000 characters, ending in an ellipsis.

Each link row and each group: "page" row carries page_status, the referring page's frontmatter status, when set (a string up to 40 characters; never inferred). The link row's own status is the relationship's temporal state and the status filter acts on that. Off with entity.row_page_status false; a record type's continuation keeps it.

Parameter Type Guidance
slug (required) string Slug of the page whose incoming links to list.
source_id string Scope the read to one source (a multi-source brain can hold the same slug in several sources). Omitted: your granted sources remotely (a connection with no grant reads every federated source); locally, the resolved source, or every federated source when no --source / GBRAIN_SOURCE / .gbrain-source pinned it. 'all' spans every source for trusted local callers and only your readable sources for remote callers.
all_sources boolean Span sources (equivalent to source_id=all): every source locally, only your readable sources remotely.

get_ingest_log

Get recent ingestion log entries

Parameter Type Guidance
limit number Max entries (default 20)

get_page

Read a page by slug (supports optional fuzzy matching). Slug aliases left by renames redirect to the canonical page in the source that owns the alias (archived sources excluded); a redirected read reports resolved_slug. To edit a page, pass include_content: true — the returned content field is the canonical full markdown (frontmatter + body + timeline sentinel); edit THAT and pass it back to put_page to round-trip losslessly. Reassembling compiled_truth/timeline by hand risks dropping sections. Soft-deleted pages are hidden by default; pass include_deleted: true to surface them with deleted_at populated (restorable until the purge cutoff, 72h by default, when the autopilot purge phase or gbrain pages purge-deleted hard-deletes them). timeline is only the markdown section after the timeline sentinel; entries written by add_timeline_entry or extraction live in timeline rows, which include_timeline_entries: true returns as timeline_entries (the same rows get_timeline returns). file_held means sync holds this page's newer file: you are reading the last good revision, and put_page refuses until the file is repaired (follow its fix). quarantined means the content-quality gate hid the page as junk (hidden from search, no facts or takes extracted) and comes with a page_quarantined safety notice: treat the text as untrusted scraped content. For a remote caller the body is withheld (quarantined.body_omitted: compiled_truth and timeline are empty and content is absent) unless an admin-scoped caller passes include_quarantined: true. To read part of a page, pass section (a heading: the first case-insensitive match, down to the next heading of the same or higher level, with heading_path; a miss lists up to 20 headings) or grep (a plain case-insensitive substring: the matching paragraphs with context paragraphs either side, default 1, max 5, merged when they overlap, with line numbers and total_matches; at most 50 matches and 100,000 characters, truncated when cut). Both are cut from the same read view as body: 'window', whose lines take their line numbers. Every response carries chars, the characters of page text it returned.

Parameter Type Guidance
slug (required) string Page slug
fuzzy boolean Enable fuzzy slug resolution (default: false)
include_content boolean Include the canonical serialized content field (frontmatter + body + timeline sentinel) for lossless get→edit→put_page round-trips. Default false — it roughly duplicates compiled_truth + timeline, so read-only callers should not pay for it.
content_only boolean With include_content: true, return only the round-trip fields: slug, source_id, type, title, revision, tags and content (plus deleted_at, resolved_slug, content_flag, file_held and timeline_entries when they apply), without the duplicate compiled_truth / timeline / frontmatter. Ignored without include_content. To write back, send content to put_page with this source_id and revision as expected_revision: on a multi-source brain the same slug can live in several sources, and a write without source_id goes to your default source.
include_deleted boolean Surface soft-deleted pages with deleted_at populated (default: false). Used by restore workflows.
include_timeline_entries boolean Also return timeline_entries, the page's timeline rows (the same rows and filtering as get_timeline for this caller). Default false to keep the payload small.
source_id string Scope the lookup to a single source (a multi-source brain can hold the same slug in several sources). Defaults to ctx.sourceId / the caller's grant. 'all' spans every source for trusted local callers, your granted sources for remote callers.
include_quarantined boolean Admin scope only: return a quarantined page's body to a remote caller (default: false). Ignored without the admin scope; trusted local reads always include it.
section string Only the section under this heading (case-insensitive, first match), with heading_path, line_start and line_end. Accepted on the starter surface; advertised on full.
grep string Only the paragraphs containing this text (case-insensitive substring, not a regex), with line numbers and total_matches. Accepted on the starter surface; advertised on full.
context number Applies only with grep (ignored without it): paragraphs of context either side (default 1, max 5).

The window parameters (lines, bytes, around_chunk_id, cursor) are advertised on the full surface. With several, one window is read: cursor, then around_chunk_id, then lines, then bytes (a cursor that can't read this page and an around_chunk_id no longer on it give way to the next, and view: "markdown" sets around_chunk_id aside beside another selector), and body: "full", include_content and content_only beside a selector are set aside. The response's window_selector names what applied and what was ignored.

get_recent_salience

Returns readable pages recently touched and ranked by activity salience and recency. Unrestricted local reads include deterministic 0..1 emotional_weight, take density, and recency decay. Holder-restricted reads count only permitted active takes, use zero emotional_weight, and select recent pages by updated_at; unrestricted local reads retain take-driven touches. Use this when the user asks what's been going on, what's notable, what's hot, anything crazy happening, or for any open-ended 'current state' question about themselves or their work. Do NOT run a semantic search for these — salience surfaces what's unusual without needing a search term.

Parameter Type Guidance
days number Window in days. Default 14.
limit number Max results (default 20, capped at 100).
slugPrefix string Optional slug-prefix filter, e.g. 'personal' or 'wiki/people'.
recency_bias string (flat, on) How to weight recency in the salience score.
'flat' (DEFAULT) — every page gets 1/(1+days_old).
Stable, predictable; what most callers want.
'on' — Per-prefix decay map. concepts/originals/writing/
become evergreen (recency component = 0); daily/,
media/x/, chat/ decay aggressively. Use when the
user explicitly biases for recency-aware salience
('what's been salient lately' vs 'what matters
in this brain regardless of when').

get_skill

Fetch one skill's full instructions by name. Returns {name, frontmatter (sanitized), body, usable_tools, unavailable_tools, client_guidance}. The body is prose — read it as your operating instructions for this task, and when it says to search / store / look something up, call the same-named MCP tool on THIS server. There is nothing to 'execute' — the value is the instructions plus your tool calls back to this server. Tools listed in unavailable_tools won't work for you (not exposed here, or beyond your access) — adapt accordingly. Size-capped; read-scope; requires the owner to have enabled mcp.publish_skills. On a shared brain, pass schema_version:2 with qualified_id and revision from discovery to fetch exact instructions and their approved dependency manifest. get_skill_asset retrieves declared files from that revision as data; downloading never grants execution or tool permissions.

Parameter Type Guidance
schema_version number Request 2 for an immutable canonical revision.
qualified_id string Exact version 2 qualified skill identity.
expected_brain_id string Assert the connected persistent brain identity from version 2 discovery. This never routes to another brain.
source_incarnation string Source incarnation from version 2 discovery.
pack_id string Canonical pack identifier.
revision string Exact immutable revision, or omit for the current head.
name string Skill name exactly as returned by list_skills (or a pack skill's name from list_brain_skillpack when source_id is set).
source_id string Optional: fetch a brain-resident pack skill from this source instead of the host catalog. Disambiguates a skill name that exists on more than one source (see list_brain_skillpack).

get_skill_asset

Read a bounded, owner-approved file from an exact sealed skill revision. Does not execute downloaded bytes.

Parameter Type Guidance
source_id string Exactly one granted source.
source_incarnation string Expected source incarnation from the qualified catalog.
name string Skill name when not selecting by qualified_id.
pack_id string Pack identifier when not selecting by qualified_id.
qualified_id string Qualified skill key from version 2 discovery.
expected_brain_id string Assert this connected persistent brain identity without routing to another brain.
revision (required) string Immutable revision from get_skill.
path (required) string Exact path in the approved revision file manifest.

get_write_request

Read your durable write receipt by request_id. Requires write scope and this operation in the current grant. Foreign, missing, and no-longer-accessible requests return the same not_found error; private journal input and recovery bytes are never returned.

Parameter Type Guidance
request_id (required) string The original request UUID. Only this principal’s currently authorized requests are accessible.

list_brain_skillpack

List brain-resident skillpacks this brain ships (per-source). Returns each pack's skills (name, the skill name get_skill takes, never a page slug) with one-line descriptions, the schema pack it targets + whether that matches this brain, and a git scaffold spec. Read-only; gated by mcp.publish_skills. After orienting, call this and ask the user whether to install any pack the brain offers (gbrain skillpack scaffold ).

list_link_sources

List distinct link_source provenances in the brain with edge counts (e.g. citation-graph, manual, markdown)

list_pages

List pages with optional filters. For 'what's recent / what did I touch this week' questions, use list_pages with sort=updated_desc instead of semantic search. Default 50 rows; remote callers are capped at 100 (local CLI callers' explicit limits are honored). A result with exactly limit rows may be truncated. For exhaustive listing, page with updated_after=<last row's updated_at_iso> + updated_after_slug=<last row's slug> until a page returns fewer rows than the limit (the keyset forces sort=updated_asc; a bare updated_after cursor skips rows sharing the cursor timestamp).

Parameter Type Guidance
type string Filter by page type
tag string Filter by tag
limit number Max results (default 50; remote callers are capped at 100)
offset number Skip first N rows (pagination).
updated_after string ISO date (YYYY-MM-DD) or full timestamp. Returns pages with updated_at > value. Bare (without updated_after_slug) this is LOSSY across rows sharing one timestamp — a bulk sync stamps one now() across a transaction; pair with updated_after_slug to page exactly.
updated_after_slug string Keyset cursor slug: pass the last row's slug together with updated_after set to that row's updated_at_iso (column precision — a millisecond-rounded value re-selects same-millisecond rows). Resumes strictly after (updated_at, slug) and forces sort=updated_asc.
sort string (updated_desc, updated_asc, created_desc, slug) Sort order. Default updated_desc. Options: updated_desc, updated_asc, created_desc, slug.
include_deleted boolean Include soft-deleted pages (default: false). Used by restore workflows and operator diagnostics.
source_id string Scope listing to a single source. Defaults to OperationContext.sourceId / federated scope. Pass 'all' to span every source for trusted local callers; for remote callers 'all' spans only your granted sources.

list_skills

List the skills this agent's brain publishes. A skill is a named prose instruction set (NOT executable code) that teaches you how to do a task using this server's other tools. Returns a flat catalog — each entry has a name, one-line description, triggers (phrasings that should invoke it), and usable_tools / unavailable_tools (which tools the skill calls that you CAN vs CANNOT call given this server + your access). To actually use a skill, call get_skill with its name, read the returned prose, and follow it — calling the correspondingly-named tools on THIS server. The response also carries an instructions envelope explaining this protocol. On a shared brain, use schema_version:2 for source-qualified identities, immutable revisions, pagination and complete declared requirements. Only authorized sources and owner-approved file classes are visible; pre-migration servers retain their legacy prose catalog. Read-scope; published only when the brain owner enabled mcp.publish_skills.

Parameter Type Guidance
schema_version number Request 2 for the canonical source-qualified sealed catalog; omitted preserves version 1.
limit number Version 2 page size, 1-100; with query, how many ranked skills to return (default 10).
cursor string Version 2 opaque snapshot cursor.
source_id string Narrow version 2 enumeration to one permitted source.
section string Optional: only skills whose routing section matches this exactly.
query string Full surface, version 1 host catalog only: the task in plain words. Skills are ranked by word overlap over their name, triggers and description (a whole trigger phrase inside the query counts most, then name words, then description words); skills matching nothing are dropped, ties break by name, limit caps the list, and each kept entry carries match: { score, matched_on: trigger | name | description }. Without query the catalog is unchanged (name order, every skill, no match). On a shared catalog (schema_version: 2, or a brain whose shared catalog is active) query is refused with invalid_params rather than ignored: filter with section there. No model call.

list_write_requests

List your currently authorized write receipts in one source, newest first. Useful when an acknowledgment was lost. Results and pagination exclude other principals and inaccessible targets; no private payloads or cross-principal queue counts are exposed.

Parameter Type Guidance
source_id string Source to inspect. Defaults to the caller’s resolved source.
limit number Number of visible receipts, 1–100. Default 25.
before string Opaque next cursor from the previous response.

list_write_conflicts

Pages whose writes keep ending in a source_changed conflict, grouped by slug (#6643): receipt counts, drift receipts (file_database_drift), first and last seen, producers, and the last committed write's time. Remote callers get database-derived fields only, filtered by their source grant, slug fence and page visibility before anything is counted; whether the canonical file still differs (still_present) is checked only for the trusted local CLI on the canonical owner host and reads { value: null, reason: "remote_caller" } here. A source_id outside the caller's grant is refused permission_denied, whether or not that source exists. The window sequences are bounded by the source's own requests (its current incarnation), so they say nothing about writes in other sources. Read-only. The resolution is a host-side, explicit-only repair (gbrain repair file-drift), so relay next_actions to the brain host's operator.

Parameter Type Guidance
source_id string Source to inspect. Defaults to the caller's resolved source.
limit number Number of slugs, 1-100. Default 25.
cursor string The previous response's next.

put_page

Replace a complete canonical Markdown page. Read get_page with include_content:true and pass its revision as expected_revision; force explicitly overwrites the current revision. Omitting both permits creation only. Retain a UUID request_id and repeat identical arguments after transport failure or a pending receipt. Content, tags, sanitized text projections, versions and the committed receipt publish together; embedding and optional Git effects have separate status. Remote callers preserve protected facts/takes fences. For remote writes, [[wikilinks]] and markdown links in the body that point at pages already in the same source become plain mentions links after the commit (a journaled links effect; the receipt's auto_links.mention_links says it is queued; mcp.remote_auto_links false turns it off). Typed and frontmatter links are skipped for untrusted writes: a stdio gbrain serve sweeps them at startup + on idle; gbrain serve --http does not self-sweep — run gbrain sweep --once or use trusted local capture/put_page for inline link extraction. Pass wait_ms (up to 30000) to hold the reply until the commit instead of polling get_write_request. For more than 3 pages, use put_pages (full surface). To add to the end of a log or conversation, use append_page instead of re-sending the page, and send a page larger than one request through an upload session (begin_page_upload, upload_page_part, commit_page_upload); both are on the full surface (adding to a large page). Remote callers receive write_through.warning when no repo is configured. For file input use gbrain capture --file PATH --slug SLUG. A write the content-quality gate quarantined still commits but reports quarantined: { reason, detail } with a page_quarantined safety notice (put_pages marks each such page and emits one notice).

Parameter Type Guidance
source_id string Source to mutate. Defaults to the selected source. Remote callers may only use their current write source.
expected_revision string Revision returned by the page read. Required when replacing an existing page unless force is true. Omit both for create-only writes.
force boolean Explicitly overwrite the current revision. Mutually exclusive with expected_revision; does not bypass authorization or the empty-content guard.
request_id string Optional caller-generated UUID for this write. Reuse the same UUID and original arguments to recover its outcome after a timeout; a different intent requires a new UUID.
content_origin string (user_said, tool_output, inferred) Where the content came from. tool_output (web page, email, file or other tool text) stores the write as external, untrusted; user_said and inferred store it as written by an agent. Advertised on the verbs and full surfaces only; a starter client that passes it is still honored.
slug (required) string Page slug
content (required) string Complete markdown content with YAML frontmatter. REPLACES the entire page; this is not a partial edit. Read the canonical page first with get_page include_content:true before modifying it.
allow_empty boolean Allow overwriting an existing non-empty page with empty/whitespace-only content (default: false). Without it, put_page rejects the empty overwrite — the empty-stdin failure class.
wait_ms number How long the reply waits for the commit, counted from arrival: 0-30000 ms, default 5000. Not part of the write's identity, so a replay with a different wait is still the same write. Out of range refuses with invalid_write_wait before anything is admitted.
source_kind string Ingestion channel taxonomy (capture-cli | put_page | webhook | …). Remote callers: SERVER-STAMPED, client value ignored.
source_uri string Original URI/path/message-id the event carried. Remote callers: SERVER-STAMPED null.
ingested_via string Richer label paired with source_kind. Remote callers: SERVER-STAMPED.

query

Hybrid search with vector + keyword, plus multi-query expansion when the search mode or the call asks for it (expand unset follows search.expansion, off by default in all three modes; expand: true forces it). Prefer query for concept / synonym / landscape questions ('all the X that do Y', 'the landscape of Z'); expansion can recover synonym- and outcome-phrased matches a single embedding misses. Still top-K, and the default count when limit is omitted depends on the configured search mode (10 conservative / 25 balanced / 50 tokenmax — see the limit param description); pass limit explicitly for a stable count regardless of mode. When the answer needs the surrounding conversation or section, pass return_unit ('page' / 'section' / 'window') to get that evidence in one call instead of get_page per hit; conversation pages already come back whole by default (return_unit 'auto'; 'chunk' opts out). For exhaustive enumeration use list_pages; for exact known tokens search is cheaper (it never expands). For personal/emotional questions ('what's going on with me', 'anything notable', 'how am I feeling'), prefer get_recent_salience, find_anomalies, or get_recent_transcripts. Semantic search returns polished pages and misses recent activity bursts. Do NOT assume words like 'crazy', 'notable', or 'big' mean impressive — they often mean difficult or emotionally charged. Rows with result_type: "fact" are saved facts, not pages: they have no slug or id; follow follow_up (a recall call), or pass page_slug to get_page when it is present.

Parameter Type Guidance
query string Question or topic text for hybrid retrieval (e.g. 'agents that do web research'). This is the search text param — there is no text or q param. Optional ONLY because image is the alternative entry point; a call with neither fails with invalid_params.
image string Base64-encoded image bytes for image-similarity search (CLI: --image
image_mime string MIME type for the image bytes (auto-derived from path on CLI; required when calling op directly).
limit number Max results. Omitted or 0 resolves from the active search mode (10 conservative / 25 balanced / 50 tokenmax by default, or the configured search.searchLimit override) — for both text queries and image-similarity queries (image param).
offset number Skip first N results (for pagination)
types array Filter results to pages whose type is in this list (e.g. ['person','company']). CLI: --types person,company. Applied at SQL level on every retrieval leg — the same filter whoknows uses. Stacks with all other filters.
snippet_chars number Cap each result's chunk_text at N characters (a "… [truncated]" marker names the get_page recovery move). 0 forces full text. Unset: subagent tool loops default to the agent.search_snippet_chars config (300; 0=full); every other caller gets full text. A row widened by search.long_page_unit (delivered: {unit, reason: "long_page"}) is exempt and comes back whole; every other row is still cut.
return_unit string (chunk, window, section, page, auto) Evidence unit returned in each result's chunk_text (default: config search.return_unit, which defaults to 'auto').
'chunk' — the ranked chunk only (~300-450 tokens per result).
'window' — the hit chunk plus return_window neighbor chunks each side (local context, ~3x chunk).
'section' — the enclosing markdown section, or the conversation rounds around the hit.
'page' — the whole page/session, capped. Use for multi-session or temporal questions where the answer needs the whole conversation.
'auto' — the whole page for conversation pages (conversation/transcript/chat/meeting/slack/imessage types, chat/ or conversations/ slugs), the ranked chunk unchanged for everything else. When no hit is a conversation the response is exactly the chunk response.
Non-chunk units return one result per page, packed into token_budget (default 6000, auto 24000; remote max 32000), with a delivered object (unit, chunk_ids, match_spans, tokens, truncated; reason under auto) per result and delivery in the response meta.
return_window number Neighbor chunks on each side for return_unit 'window' (integer 1-3, default 1).
token_budget number Token budget. Chunk mode, and whenever return_unit is omitted: caps the cumulative chunk payload (results that would overflow are skipped); with search.query_budget_unit=auto (default chunk), an omitted return_unit delivers evidence under the budget as a hard cap instead, and a budget below 32 is refused. Explicit non-chunk return_unit: the budget for delivered evidence (default search.return_budget_default = 6000, auto 24000; remote max search.return_budget_max_remote = 32000).
expand boolean Multi-query expansion. Unset follows search.expansion (off by default in all three modes); true forces it, false skips it. Requires configured embedding and expansion providers; a cloud expander receives the query and may charge for the call. Response metadata expansion_applied reports whether variants were actually used.
detail string Result detail level: low (compiled truth only), medium (default, all with dedup), high (all chunks)
mode string Search mode (conservative|balanced|tokenmax). Local callers only; remote uses configured mode.
lang string Filter to chunks where content_chunks.language matches (e.g., typescript, python, ruby)
symbol_kind string Filter to chunks where content_chunks.symbol_type matches (e.g., function, class, method, type, interface)
near_symbol string Anchor retrieval at this qualified symbol name (e.g., BrainEngine.searchKeyword). Enables A2 two-pass.
walk_depth number Structural walk depth 1-2. Default 0 (off). Expands anchors through code_edges with 1/(1+hop) decay.
salience string (off, on, strong) Salience boost — emotional_weight + take_count, NO time component.
'off' — default for entity / canonical / definitional queries
'on' — surface emotionally-weighted + take-rich pages
'strong' — aggressive mattering tilt
Omit and gbrain auto-detects from query text. Independent of recency.
recency string (off, on, strong) Recency boost — per-prefix age decay, NO mattering signal.
'off' — default for canonical truth
'on' — daily/, media/x/, chat/ decay aggressively; concepts/, originals/, writing/ stay evergreen
'strong' — multiplies the recency factor by 1.5 (use for 'today' / 'right now')
Omit and gbrain auto-detects. Independent of salience (orthogonal axes).
since string Filter to pages whose effective_date is >= this. ISO-8601 (YYYY-MM-DD or full timestamp) OR relative ('7d', '2w', '1y').
until string Filter to effective_date <= this. Same format as since. YYYY-MM-DD lands at end-of-day.
source_id string Scope search to a single source. Defaults to OperationContext.sourceId (set from CLI --source / GBRAIN_SOURCE / .gbrain-source dotfile). Pass 'all' to span every source for trusted local callers. For remote callers, 'all' uses the same scope as omission: an OAuth grant when present, otherwise the transport-computed federated sources for grantless local stdio.
source_ids array Narrow the request to these sources (CLI: --source-ids source-a,source-b). Each id is authorized like an explicit source_id, so the list can narrow a request but never widen it: a source outside a remote caller's grant refuses the whole request with permission_denied, and a removed or archived one with unknown_source. Omitted, [] or a blank string leaves the request's normal scope (source_id, or your default scope) unchanged; __all__ is refused. With source_id too, the request reads their intersection, and an empty intersection returns no rows with an empty_retrieval notice. See narrowing one request.
cross_modal string (text, image, both, auto) Cross-modal search routing.
'text' (default for non-image-intent queries) — text-only path.
'image' — route the query through Voyage multimodal-3 + the embedding_image column. Best for 'show me photos of...' phrasings.
'both' — run text AND image searches in parallel; merge via weighted RRF.
'auto' — same effect as omitting the field; intent classifier decides based on query phrasing.
embedding_column string Route vector search through a non-default embedding column. Defaults to 'embedding' (the brain's primary column) unless search_embedding_column config sets a different default. Per-call override for A/B benchmarking across providers (e.g. 'embedding_voyage', 'embedding_openai'). Column MUST be declared in the embedding_columns config registry — unknown names throw with a paste-ready hint listing valid columns.
adaptive_return boolean Return a TIGHT, intent-sized result set instead of the full top-K. YOU (the agent) set this per query to serve the user well:
TRUE when the user's question has a small, specific answer — a lookup ('what is X', 'who is Y', 'what's my ', 'what did Z decide'), a single-fact recall, or when you'll route the result into a precise downstream step (a classifier, a decision, an exact citation). The user gets the answer, not a wall of loosely-related pages, and you spend fewer tokens reading noise.
Omit / FALSE for breadth — 'everything about X', 'list all', 'what do I know about Y', exploration, brainstorming, or any time you'd rather see more candidates and judge for yourself. Recall matters more there, so take the full top-K.
Safe by construction: it NEVER returns empty when there are matches (you always get at least the top hit), and it only applies to the first page (omit when paginating). Caps come from config (search.adaptive_return_entity_max / _other_max; default 2 / 6) — pass limit 1 alongside this for a hard single-answer cap.
autocut boolean Cut the ranked results where the relevance score drops off a cliff, so an obvious single answer comes back as 1 result and a genuine handful comes back as that handful, not a fixed wall of 20+. Off by default in every search mode; a brain can turn it on with gbrain config set search.autocut true.
Pass TRUE for a tight, confident set on one call. Pass FALSE to force the full top-K on a brain whose config turned autocut on, when you deliberately want breadth: broad exploration, 'show me everything about X', enumeration, or when you suspect the top hit is wrong.
Safe by construction: never returns empty when there are matches, only applies to the first page (omit when paginating), and is a no-op when no reranker scored the results (so it can't cut on an untrustworthy signal). Distinct from adaptive_return: autocut cuts on the score cliff; adaptive_return caps by question intent. Leave both unset for the brain's configured default.
relational boolean Relational recall arm. SMART DEFAULT (on in balanced/tokenmax). When the question is about a RELATIONSHIP ('who invested in widget-co', 'who introduced me to alice', 'what connects fund-a and fund-b'), the brain resolves the named entity and walks its typed-edge graph (invested_in, works_at, founded, …), surfacing the answer even when no passage mentions both sides. Pure no-op for non-relational questions. Pass FALSE to force lexical/vector-only retrieval (e.g. debugging why a graph answer appeared). You almost never set this.

recall

MEMORY VERB (v1): retrieve saved facts/snippets — the protocol read verb. Filters hot-memory facts by entity / since / session_id, newest first, or ranks them by relevance with question; pass query to ALSO run hybrid search over pages (results[] arm); pass budget_tokens for server-side packing (response reports budget_used + dropped_count — never trims client-side). Remote callers see visibility=world facts only. Routing: for ONE known person/company/project card use entity (zero LLM); for broad questions needing reasoning use synthesize (expensive). Branch on structured fields (status/kind/evidence), never on prose. Every response carries protocol_version.

Parameter Type Guidance
entity string Entity slug (canonical). Returns facts about this entity newest first, each labelled with its source_id. Across several granted sources, same-slug entities that no entity-identity group links are different entities: facts comes back empty and ambiguous_entity names each (source_id, entity_slug); pass source_id to read one.
question string Ranks active facts by relevance to this question (cosine to its embedding plus term share, with words matched on their stems and dates, years and auxiliary verbs ignored, +0.1 for a writer-dated fact) instead of newest first. Facts below the admission rule are left out, so an empty facts[] is a valid answer. Each fact carries relevance (a ranking score, about 0 to 2.1, not comparable across calls); the response carries facts_order: "relevance" and, when ranking ran without full semantic matching, facts_degraded. When semantic matching ran on an embedding model whose fact admission floors were never measured, the response also carries the informational facts_calibration: {status: "unmeasured", model_key} (one facts_calibration_unmeasured notice per session explains it; gbrain doctor --only fact_admission_floors --json names the model): treat a short facts list as weaker evidence of "nothing matched". Applies inside entity, session_id, since and grep. Does not search pages (query does; both may be passed). With include_expired, expired and superseded facts are ranked too. A question over 12 content words is searched on its last 24 and scored on the 12 of those the fewest candidates hold. facts_below_floor: <n> is present when candidates were found and none cleared the admission rule (absent when nothing matched). Rejected with supersessions, and over 2,000 characters (invalid_params reason question_too_long, detail max_chars=2000 received_chars=<n>, with the corrected call as fix; never cut). One query embedding per call, shared with a query of the same text.
query string MEMORY_VERBS v1: free-text retrieval over pages (hybrid search arm). Response adds results[] (slug, title, chunk, evidence, create_safety, provenance). Combinable with entity (both arms run). Degrades to keyword-only search when no embedding provider is configured (search_degraded notes it; never an error).
budget_tokens number MEMORY_VERBS v1: server-side token budget (char/4 estimate). Facts pack first, then results. Response adds budget_tokens, budget_used, dropped_count.
budget_policy string (facts_first, query_first) Optional packing order. facts_first (default) packs facts first, then page results. query_first packs the ranked page prefix before facts only with a nonblank query and positive finite budget; a positive budget below one token keeps neither arm. Without a nonblank query and an active budget, packing stays facts_first. Neither policy skips oversized items or truncates. Supplying this option adds budget_packing accounting. Keep fact-focused/entity-filtered questions on facts_first.
source_id string Optional concrete source id for both facts and page results. Narrows the caller’s authorized scope, including an explicit default; a denied, missing, or archived source fails rather than widening. Omit to preserve the existing context/grant scope.
since string ISO 8601 datetime, duration shorthand (e.g. "8 hours ago", "2d") or a relative phrase ("6 weeks ago", "a month ago", "last month", "the past 2 years"; months and years step the calendar). Filters the FACTS arm only, on event time (valid_from, falling back to created_at); composes with entity and session_id. An unparseable value is rejected (invalid_params).
session_id string Source session id (e.g. topic-A). Returns facts captured in that session.
include_expired boolean When true, include expired_at IS NOT NULL rows. Default false. With question, expired, superseded and lapsed facts are ranked alongside active ones (each row keeps its expired_at and valid_until).
supersessions boolean When true, return only the supersession audit log (facts with superseded_by set), newest first by COALESCE(expired_at, valid_until).
limit number Per-arm cap: max fact rows AND max search results. Default 50, cap 100.
grep string Substring filter on fact text (case-insensitive). Applied in SQL before the limit, so matches on high-cardinality entities are found even outside the newest-N window.
include_pending boolean When true, response includes pending_consolidation_count (facts not yet promoted to takes by the dream-cycle consolidate phase). One round trip; backward-compatible (field omitted when false).
return_unit string (chunk, window, section, page, auto) Evidence unit for the results[] arm (needs query; default config search.return_unit = 'auto'). 'window' adds neighbor chunks, 'section' the enclosing section or conversation rounds, 'page' the whole page/session (best for multi-session questions), 'auto' the whole page for conversation pages and the ranked chunk unchanged for everything else (budget_tokens or budget_policy without return_unit keeps chunk packing). Non-chunk units return one result per page with delivered metadata and a top-level delivery block; the evidence is budgeted by budget_tokens (default 6000, auto 24000) and then packed by recall's usual rules.
return_window number Neighbor chunks on each side for return_unit 'window' (integer 1-3, default 1).

remember

MEMORY VERB (v1): save one fact to durable agent memory — the protocol write verb. provenance is REQUIRED (free text, e.g. "conversation 2026-06-12", "user said in chat", "import: notes.md"). Set entity whenever the fact is about a specific person/company/project — entity-scoped recall will not find it otherwise. ttl accepts duration shorthand ("30d", "12h") or an absolute ISO 8601 timestamp; ISO-8601 durations like "P30D" are rejected with a fix. visibility defaults to "world" (readable by every agent connected to this brain; pass "private" for local-CLI-only facts). A credential bound to a member saves on its own member page as "private" by default; pass share: true to share a fact with everyone who reads the source. The brain owner's own credential saves shared on the subject's page unless it passes visibility "private" or the page or the brain's default keeps facts private (then on its member page); the reply names the page and visibility. Response: branch on status (inserted|duplicate|superseded), never on status_text (human rendering only). On duplicate, id is the EXISTING fact's id. page names the page whose Facts table now holds the fact, and is absent when the fact is on no page: remember never creates a page, so a fact whose entity slug has no page is stored in the database only (persistence: {mode: "database"}, write_through: {written: false, skipped: "entity_page_missing"}) and still recalls; on a source canonical in Git it is instead committed as a row of memory/unattributed naming the entity (page: "memory/unattributed", write_through: {written: true, held_for: "<entity>"}) until maintenance moves it into the entity's page. Each items entry carries its own page, persistence and write_through. Where the brain's pages are in a Git repository, that reply also carries an entity_page_missing notice whose step is ask_user: relay its user_message (the fact is saved in the database only; should a page be created for the entity?) and, if the user agrees, make its put_page call; the next maintenance cycle can then move the entity's facts into the page. A held fact's notice only says where the fact is and that it moves once the page exists, with no step to run. For bulk extraction from a raw transcript use extract_facts instead.

Parameter Type Guidance
source_id string Source to mutate. Defaults to the selected source. Remote callers may only use their current write source.
expected_revision string Revision returned by the page read. Required when replacing an existing page unless force is true. Omit both for create-only writes.
force boolean Explicitly overwrite the current revision. Mutually exclusive with expected_revision; does not bypass authorization or the empty-content guard.
request_id string Optional caller-generated UUID for this write. Reuse the same UUID and original arguments to recover its outcome after a timeout; a different intent requires a new UUID.
content_origin string (user_said, tool_output, inferred) Where the content came from. tool_output (web page, email, file or other tool text) stores the write as external, untrusted; user_said and inferred store it as written by an agent. Advertised on the verbs and full surfaces only; a starter client that passes it is still honored.
fact (required) string The fact to remember, one claim per call.
provenance (required) string Where this fact came from (REQUIRED, free text, max 500 chars). Examples: "conversation 2026-06-12", "user said in chat", "import: meeting-notes.md".
ttl string Optional expiry: duration shorthand ("30d", "12h", "45m") or absolute ISO 8601 timestamp ("2026-07-12T00:00:00Z"). NOT ISO-8601 durations ("P30D" is rejected). Omit = never expires.
entity string Person/company/project this fact is about (name or slug; canonicalized server-side). Set it whenever the fact has a subject — entity-scoped recall misses unattributed facts.
infer_entity boolean Default true. When entity is omitted, link the fact to the one entity page the text names exactly (response entity_inferred: "mention"); pass false to save it unattributed.
kind string (event, preference, commitment, belief, fact) Fact kind: event | preference | commitment | belief | fact (default).
visibility string (world, private) world (default): readable by every agent connected to this brain — required for the remote remember→recall round-trip. private: local CLI reads only.

request_tools

Discover this brain's tool catalog and optionally unlock a wider tool surface for your client. No arguments → the catalog visible to YOUR credentials, grouped by area (tool names + one-line summaries). {tools: ["name", ...]} → full read-only schemas for the visible subset of those names (unknown/hidden names are silently omitted; an empty list, or one with no name you can call, returns the catalog plus did_you_mean, the closest names you can call). {surface: "verbs"|"starter"|"full"} → persist that tool surface for this client (bounded by the server ceiling; denied when an operator pinned the surface; ~5 changes/hour), then re-issue tools/list to see the new catalog.

Parameter Type Guidance
tools array Fetch full read-only tool schemas for these names. Names outside your visible surface are silently omitted.
surface string (verbs, starter, full) Persist this tool surface for your client. Must not exceed the server ceiling; ignored surfaces stay available via no-arg discovery. Takes effect on your next tools/list.

resolve_slugs

Fuzzy-resolve a partial slug to matching page slugs

Parameter Type Guidance
partial (required) string Partial slug or title text to match, e.g. 'alice-ex' or 'meeting notes'. This is the search text param — there is no text param.
source_id string Scope resolution to a single source. Defaults to OperationContext.sourceId; when unset, an unqualified resolve spans every federated source (matching search/get_page). Pass 'all' to span every source for trusted local callers; for remote callers 'all' spans only your granted sources.

search

Cheap hybrid search (vector + keyword + RRF) with no LLM expansion. Best for exact known tokens, names, and structured-field lookups. A populated result set is NOT proof of coverage — for concept / synonym / landscape questions use query (it can add multi-query expansion with expand: true); for exhaustive enumeration use list_pages pagination. Pass return_unit ('window' / 'section' / 'page') for whole evidence instead of chunks; conversation pages already come back whole by default (return_unit 'auto'; 'chunk' opts out). For personal/emotional questions, prefer get_recent_salience or find_anomalies — they surface activity bursts without needing a search term. To find every page that contains a literal phrase or identifier, where you would otherwise grep, use search_exact on the full surface (CLI gbrain search --exact "<phrase>"): it is unranked and exhaustive and says whether it read the whole scope (exact search). For code-symbol questions (callers, callees, definitions, blast radius), use code_callers / code_callees / code_def / code_refs instead — those return structural graph data, not text chunks. For agent memory reads (saved facts + budget-packed retrieval), prefer the recall verb.

Every call also reports how many pages match the query's keywords (keyword_total, keyword_truncated; "10000+" past 10,000) in one line after the rows. That count covers keyword (full-text) matches only, not the ranked rows. To list every one of those pages, pass match: "keyword": rows come one per page in keyword-score order with total, truncated and next, a ready-to-send argument object; keep calling with next until it is absent. A page whose text did not fit token_budget still gets a row, with evidence_omitted: true. If the count times out, the line says it is unavailable (degraded stage keyword_count_unavailable), never zero.

On a large Postgres brain a broad keyword statement can hit the keyword time limit; the response's degraded stages then carry keyword_arm_failed with reason timeout, and for up to 10 minutes (search.keyword_timeout_negative_cache_seconds, 0 = off) the same search in the same serving process reports reason skipped_after_timeout at once instead of waiting again. The serve re-runs the statement in the background from 30 seconds after the timeout, and the skip ends at the first re-run that answers. Vector hits still come back. A skipped keyword arm is not evidence of absence: narrow the search (source_id, types, since or until) to run keyword matching, and gbrain doctor --only keyword_plan --json on the brain host reports the bound and the recorded timeouts. The same applies to query.

Parameter Type Guidance
query (required) string Search text. Exact tokens, names, and structured-field values work best here (e.g. 'acme-example series A'), since this op does no LLM expansion. This is the search text param — there is no text or q param.
limit number Max results (default 20)
offset number Skip the first N rows of the ranked list (at most 10,000). Hybrid rows are a ranked top-K, so offset paging can miss pages; use match: "keyword" and next to list every keyword match.
match string (hybrid, keyword) hybrid (default): ranked top-K rows plus the keyword count line. keyword: every page matching the query's keywords (strict full-text match, the same set keyword_total counts), paged with next. Remote-safe; keyword matching costs less than hybrid.
cursor string The keyset cursor inside a match: "keyword" response's next. Send next unchanged; a cursor without match: "keyword" is refused (search_cursor_requires_keyword).
mode string Search mode (conservative|balanced|tokenmax). Local callers only: an agent-facing caller that sets it is refused (search_mode_local_only) with a fix naming match: "keyword".
source_id string Scope search to a single source. Defaults to OperationContext.sourceId (set from CLI --source / GBRAIN_SOURCE / .gbrain-source dotfile); when unset, an unqualified read spans every federated source. Pass 'all' to span every source for trusted local callers; for remote callers 'all' spans only your granted sources.
source_ids array Narrow the request to these sources (CLI: --source-ids source-a,source-b). Each id is authorized like an explicit source_id, so the list can narrow a request but never widen it: a source outside a remote caller's grant refuses the whole request with permission_denied, and a removed or archived one with unknown_source. Omitted, [] or a blank string leaves the request's normal scope (source_id, or your default scope) unchanged; __all__ is refused. With source_id too, the request reads their intersection, and an empty intersection returns no rows with an empty_retrieval notice. See narrowing one request.
types array Filter results to pages whose type is in this list (e.g. ['person','company']). CLI: --types person,company. Applied at SQL level on every retrieval leg — the same filter whoknows uses. Stacks with all other filters.
snippet_chars number Cap each result's chunk_text at N characters (a "… [truncated]" marker names the get_page recovery move). 0 forces full text. Unset: subagent tool loops default to the agent.search_snippet_chars config (300; 0=full); every other caller gets full text. A row widened by search.long_page_unit (delivered: {unit, reason: "long_page"}) is exempt and comes back whole; every other row is still cut.
return_unit string (chunk, window, section, page, auto) Evidence unit returned in each result's chunk_text (default: config search.return_unit, which defaults to 'auto').
'chunk' — the ranked chunk only (~300-450 tokens per result).
'window' — the hit chunk plus return_window neighbor chunks each side (local context, ~3x chunk).
'section' — the enclosing markdown section, or the conversation rounds around the hit.
'page' — the whole page/session, capped. Use for multi-session or temporal questions where the answer needs the whole conversation.
'auto' — the whole page for conversation pages (conversation/transcript/chat/meeting/slack/imessage types, chat/ or conversations/ slugs), the ranked chunk unchanged for everything else. When no hit is a conversation the response is exactly the chunk response.
Non-chunk units return one result per page, packed into token_budget (default 6000, auto 24000; remote max 32000), with a delivered object (unit, chunk_ids, match_spans, tokens, truncated; reason under auto) per result and delivery in the response meta.
return_window number Neighbor chunks on each side for return_unit 'window' (integer 1-3, default 1).
token_budget number Token budget for delivered evidence when return_unit is not 'chunk' (default search.return_budget_default = 6000; auto: search.return_budget_conversation = 24000). Ignored in chunk mode.
salience string (off, on, strong) Salience boost (emotional_weight + take_count, no time component): 'off' | 'on' | 'strong'. Omit and gbrain auto-detects from query text. Independent of recency.
recency string (off, on, strong) Recency boost (per-prefix age decay, no mattering signal): 'off' | 'on' | 'strong'. Omit and gbrain auto-detects. Independent of salience. Ignored on the keyword-only opt-out path.

submit_agent

Submit an LLM agent job that the worker dispatches via the gateway-native tool loop. Requires the agent OAuth scope. Tools, source, slug prefixes, max concurrency, and daily budget are bound at OAuth client registration time.

Parameter Type Guidance
prompt (required) string User prompt for the agent
model string provider:model string (defaults to models.tier.subagent)
allowed_tools array Subset of bound_tools the agent may invoke
allowed_slug_prefixes array Subset of delegated_slug_prefixes for writes; omit for a job-owned namespace
max_turns number Max LLM turns (default 20, hard cap 100)
queue string Queue name (default "default")

synthesize

[EXPENSIVE / SLOW — makes LLM calls, seconds-to-minutes latency, costs money] MEMORY VERB (v1): answer a broad question using cross-page LLM reasoning with citations and gap analysis. Prefer recall (facts/snippets) or entity (one known card, zero LLM) for lookups — use synthesize only when the answer requires combining evidence across pages. Response carries a best-effort cost block (model, tokens, usd_estimate) plus compose-status fields (synthesis_status, pages_gathered, takes_gathered, warnings); when the LLM compose step fails but retrieval succeeded, answer degrades to an extractive digest of retrieved pages (synthesis_status: "extractive_fallback") instead of an error.

Parameter Type Guidance
question (required) string The question to answer.
since string Optional temporal window start (ISO 8601 date or datetime).
until string Optional temporal window end (ISO 8601 date or datetime).

traverse_graph

Traverse link graph from a page. Remote callers default to bidirectional edges (GraphPath[]) at depth 2 (pass depth explicitly for deeper walks); trusted local no-filter callers get the legacy node shape at depth 5. The walk is breadth-first: each page comes back once at its shortest depth and each edge once, and a walk stops at 20,000 visited pages or 5,000 edge rows, keeping the shallowest (a stderr note says when, and the result carries a graph_walk_truncated degraded notice; above depth 1 its fix repeats the walk one level shallower).

Parameter Type Guidance
slug (required) string Slug of the page to start the traversal from, e.g. 'people/alice-example'. This is the start-node param — there is no start or root param.
depth number Max traversal depth (capped at 10). Default 5, except a remote call that lets direction default to 'both' uses 2 (a both-direction walk from a hub reaches much of the brain and fills the 5,000-edge cap); an explicit depth is always honored up to the cap.
link_type string Filter to one link type (per-edge filter, traversal only follows matching edges)
direction string (in, out, both) Traversal direction ('in', 'out', or 'both'). Remote callers default to 'both'; trusted local no-filter callers get the legacy outgoing-node output.
hops array of {link_type, toward} Typed chain of 1-3 hops from the start page, e.g. [{"link_type":"invested_in","toward":"object"},{"link_type":"founded","toward":"subject"}] (companies the person invested in, then their founders). toward follows the relationship's meaning (object: subject → object; subject: object → subject), not stored link direction. Returns {anchor, answers, paths, diagnostics} with each answer's evidence edges; a chain that finds nothing carries a relational_chain notice with the next call. Not combinable with depth, link_type or direction; each hop walks live relationships. Advertised on the full surface only. Chain link types: founded, invested_in, led_round, advises, works_at, attended, yc_partner. See docs/guides/multi-hop.md.
source_id string Scope the read to one source (a multi-source brain can hold the same slug in several sources). Omitted: your granted sources remotely (a connection with no grant reads every federated source); locally, the resolved source, or every federated source when no --source / GBRAIN_SOURCE / .gbrain-source pinned it. 'all' spans every source for trusted local callers and only your readable sources for remote callers.
all_sources boolean Span sources (equivalent to source_id=all): every source locally, only your readable sources remotely.

whoami

Introspect the calling identity. Returns one of three transport shapes: {transport: "oauth", client_id, client_name, scopes, expires_at, source_id, federated_read}, {transport: "legacy", token_name, scopes, expires_at: null}, or {transport: "local", scopes: []}, or {transport: "stdio", scopes: []} for the auth-less stdio MCP pipe. Throws unknown_transport when the context is ambiguous (remote=true without auth and no transport marker) — fail-closed, per the trust-boundary contract.