Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: qm-harness read isolation names folder rules; company-brain counts three scoping models
garrytan54ac1b1e4c53
diff --git a/docs/integrations/qm-harness.md b/docs/integrations/qm-harness.mdindex 2c561f13cc..7dc73e1fdc 100644--- a/docs/integrations/qm-harness.md+++ b/docs/integrations/qm-harness.md@@ -30,7 +30,8 @@ knowledge, entity graphs, and durable memory that outlives a scope.Isolation model:- **Reads** are source-granular, SQL-enforced (`federated_read`): every- employee client reads `agents` + the read-only sources you grant.+ employee client reads `agents` + 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 own `emp-<slug>/`and its channels' `chan-<x>/` prefixes — on `put_page`, `delete_page`,`restore_page`, `add_tag`, `remove_tag`, `add_link`/`remove_link`,@@ -77,9 +78,15 @@ boundary, and it does not make every side effect prefix-clean:ranking. Fencing `to` would break legitimate cross-referencing into`org-wiki`, so this is deliberate — treat inbound-edge context as untrustedcontent, the same way you treat page bodies.-- **Reads are source-granular, never prefix-granular.** Everyone entitled to- a source can read every prefix in it. If a scope needs genuine read- privacy, give it its own source.+- **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 inside `agents`, 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](../tutorials/company-brain.md). A separate source+ remains the strongest separation.- **`put_page` can create one reverse graph edge outside the fence.** If apage body cites a code location (`src/x.ts:42`) and a code page for itexists *in the same source*, doc↔impl reconciliation adds an edge@@ -106,11 +113,12 @@ boundary, and it does not make every side effect prefix-clean:this route, give its client an explicit `--source` so its captures do notaccumulate in the brain's `default` source. Bound clients are still refusedthe route outright, because the slug fence cannot run on this path.-- **Tradeoff to state out loud:** read isolation is per-source, so within the- shared `agents` source every employee can *read* every prefix (including- other employees' `emp-*/`). That matches qm's transparent-by-default,+- **Tradeoff to state out loud:** without folder rules, read isolation is+ per-source, so within the shared `agents` source 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, give those employees their own write source instead of a prefix+ memory, add a folder rule per `emp-<slug>/` (above), or give those+ employees their own write source instead of a prefix(one `sources add emp-<slug>` + `--source emp-<slug>` per client) and keepchannel prefixes in `agents` via a second, channels-only client — at thecost of two credentials in that sandbox.@@ -241,6 +249,3 @@ gbrain search "test" # sees agents +- **MCP-native attach:** qm pins `strictMcpConfig` with only its in-processserver, so gbrain's MCP-discovered brain-resident skillpacks don't reachqm agents; the sandbox skill above covers it.-- **Read-side prefix fencing** (hard privacy for `emp-*/` inside a shared- source) — tracked upstream; the roster layout is forward-compatible with- it.diff --git a/docs/tutorials/company-brain.md b/docs/tutorials/company-brain.mdindex 22b4fc81f8..59275d9bc2 100644--- a/docs/tutorials/company-brain.md+++ b/docs/tutorials/company-brain.md@@ -107,7 +107,7 @@ You can also keep the existing personal-brain repo as one of the sources. Just p### Two scoping models (pick the one that matches your shape)-There are two ways to scope teammates' access. They suit different deployment shapes.+There are three ways to scope teammates' access. They suit different deployment shapes.**Model A: separate sources with OAuth scoping (recommended for true multi-user with different AI clients).** What this tutorial walks you through. Each teammate gets their own OAuth client, which carries `--source` + `--federated-read` flags. The brain refuses cross-source reads at the SQL layer; isolation is database-enforced. Each teammate can run their own MCP-aware client (Claude Code, Cursor, their own OpenClaw, etc.) and the scoping holds.