Garry's Opinionated OpenClaw/Hermes Agent Brain
Rust engine research maps
These twelve maps are research for a Rust third engine behind BrainEngine, next to PGLite and Postgres. The design they feed is in ../../RUST_ENGINE.md. Each map reads the TypeScript implementation and its tests and records what a Rust engine must match, what it can simplify, and which questions are still open.
Precedence. The maps were written before the design was settled, and some of their implication sections explore a wider rewrite: one engine instead of a parity matrix (01), a Rust CLI and middleware (05), dropping the engine test matrix and TypeScript guards (10), a stdio oracle-ts route for gbrain-evals (11) and dropping the embedded PGLite lane (12). Those passages are kept as research history and do not bind. The approved ../../RUST_ENGINE.md governs: it keeps the TypeScript surfaces, keeps PGLite and Postgres as engines, and defers the stdio route. Where a map and the plan disagree, the plan wins.
Pinned commits
- gbrain:
36bd05806a(v0.60.733.0). Line numbers in every map refer to this commit. - gbrain-evals:
9ecc5b20(2026-05-24). That commit is about 3,500 commits behind gbrain-evals main as of 2026-11-16, so11is history for that repository: its counts, broken-runner notes and pin status are out of date, and the plan's D11 records the current terms.
Evidence tags
Each map tags its claims as verified (code read), reported (doc quote) or inferred. The tag letters differ slightly per map (for example [V], [I], [R], [D], [C], or "(inferred)"), and each map states its own legend near the top.
Maps
| Map | Summary |
|---|---|
| 01-engine-interface.md | The BrainEngine seam, engine-sql, and how much raw SQL bypasses the interface. |
| 02-schema.md | src/schema.sql table by table: indexes, triggers, RLS, migration-created tables, and graduation inventory. |
| 03-search-pipeline.md | Retrieval and ranking end to end: arms, fusion, boosts, filters, and the Postgres features each piece needs. |
| 04-ingest-chunk-embed.md | The write path: parse, chunk, embed, store, plus the triggers that fire on write. |
| 05-cli-mcp-surface.md | The agent-facing surface: operations, CLI verbs, MCP surfaces, scopes, and exit codes. |
| 06-graph-and-knowledge.md | The knowledge layer: links and graph traversal, entities, facts, takes, timeline. |
| 07-jobs-and-cycles.md | The Minions job queue, autopilot, and the cycle phases. |
| 08-concurrency-and-persistence.md | Locking, persistence ownership, and the multi-process model. |
| 09-access-and-security.md | Trust boundary, credentials, per-member access, and the invariants the database enforces today that must move into Rust code. |
| 10-tests.md | The TypeScript test suites as a parity oracle, and a GBRAIN_BIN harness proposal. |
| 11-gbrain-evals.md | gbrain-evals as a parity oracle: runners, gates, and what a Rust engine must satisfy. |
| 12-perf-and-operations.md | Performance, scale, and operations: sizing, budgets, install and upgrade paths, and what users need to switch. |