Plain English first. Source detail on click.

Understand the whole brain before installing it again.

This manual has two separate lanes. Native Upstream explains only the pinned GBrain repository. Fulcrum Overlay explains how Fulcrum applies it with Orgo, Hermes, Supabase, Voyage, Composio, and isolated client cells.

GBRAINdurable memory

Read

Write

Sync

Learn

Lane 1

Native Upstream GBrain

Architecture, install, commands, skills, loops, verification, and source atlas from the pinned repository only.

Lane 2

Fulcrum Stack

Orgo, client isolation, Supabase and Voyage choices, Composio policy, deployment sequencing, and client acceptance.

Boundary rule

One-way reference

Fulcrum pages may cite native pages. Native pages never treat a Fulcrum decision as an upstream requirement.

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	User or team markdown knowledge estate	Git repo or local folder	No durable truth or wrong source routing
Brain database	Pages, chunks, vectors, graph, facts, versions	PGLite or Postgres	No retrieval or expected concurrency
Agent workspace	Harness identity, skills, MCP config, runtime	Supported agent workspace	Agent cannot use or maintain the brain

Native definition of done

Installation is not proven by a binary, process, MCP add exit code, page count, or existing embeddings. The upstream verification runbook must prove schema, source coverage, live sync, embedding coverage, search, graph, integrity, updates, and configured agent behavior.

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 ↗

Invariant

Skills and MCP are different layers

MCP exposes operations. Skills and the resolver teach an agent when and how to use those operations.

Skillpack design ↗

Native upstream lane

Install GBrain exactly as the pinned repository defines it.

This page contains no Orgo topology, Fulcrum tenancy, Composio policy, or cross-client requirements. Apply those later from the separate Fulcrum deployment runbook.

0%complete

Native handoff

What the installing 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

Follow only the native GBrain procedures these files define. Ask at every upstream decision gate. Do not add hosting, tenancy, connector, or client-isolation assumptions that are not present in the upstream sources. Do not claim native installation health until every check in docs/GBRAIN_VERIFY.md 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.

Everything on this page is Fulcrum-specific.

Native GBrain supports several engines, providers, harnesses, transports, and deployment shapes. This page records Fulcrum's selected architecture. It does not redefine upstream GBrain.

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.

Fulcrum overlay lane

Apply Fulcrum gates around the native install.

This combined checklist links to upstream evidence but adds Fulcrum requirements for client boundaries, Orgo ownership, provider tenancy, Composio persistence, and acceptance.

0%complete

1Learn native

Complete the native architecture and install study first.

2Apply overlay

Run the Fulcrum checklist below under the exact client identity.

3Prove both

Pass native verification, then the Fulcrum client-cell canary.

Fulcrum handoff

How the client agent follows both lanes

First read and follow the native GBrain sources in the Native Install page. Then apply the Fulcrum Deployment Runbook under the exact client-specific Orgo VM, runtime user, HERMES_HOME, GBRAIN_HOME, brain repo, database, provider keys, and Composio tenant supplied by the operator. Never infer or reuse another client's identity, credentials, source, or database. Native GBrain verification must pass before the Fulcrum golden canary. Do not call the client cell complete until restart, durable connector persistence, cross-client denial, and correction all pass.

Native upstream verification

Prove GBrain before adding deployment assumptions.

These checks cover native GBrain, supported engines, providers, integrations, and supported harness connections.

Native completion

Run every check in docs/GBRAIN_VERIFY.md. Live source-edit sync is the most important proof. Client isolation and Composio persistence are separate Fulcrum checks.

Fulcrum client-cell verification

Prove the full service after native GBrain passes.

This lane adds Orgo ownership, Hermes behavior, provider environment, connector persistence, restart durability, and cross-client denial.

Fulcrum golden canary

The acceptance test for the complete client cell

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.