Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Research maps: agent-facing contract overview
These maps describe what the Rust port of gbrain must keep exactly: the CLI (commands, flags, --json output, exit codes), the MCP tools (names, input schemas, result shapes, access rules), and the markdown brain format. They are research only. No build phase starts from them until Garry approves it.
Reference versions
| Repo | Commit | Notes |
|---|---|---|
garrytan/gbrain (reference) |
master 8bbfd0b5e8 |
VERSION 0.60.733.0 |
garrytan/gbrain-evals (parity oracle) |
cd447b3ae ("Release v0.10.237") |
pins gbrain at 6ce7195b44a0, not #master |
The root CLAUDE.md in gbrain describes roughly v0.41. Where it disagrees with the code, these maps follow the code.
Files
| File | What it covers |
|---|---|
| cli.md | All 220 public CLI commands. Part A: op-backed commands, argv parsing, global flags, agent contract v1 (--json documents, notices, error envelope), exit codes. Part B: the 132 CLI-only commands by category. Part C: which commands agents and evals use. |
| mcp.md | All 186 MCP tools: transports (stdio, OAuth HTTP), scopes, surfaces, publish gates, wire shapes, the full tool table, JSON schemas for the verbs and starter surfaces, MEMORY_VERBS and the qm-memory-provider contract, and which tools agents and evals use. |
| brain-format.md | The markdown brain: directory layout, frontmatter fields and YAML rules, compiled truth vs timeline, facts/takes/links fences, slugs, wikilinks and backlinks, import/sync/export, content hash, annotated fixture pages. |
| agent-and-eval-usage.md | How gbrain-evals touches gbrain (library imports, CLI argv, MCP calls, the HTTP protocol v1 seam) and how gbrain's own skills and instructions use the CLI and MCP. |
| data/ | Machine-readable snapshots: the operation manifest (204 ops), tools/list output per surface (non-strict and strict), the public-surface lists (commands, flags, MCP params, exit codes, config keys), and captured MCP error envelopes. Regenerate with bun docs/research/rust-engine/scripts/dump-contract-data.ts <gbrain-checkout> docs/research/rust-engine/data. |
Key numbers
| Surface | Count | Source |
|---|---|---|
| Operations (single source for CLI and MCP) | 204 | src/core/operation-manifest.generated.ts |
| Public CLI commands / flags | 220 / 613 | docs/contracts/public-surface.json (CI-enforced) |
| CLI-only command records | 132 | src/cli/command-table.ts |
MCP tools (not cliOnly) |
186 | public-surface mcp-tool |
| MCP tools an HTTP client can ever see | 176 | 186 minus 10 localOnly ops |
| Verbs / starter surfaces | 7 / 41 | src/mcp/surface.ts |
| Error codes / distinct exit values | 707 / 17 (658 codes exit 1) | src/core/error-catalogue.ts |
| gbrain-evals files importing gbrain as a library | 131 (plus 116 path-based src/ imports in 68 files) |
agent-and-eval-usage.md section 1a |
Contract risks
These are the places where a Rust port can break agents or evals without a compile error. Each is detailed in the linked file.
- gbrain-evals is mostly a library consumer. 131 files import
gbrain/*modules and 68 runners load gbrainsrc/files by path. A Rust binary cannot satisfy these. Only the CLI argv (about 26 verbs), MCP stdio (about 28 tools) and the HTTP protocol v1 shim (eval/systems/PROTOCOL.md) are language-neutral. (agent-and-eval-usage.md section 1) - JSON bytes. CLI
--jsonisJSON.stringify(x, replacer, 2)plus a newline. MCP success text is compact JSON, but MCP errors are indented. Key order is insertion order. bigint ids are strings. JS number text (1not1.0,1e+21) andtoFixedrounding differ from Rust defaults. (cli.md A.7.1) - Content hash. SHA-256 over
JSON.stringifyof{title, type, compiled_truth, timeline, frontmatter, tags}, with JS key order (integer-like keys first), JS number and string escaping, and a frozen list of dropped frontmatter keys. Any difference changes every stored hash and forces re-import. (brain-format.md 5.5, 9.3) - YAML. gbrain uses js-yaml 4 with a calendar-checked timestamp type and merge keys. Rust YAML crates differ on YAML 1.1 booleans, octals, merge keys, tags and duplicate keys. A bare
date: 2024-06-01is stored as2024-06-01T00:00:00.000Z. (brain-format.md 9.1, 9.2) - Unicode slugs. Slug rules depend on Unicode tables (
\p{L}, NFD/NFC), CJK ranges and a frontmatter-slug fallback for emoji or exotic-script filenames. Node ICU and Rust crates can disagree on new code points. (brain-format.md 3, 9.4) - Errors are tool results, not JSON-RPC errors. MCP refusals return
{content, isError: true}with a versioned envelope (code,class,retryable,suggestion,docs,contract_version). The CLI exit code comes from the error code, not its class. (mcp.md 3, R8; cli.md A.5) - The visible tool list is computed per request. It depends on transport (stdio lists
localOnlyops, HTTP never does), OAuth scope, publish gates, bound-client fences, surface andstrict_params. A static list is wrong for most callers. (mcp.md 0.2, 2) - Tool and schema order and text.
tools/listorder is registry order (verbs first). Descriptions are byte-for-byte strings.initialize.instructionsis computed from the caller's callable set. (mcp.md R3-R7) - JSON on a pipe. Op-backed commands print human output unless
--jsonis passed. The fourcode-*commands switch to JSON automatically when stdout is not a TTY. Several CLI-only commands print JSON without a declared--jsoncontract, so the stdout guard does not protect them. (cli.md A.3.4, B.4.3) - Parser quirks. Excess positionals are dropped silently. Global flags are stripped even after
--.--flag falseconsumes the value. Nine names are both an op and a CLI-only command, and the CLI-only one wins. (cli.md A.7.4) - Single-writer storage drives the CLI design. While
gbrain serveholds the PGLite lock, many commands delegate over an IPC socket. The Rust storage choice decides whether that protocol is part of the port. (cli.md B.4.2) - Host-specific commands.
autopilotinstallers (launchd, systemd, cron),upgrade(Bun self-update with Sigstore checks),check-update,hook(exactgitoutput),pglite-repairandreinit-pglitehave no direct Rust equivalent. (cli.md B.4.1)
Open questions for Garry
- Eval seam. Should parity runs use the CLI and MCP stdio (as the Python
gbrain-defaultsshim does withGBRAIN_BIN), the HTTP protocol v1 shim, or both? The 131 library-import files cannot run against Rust without a TypeScript adapter. - v1 scope. The research suggests P0 = the agent and eval contract (
init,import,sync,export,embed,extract,serve,doctor,status,jobs,eval,capture,forget,call,dream,config,sources,hook,frontmatter validate, plus all op-backed commands), P1 = setup and auth, P2 or retire = installers, Bun upgrade paths and PGLite repair. Is that the right cut? - Byte identity. Must human output and
--helptext be byte-identical, or only--jsonand MCP output? Must the YAML writer reproduce js-yaml dump bytes, or only parse the same and hash the same? - Existing brains. Must Rust open existing PGLite or Postgres brains, or is a one-time export and re-import acceptable? This decides whether stored hashes, ISO date strings and the legacy hash formula must match exactly.
- Known oddities: keep or fix? Examples: silent drop of excess positionals,
String(date)for date-valued tags (timezone-dependent),noteas the default type for files without frontmatter, three.raw/sidecar layouts, exit 15 documented but never emitted, and three cliOnly ops listed indocs/TOOL_CATALOG.md. - MCP protocol versions. Accept the SDK 1.32.1 list (
2025-11-25back to2024-10-07) and echo the client's version, as the TypeScript server does today? - Legacy bearer HTTP transport (
src/mcp/http-transport.ts). It has no production caller, only tests. Drop it and re-point those tests at the OAuth transport? - Moving target. gbrain
mastermoves fast. It advanced 3 commits (to9f1d54232d) while this research ran; those commits did not changepublic-surface.jsonor the operation manifest. Which gbrain commit is the parity baseline, and how often do we re-sync these maps? - Library contract. gbrain-evals imports 31
package.jsonexportsentries and 100 non-exportedsrc/paths. Is any part of that a contract the Rust project must keep (for example through a TypeScript wrapper), or is it eval-internal?
Method and limits
- Five parallel research passes read the source with
file:linecitations. Handler-free modules (operation manifest, tool-defs, surface, callable, dispatch with a stub engine) were imported with Bun to produce the data files and the MCP error envelopes. - The gbrain CLI itself was not executed: it requires Bun >= 1.4.4 and the research host had 1.3.14. CLI JSON examples come from tests, golden fixtures and code literals, not live captures.
- No test suites were run. Engine-method columns in the large tables are from reading handlers and are marked as heuristics where they are.
- Line numbers refer to gbrain
8bbfd0b5e8. Re-check them after gbrain moves.