Garry's Opinionated OpenClaw/Hermes Agent Brain
MCP _meta channels
Normative conventions for ToolResult._meta on gbrain's MCP surfaces.
_meta is the structured, out-of-band
channel for tool-call responses; the response BODY contract never changes
shape for it.
Rules
- One producer per top-level key. A producer owns exactly one
namespaced key and never writes another producer's key. The dispatch
layer (
src/mcp/dispatch.ts) merges per top-level key — never wholesale_metaassignment. - Additive-forever within a key. Fields inside a key may be added,
never renamed or removed — the RESPONSE_SCHEMAS discipline applied to
_meta. Consumers must tolerate unknown fields. - Producer isolation. Every producer attaches inside its own try/catch. A failing producer degrades to its key being absent; it never drops another producer's key and never errors the tool call.
- Merge precedence. Handler-emitted keys (via
OperationContext.emitResponseMeta) attach first; transport hooks (metaHook) attach after and may add keys but shadow nothing that matters — key ownership (rule 1) makes ordering a non-event. - Model visibility caveat. Mainstream harnesses do NOT feed
_metato the model. Anything the model must SEE rides a content block (see the second text block on empty retrievals);_metaserves structured programmatic consumers (thin clients, harness plumbing, tests).
Registered keys
| Key | Producer | Contents |
|---|---|---|
brain_hot_memory |
dispatch metaHook on stdio and HTTP (getBrainHotMemoryMeta, details) |
Hot-memory facts relevant to the call; each fact carries trust_tier and origin, and suppressed ({withheld, review}, present only when non-zero) counts unconfirmed agent-written facts activation control withheld, never their content |
degraded |
dispatch (src/core/degraded-stamp.ts), on every transport |
{reasons: [...]}: present only when the result is partial or degraded; sorted, unique stable codes (AGENT_OPERATOR_v1.md, Degraded stamp). Mirrored as the last content block, [gbrain degraded: <codes>] … |
retrieval |
search/query op handlers; recall and find_experts emit {degraded[]} when their page search degraded |
returned_count, retrieved_count, vector_enabled, expansion_applied, cache, token_budget, degraded[] (closed stage vocabulary), rerank_degraded (on a call whose reranker failed: {reason, fallback: "fused_order", calls_this_session}; reason is timeout, budget, rate_limited, unreachable, auth or provider_error; no fields: "full" needed), hint (non-contractual prose), rows ("lean" or "full": the row shape of content[0]; reported for remote callers and whenever fields is passed), timings ({total_ms, stages_ms, other_ms, overlapped_ms?, parts_ms?}, integer ms, every response; search-explain.md) |
access |
dispatch (appliedAccessSummary, src/core/access/caller.ts), every remote response that reached the operation |
The view the call was answered under: member and groups it read as (null and [] for an unbound caller or an audience of several entries), audience (the normalized on_behalf_of principals, or null), policy_rev (each source's applied folder-rule revision; null on a brain with no restriction), relaxation (none, granted_sources, operator or owner: what relaxed visibility: private; owner is a credential bound to the brain owner, see access designations). whoami returns the same object as access.applied. An attested call adds actor ({system}); an unlinked memory_recall carries code: "actor_unlinked", member: null and the id as sent. |
room |
dispatch (assessRoom, src/core/access/room.ts), only on a call that declared a room |
The shared chat the answer goes into, as read: principals, declared_by (harness or argument), conflict (present when the argument and the harness disagreed), complete, counts ({items, readable, above, unknown}), by_reason, above (references the room could not read) and unavailable (why no marks could be computed: invalid, not_permitted, unknown_principal, unbound, mark_failed, deadline, op_not_covered, response_cap, not_supported). Each page and fact in the body, each hot-memory fact and each entry of retrieval.saved_facts carries room_access ({readable: true}, {readable: false, reason} with reason readers, folder_rule, labelled_only, private_label, derived or personal_source, or {readable: "unknown", reason}). Details |
warnings |
dispatch strict-params warn mode | [{code: 'unknown_param', param, suggestion?}]: a parameter a read ignored. This is the only place the warning appears; no content block or notice carries it, so a harness that stores tool output in its turns never stores it (writes refuse unknown parameters instead). |
pagination |
list_pages op handler |
truncated (more rows match), limit (effective), clamped_from? (the caller's limit when capped), next? (params for the following page: {sort, updated_after, updated_after_slug} under updated_asc, else {offset}). The model-visible counterpart is the listing_truncated notice block (kind info, never deduped), whose fix.mcp is the next-page call. |
brain_hot_memory
The brain's recent facts, attached to tool results so a harness can keep them in front of the model without a separate call.
When it is sent. On a successful tool call over stdio (gbrain serve) and
over HTTP (gbrain serve --http), except recall, extract_facts and
forget_fact, which already return facts, and except a call that names its own
sources (a non-empty source_ids, or a source_id other than the connection's
source), so a narrowed request never carries another source's facts. It is absent when there is nothing
to send, and it is best-effort: if it cannot be built, the key is left out and
the tool call still succeeds. It cannot be turned off per call.
Which facts. Up to 10 facts from the call's source, ranked by decayed confidence, with duplicates collapsed:
- facts recorded in the caller's session, when the request carries
_meta.session_id(besideargumentsor at request level); otherwise - the source's newest facts from the last 24 hours, from any session.
context.hot_memory.session_onlynarrows only the hook andcontext_packpaths, never this key.
Remote callers get world-visible facts only (private pages are excluded unless
search.remote_private_pages allows them), and the trust floor, quarantine and
activation control apply. Payloads are cached for up to 30 seconds per engine,
source, tier, session and eligibility; any write, forget or trust change
invalidates them.
Shape (fields are additive-forever, per rule 2):
{
"brain_hot_memory": {
"source_id": "default",
"session_id": "s-123",
"suppressed": { "withheld": 1, "review": 0 },
"facts": [
{
"id": 42, "fact": "Prefers morning meetings", "kind": "preference",
"notability": "high", "entity_slug": "people/alice-example",
"valid_from": "2026-10-01T00:00:00.000Z", "created_at": "2026-10-01T09:30:00.000Z",
"context": null, "confidence": 0.91,
"trust_tier": "agent_written", "origin": "mcp:user_said", "unconfirmed": true
}
]
}
}
suppressed appears only when activation control withheld facts, and counts
them without their content. attributed_to, entity_slugs and unconfirmed
appear only when set.
Using it from a harness. Most harnesses drop _meta before the model
(rule 5), so these facts reach the model only if the harness copies them in:
- Send a stable
_meta.session_idper conversation, so the block carries that conversation's facts instead of the source's newest. - Read
result._meta.brain_hot_memory.factsfrom each tool result and add them to the next model turn as context, labeled as saved memory. - Apply your own access rules before showing them: the 24-hour fallback can
carry another session's facts, such as a different user's direct messages
on a shared brain. Treat
unconfirmed: trueandtrust_tier: "agent_written"facts as claims to check, not as the user's words.
A harness that cannot do this still gets the same facts on purpose through the
per-turn hook or context_pack (ambient writeback).
Inbound _meta (e.g. _meta.session_id inside tool ARGUMENTS) is a
separate, client-to-server plane. Request-level _meta.on_behalf_of (a
sibling of arguments, list of member ids, group:<id> and guest) names a
shared agent's audience, like the X-Gbrain-On-Behalf-Of header; it is
bounded by the credential's may_act_for, and the same key inside tool
arguments is refused (on_behalf_of_in_arguments). See Model C in
company-brain.md. The eval-report _meta.metric_glossary
lives in JSON BODIES of eval commands — a third, unrelated plane. Ambient
recall rides content/hooks, not _meta.
Adding a key: register it in the table above, one producer, additive-forever.
brain_hot_memory: when it appears and how to turn it off
When. On every successful tool call over stdio (gbrain serve) and
HTTP (gbrain serve --http), except recall, extract_facts and
forget_fact, whenever the source below has facts to show. Errors never carry
it.
Which facts. Up to 10 recent facts from one source: the connection's own
source. Over HTTP that is the token's or client's write source (the first id
of its source grant), or default with no grant. Over stdio it is the source
the server resolved (GBRAIN_SOURCE, .gbrain-source, then default). With
a _meta.session_id, the block holds that session's facts. Without one, or
when the session has none, it holds the source's facts from the last 24 hours
(context.hot_memory.session_only does not narrow this key). A remote caller only
ever gets facts with visibility: world, and never a fact from a source its
grant can't read.
Why it matters for shared sessions. A member token whose first source is
that member's private source (private-alice-example) gets that member's own
recent facts in the block, such as preferences from a direct message. That is
correct for the member's own session. A harness that answers several people in
a channel and puts the block into the model's context can carry those facts
into a reply everyone reads.
Turning it off for one call. Set _meta.hot_memory: "off" on the request,
beside arguments (MCP request-level _meta), or inside the tool arguments
({"query": "…", "_meta": {"hot_memory": "off"}}) for clients that fold
_meta into the arguments. That call's response carries no
brain_hot_memory. Other values, or no value, leave the block as it is. A
channel or shared session should send it on every call. A member's own
direct-message session can leave it out. The opt-out removes only this
_meta block: a context_pack or delta body still lists the connection's
recent facts, so a channel harness should not call them with a member token
whose first source is that member's private source.
{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
"params": {"name": "search", "arguments": {"query": "standup time"},
"_meta": {"session_id": "channel-a", "hot_memory": "off"}}}
room
room is the one key that also travels on the request. A harness sets the
request-level _meta.room (a sibling of arguments) or the X-Gbrain-Room
header, and the response carries _meta.room back:
// request
{ "name": "search", "arguments": { "query": "launch plan" },
"_meta": { "room": ["alice-example", "group:team-a"] } }
// response _meta
{ "room": { "principals": ["group:team-a", "member:alice-example"], "declared_by": "harness",
"complete": true, "counts": { "items": 3, "readable": 2, "above": 1, "unknown": 0 },
"by_reason": { "readers": 1 }, "above": [{ "source_id": "default", "slug": "notes/owner-plan", "reason": "readers" }] } }
A room never changes the body's items or their order; it only adds
room_access to each item. A call with no room carries no room key. The
model-visible counterparts are the room_above_level,
room_hints_unavailable and room_conflict notice blocks. Full guide:
rooms.
Degraded stamp codes
The codes in _meta.degraded.reasons (AGENT_OPERATOR_v1.md, Degraded stamp). The list grows; a code never changes meaning.
| Code | Ops | Meaning |
|---|---|---|
a retrieval stage: embed_unavailable, embed_timeout, expansion_failed, expansion_partial, rescore_skipped, vector_arm_failed, keyword_arm_failed, title_arm_failed, budget_dropped_all, budget_truncated, keyword_zero, cache_prestamp, rerank_passthrough, rerank_failed, keyword_relaxed_carried, safe_index_pending, vector_candidates_incomplete, keyword_candidates_incomplete, projection_pending, projection_by_design, projection_status_unknown, keyword_count_unavailable, saved_facts_withheld, fact_observed_date_unavailable, contested_unavailable, facts_history_unavailable (query) |
search, query, recall, find_experts; think and synthesize (their page search) | the stage in _meta.retrieval.degraded (every stage except the ranking-only reranker_skipped; projection_pending only when a pending page could match). embed_unavailable also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |
no_query_terms, facts_embedding_column_missing, facts_read_failed, saved_facts_withheld, fact_observed_date_unavailable |
recall | facts_degraded.reason of a question-ranked recall |
facts_unembedded |
recall | some facts in scope could not be compared with the question |
deadline, server_budget, budget_trimmed |
context_pack | degraded_reason: the pack is partial |
delta_incomplete |
delta | delta delivered less than is waiting |
file_held |
get_page | the page's newer file is held by sync; this is its last good revision |
gather_hybrid_failed, gather_takes_keyword_failed, gather_takes_vector_failed, gather_graph_failed, gather_anchor_hydrate_failed, gather_window_floor_failed |
think, synthesize | an evidence stream failed (the matching GATHER_*_FAILED warning) |
held_files, references_unavailable, mention_index, relational_chain, graph_walk_truncated, pinned_answer_stale |
the ops that emit the notice of that code | a kind: degraded notice about this result |
room_hints_unavailable |
every op answered with a room declared | the room's marks could not be computed (_meta.room.unavailable says why): the body is complete, but every item is marked unknown |
scan_deadline, unreadable_pages |
search_exact | incomplete_reasons other than the caller's limit |
source_stale, held_items |
open_loops | stale or completeness: "partial" |
link_coverage_behind, link_coverage_unread |
rank_entities | coverage.state |