Garry's Opinionated OpenClaw/Hermes Agent Brain
qm (multi-user agent harness) — gbrain as the company brain
Connect gbrain to qm — the multiplayer agent harness where each employee and each channel gets an isolated agent scope — so every scope's agent can search and write one shared, indexed, isolation-enforced company brain. The same recipe fits any harness with per-person sandboxes that can run a CLI.
Shape: one central gbrain serve --http (OAuth 2.1) next to qm's core;
the gbrain binary baked into qm's sandbox image as a thin client; one OAuth
client per employee, read-fenced by source federation and write-fenced by
bound_slug_prefixes. Zero qm code changes — everything lives in the qm
deployment directory.
qm's native memory (per-scope notebook) stays as-is for fast per-turn recall. gbrain adds what qm doesn't have: semantic + hybrid search, cross-scope knowledge, entity graphs, and durable memory that outlives a scope.
Topology
| gbrain concept | qm concept |
|---|---|
| one brain (one Postgres/Supabase DB) | the org |
source agents (path-less, shared) |
all agent-written memory |
slug prefix emp-<slug>/ in agents |
an employee's personal scope |
slug prefix chan-<slug>/ in agents |
a channel/room scope |
source org-wiki (git-backed, read-only) |
company docs |
OAuth client qm-emp-<slug> |
one employee's agent identity |
Isolation model:
- Reads are source-granular, SQL-enforced (
federated_read): every employee client readsagents+ the read-only sources you grant. Folder rules can narrow reads inside a source (Known limitations). - Writes are slug-prefix-granular, server-enforced (
bound_slug_prefixes): a client can only mutate pages under its ownemp-<slug>/and its channels'chan-<x>/prefixes — onput_page,delete_page,restore_page,add_tag,remove_tag,add_link/remove_link,add_timeline_entry,revert_versionandput_raw_data, plus thePOST /ingestwebhook route. Not by convention. - Every op that is not a plain read is denied unless allow-listed. Ops
that write by a key other than a slug —
extract_entitiesandextract_facts(which mutatepeople/*andcompanies/*),forget_fact(targets a fact by numeric id, across sources),ontology_propose, and thesources_adminpairsources_add/sources_remove— cannot be fenced by slug, so a bound client getspermission_deniedat dispatch. The gate keys on "not a pure read", not on a list of scope strings, so a write op added later (or one carrying a bespoke scope) is denied until it is explicitly fenced and added toCLIENT_FENCED_WRITE_OPS(src/core/operations.ts).thinkis allow-listed because remote callers cannot persist from it;submit_agentbecause it enforces this same column itself;remember(#5913) because it fences the one slug it writes and confinesreplacesto the caller's entity.forget/forget_factare not: a withdrawal's write set reaches pages the fenced slug does not name. - Indirect write paths are gated too, not just the ops.
put_page's facts backstop would otherwise extract entities from the page body and write fact rows (and a## Factsfence on git-backed sources) ontopeople/*pages the caller never named — the same capabilityextract_factsis denied for, reached through an in-prefix write. It is skipped for bound clients.POST /ingestis refused outright: its handler bypasses the op layer, soenforceClientSlugFencenever runs and a bound client could write any slug inside its granted source.
Known limitations — read these before you rely on the fence
The write fence is a write boundary within a source. It is not a privacy boundary, and it does not make every side effect prefix-clean:
The fence follows a delegated write. When a client with
agentscope hands work to a subagent viasubmit_agent, that subagent runs under its own slug confinement rather than the parent's OAuth binding. Both confinements are enforced, including on the path where deduplication redirects a write onto an existing page: the redirected target is checked against whichever confinement the calling context actually carries, so delegation does not widen what a client can write.add_link/remove_linkfence thefromendpoint only. A bound client can create an edge pointing AT a page it cannot write; the edge'scontexttext surfaces in that page's backlinks and contributes to its search ranking. Fencingtowould break legitimate cross-referencing intoorg-wiki, so this is deliberate — treat inbound-edge context as untrusted content, the same way you treat page bodies.Reads are source-granular unless you add folder rules. Without them, everyone entitled to a source can read every prefix in it. To keep
emp-<slug>/to one employee insideagents, make them a member (gbrain access member add <slug>), bind their client to it (gbrain auth rescope --client <id> --member <slug>) and add a folder rule (gbrain access rule add --prefix emp-<slug>/ --readers <slug> --source agents, preview, then--yes); see Model C in the company-brain tutorial. A separate source remains the strongest separation.put_pagecan create one reverse graph edge outside the fence. If a page body cites a code location (src/x.ts:42) and a code page for it exists in the same source, doc↔impl reconciliation adds an edge originating from that code page. It affects graph/backlink ranking, not page content. Unreachable in the layout above (theagentssource is path-less and holds no code pages); it applies only if you point employee writes at a code-synced source.Stored contradiction findings are filtered per caller.
find_contradictionsreturns a harness client only the findings whose two sides it can read in its grant, re-read live withsource_idandtrust_tier; stored report text never leaves. Other brain-wide read ops (get_recent_salience,find_anomalies, andsources_list/sources_status) honor the federated grant;sources_statusanswersnot_foundfor an out-of-grant ID.Reads touch
last_retrieved_at(inpage_retrievals) on the pages they return, including pages in read-only sources. Freshness/usage signals are therefore writable-by-reading; nothing else about the page is.POST /ingestwrites land in the calling client's granted source. The write source is resolved server-side fromoauth_clients.source_id; the caller-suppliedX-Gbrain-Source-Idheader does not route anything, so a client cannot choose its own write partition. A client registered without a source writes todefault. If its source is unregistered, archived, or deleted before the job runs (or deleted while it writes), the job fails withsource_changed(detail: webhook_source_unavailable) and nothing is written; restore the source and rungbrain jobs retryon the job. If you point a webhook integration at this route, give its client an explicit--sourceso its captures do not accumulate in the brain'sdefaultsource. Bound clients are still refused the route outright, because the slug fence cannot run on this path.Tradeoff to state out loud: without folder rules, read isolation is per-source, so within the shared
agentssource every employee can read every prefix (including other employees'emp-*/). That matches qm's transparent-by-default, everything-audited posture. If you need hard read privacy for personal memory, add a folder rule peremp-<slug>/(above), or give those employees their own write source instead of a prefix (onesources add emp-<slug>+--source emp-<slug>per client) and keep channel prefixes inagentsvia a second, channels-only client — at the cost of two credentials in that sandbox.
Host setup (the machine running qm's core, or any box its sandboxes can reach)
# 1. Engine: Postgres/Supabase. PGLite is single-process and cannot serve
# many concurrent sandboxes.
gbrain init --supabase --embedding-model voyage:voyage-4-large
# 2. Modes + gates (publish_* default OFF and fail as silent 403s):
gbrain config set search.mode balanced
gbrain config set mcp.publish_skills true
gbrain config set mcp.publish_advisor true
# 3. Read-only org sources + first sync:
gbrain sources add org-wiki --path ~/brains/org-wiki
gbrain sync --all # cron this
# 4. Serve over HTTP MCP (OAuth 2.1), listing the 7 memory verbs:
gbrain serve --http --bind 0.0.0.0 --port 3131 \
--public-url https://brain.acme-example.com --advertise verbs
--advertise verbs is the registration default gbrain's own installers use
(--surface starter --advertise verbs since v0.60.503.0). QM sends every listed
tool schema on every request, so a bare serve costs each turn about 11,800 input
tokens for 33 tool schemas; with --advertise verbs it lists the seven verbs
plus request_tools. Every operation stays callable, so the gbrain tool in the
sandbox keeps working: the server keeps the full ceiling here because the
skill's gbrain link (add_link) is outside starter.
Never hand sandboxes DATABASE_URL — direct DB access bypasses OAuth, source
federation, and the write fence entirely.
Provision scopes from a roster
qm-harness-snippets/provision-scopes.sh
converges the brain to a roster file
(roster.example.tsv):
bash provision-scopes.sh roster.tsv --read-sources org-wiki
- Creates the path-less
agentssource (agent-written memory needs no git clone; if the host hassync.repo_pathconfigured, pages also write through to.sources/agents/for git-backed durability). - Registers
qm-emp-<slug>clients:--scopes "read write",--source agents,--federated-read agents,org-wiki,--bound-slug-prefixes emp-<slug>/,chan-<a>/,..., per-day budget. - Idempotent: re-run after every roster edit; existing clients are
rescope-cliented in place (channel joins/leaves update the write fence without rotating secrets). - New client secrets land once in
<roster>.new-credentials.tsv— deliver each row to its scope (qm keychain / one-time secret drop), then delete the file.
qm deployment directory
In the org's qm deployment repo (the directory qm init produced):
- Tool: copy
qm-harness-snippets/tool.jsontosandbox/tools/gbrain/tool.jsonand drop the compiledgbrainbinary beside it (bun build --compile --no-compile-autoload-bunfig --outfile gbrain src/cli.ts, built for the sandbox image's OS/arch).auth.credentialPathsmarks~/.gbrain/config.jsonas the scope's resident credential file;auth.checkwiresgbrain whoamiinto qm's connector status (read-scope; see the note below on whyremote doctorcannot be used here). - Skill: copy
qm-harness-snippets/SKILL.mdtosandbox/skills/gbrain/SKILL.md(edit slug conventions to taste). - Ship it:
qm sandbox build && qm sandbox publish && qm up.
Per scope, one-time (agent- or operator-run, credentials from the handoff):
gbrain init --mcp-only \
--issuer-url https://brain.acme-example.com \
--mcp-url https://brain.acme-example.com/mcp \
--oauth-client-id gbrain_cl_... --oauth-client-secret gbrain_cs_...
gbrain whoami # must succeed
Use --oauth-client-secret, not GBRAIN_REMOTE_CLIENT_SECRET: an env-sourced
secret is deliberately not written to ~/.gbrain/config.json
(src/commands/init.ts), so with the env var alone every later command fails
once it leaves scope — and qm's sandbox.secretEnv is org-wide, so there is no
per-scope env to keep it in. With the flag, the credential lands in the config
file on the scope's durable disk and this runs once per scope, ever.
gbrain remote doctor is not the health check here: run_doctor is an
admin-scope op and these clients are read write on purpose. gbrain whoami
is read-scope and reports the client's identity, source, and grants.
Verify isolation before rollout
From two differently-scoped sandboxes (or two thin-client configs):
# alice-example (bound to emp-alice-example/, chan-eng/):
gbrain put emp-alice-example/notes/test --content "mine" # OK
gbrain put chan-eng/notes/test --content "shared" # OK
gbrain put emp-bob-example/notes/test --content "not mine" # permission_denied
gbrain put chan-product/notes/test --content "not my channel" # permission_denied
gbrain search "test" # sees agents + org-wiki only
Cost + operations
search.mode balanced(12K token budget, relational retrieval on) is the right default for a startup fleet; seedocs/guides/search-modes.mdfor the cost matrix before changing it.- Budgets:
--budget-usd-per-dayis recorded on the client but only enforced on thesubmit_agentpath (src/core/minions/budget-meter.ts), which theseread writeclients cannot reach — so it does not cap spend from ordinarysearch/put_pagetraffic. Treat runaway-agent containment as an open item: watch the admin SPA (/admin) andgbrain search stats, and cap at the model/harness layer. - Backfills on a live brain:
gbrain embed --stale --pace(see Pace Mode in CLAUDE.md /docs/operations/spend-controls.md).
Deliberately deferred
- qm
MemoryServicedecorator (mirror notebook captures into gbrain, fanrecallout and merge,volunteer_contextpush): needs a qm code change; today's integration is agent-initiated via the CLI + skill. - MCP-native attach: qm pins
strictMcpConfigwith only its in-process server, so gbrain's MCP-discovered brain-resident skillpacks don't reach qm agents; the sandbox skill above covers it.