Plain English first. Source detail on click.

Understand the whole brain before installing it again.

GBrain is not one database command. It is a loop that turns durable files into searchable pages, graph relationships, cited answers, and future agent memory. This manual shows each layer, the exact upstream source behind it, and the safe Fulcrum install path.

GBRAINdurable memory

Read

Write

Sync

Learn

Upstream fact

Directly documented or implemented in the pinned gbrain source.

Fulcrum recommendation

Our deployment choice for Orgo + Hermes client cells.

Verify live

Must be proved on the exact client VM before calling it complete.

The one mental model

Files are truth. The database is the working brain.

Source ↗

1

Durable files

Markdown pages and source repos remain readable, reviewable, movable truth. They are separate from the gbrain tool repo.

2

Indexed structure

GBrain parses pages into rows, chunks, embeddings, links, facts, timelines, versions, and source metadata.

3

Agent interface

CLI and MCP operations expose the same brain contract. Hermes launches the MCP server as a subprocess.

4

Compounding loops

Sync, embed, graph extraction, fact reconciliation, dream, health checks, and human review keep the brain useful.

Do not confuse these

Four different things called “the brain”

Thing	What it is	Where it lives	What breaks if wrong
GBrain tool repo	The TypeScript product and bundled docs/skills	GitHub install or clone	Wrong binary, stale docs, bad upgrade
Brain repo	Your/client markdown knowledge estate	Private Git repo or local folder	No durable truth or wrong source routing
Brain database	Pages, chunks, vectors, graph, facts, versions	PGLite or Postgres/Supabase	No retrieval, concurrency, or isolation
Agent workspace	Hermes identity, skills, MCP config, runtime	Each Orgo client VM	Agent cannot use or maintain the brain

The definition of done

“Installed,” “running,” a successful MCP add exit code, non-zero page counts, or embeddings alone do not prove a working brain. A fresh source change must sync, embed, retrieve through Hermes with a citation, survive a restart, and remain isolated from every other client.

Clickable architecture

Follow one fact through the entire system.

Click any node for plain-English purpose, exact files, inputs, outputs, failure modes, and source links. Use the view controls to focus the map.

Signal/sourceGBrain processPersistent stateAgent surfaceSolid = data pathDashed = maintenance/control

Invariant

Embedding is outside the engine

The engine stores vectors and searches them. The AI gateway generates them. This is why a model mismatch can return plausible but wrong results.

Engine design ↗

Invariant

Brain and source are separate axes

A brain selects the database. A source selects a repo inside that database. If data ownership changes, use a brain boundary.

Routing model ↗

Client boundary

One client, one cell

Use a separate Orgo VM, brain repo, Supabase destination, gbrain home, connector tenancy, and credentials per client.

Production lane

Orgo + Hermes install, one proof gate at a time.

This is an operator study runbook. It is intentionally sequential. Do not advance because a command returned zero. Advance only when the proof condition is true.

0%complete

Extremely terse handoff

What the Hermes agent reads, in order

Read these files completely in this order from the pinned latest-stable gbrain source:
1. AGENTS.md
2. INSTALL_FOR_AGENTS.md
3. docs/ENGINES.md
4. docs/integrations/embedding-providers.md
5. docs/mcp/HERMES.md
6. skills/RESOLVER.md
7. docs/guides/cron-schedule.md
8. docs/GBRAIN_VERIFY.md

Install one isolated client brain only. Use the explicit client-specific GBRAIN_HOME, brain repo, Postgres URLs, Voyage key, and Hermes home supplied by the operator. Never reuse another client's credentials, source ID, database, or connector account. Stop at every decision or failure gate. Do not claim completion until the full source-change → sync → embed → Hermes retrieval → citation → restart → retrieval canary passes.

How it compounds

The loops are the product.

A database sitting online is not a functioning brain. These loops move new signal into durable truth, keep retrieval current, detect failures, and improve synthesis.

Nightly maintenance

The current dream cycle phase order

Source ↗

Not every phase always runs.

Several phases are feature-gated, schema-pack-gated, source-scoped, or disabled by default. “gbrain dream finished” does not mean each phase changed data. Inspect the phase report and remaining backlog.

Two surfaces, one contract

Commands for operators. Tools for agents.

