Skip to content

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.md
index 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 untrusted
content, 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 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
@@ -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 not
accumulate in the brain's `default` source. Bound clients are still refused
the 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 keep
channel prefixes in `agents` via a second, channels-only client — at the
cost 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-process
server, so gbrain's MCP-discovered brain-resident skillpacks don't reach
qm 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.md
index 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.