The CLI includes local-only operations and maintenance commands. MCP exposes scoped operations to Hermes and other agents. Search the pinned source catalog below.

Behavior layer

Skills teach Hermes how to use the brain.

GBrain provides the storage and operation surface. Skills provide procedures, triggers, quality rules, and sequencing. The resolver tells the agent which skill to read for a request.

Open resolver ↗

→ → → →

Bundled skill catalog

Measured skill improvement

SkillOpt treats a skill body like trainable parameters.

It evaluates the current skill, proposes text edits, tests candidates against a benchmark, and accepts only a measured improvement. It is not a free-form nightly rewrite.

Exact skill contract ↗

Gate 1

Benchmark first

No trustworthy benchmark means no trustworthy optimization. Generated starter judges require human strengthening.

Gate 2

Body only

Triggers and other frontmatter do not change. Routing behavior stays invariant.

Gate 3

Median of 3

A candidate must beat the selection baseline by at least epsilon 0.05.

Gate 4

Bundled skills protected

Default behavior writes a proposal. In-place changes require explicit opt-in and an independent held-out set.

Gate 5

Cost and time capped

Preflight refuses work beyond the configured budget. Runs are lock-protected and resumable.

Gate 6

Nightly is review-first

The dream-cycle SkillOpt phase is off by default and does not auto-mutate bundled skills.

Common first run

Start a benchmark

gbrain skillopt my-skill --bootstrap-from-skill
# Human reviews and strengthens judges
gbrain skillopt my-skill --bootstrap-reviewed --split 1:1:1 --dry-run

Safe review path

Propose without mutation

gbrain skillopt my-skill \
  --benchmark skills/my-skill/skillopt-benchmark.jsonl \
  --no-mutate --dry-run

Pinned repo browser

Explore the source without drowning in it.

This catalog was generated from every tracked source file in the pinned stable commit. Select a file to see exports, local imports, related files, and the native GitHub source.

Select a file

Its role and connections will appear here.

Fulcrum deployment recommendation

How your chosen stack should fit together.

This page separates native gbrain components from the surrounding Fulcrum client-cell infrastructure.

Decisions

Recommended default for client Hermes agents

Layer	Recommended	Why	Boundary
Compute	One Orgo VM per client agent cell	Simple ownership and process isolation	Do not share runtime homes or credentials
Agent	Hermes on the client VM	Local stdio MCP, skills, sessions, scheduler	Use the exact client HERMES_HOME
Database	Separate Supabase project or database per client	Postgres concurrency, pgvector, managed backup	Source filters are not a substitute for tenant isolation
Embeddings + rerank	Voyage AI	Native default uses one key for voyage-4 and rerank-2.5	Pin model and 1024 dimensions at init
Hermes inference	OpenRouter if desired	One key can simplify Hermes chat model access	Do not assume it replaces every gbrain subagent/provider path
Business connectors	Composio per client	Gives Hermes controlled service access	It is not durable gbrain ingestion by itself
Durable source	Private client brain repo	Human-readable truth and recoverability	Never put source content inside the gbrain tool repo

Why Voyage instead of “OpenRouter for everything”?

Upstream v0.47.3.0 supports OpenRouter embeddings, but Voyage is the native default and pairs its embedding model with a supported reranker on the same key. OpenRouter can simplify Hermes chat inference. It does not simplify the whole gbrain path because gbrain’s protected subagent loop remains Anthropic-direct, and reranking still needs an explicit supported route.

Diagnose by layer

Start with the symptom. Prove the failing boundary.

Do not reinstall first. A healthy-looking outer layer can hide a broken inner layer.

Golden canary

The one acceptance test that crosses every layer

WriteAdd a unique, harmless fact to a test page in the correct client brain repo.
SyncRun or observe the exact source sync and confirm the page count/checkpoint advances.
EmbedConfirm stale embeddings drain and dimensions match the configured model.
RetrieveAsk Hermes naturally. Confirm it calls gbrain and returns the unique fact with its source.
RestartRestart the Hermes/gbrain service path and repeat retrieval in a fresh session.
IsolateProve a different client cell cannot retrieve the test fact.
ReverseRemove or correct the test fact, sync again, and prove the old value no longer wins.