---
name: gbrain-ops
description: "Operate GBrain (garrytan/gbrain) as Hermes' vector-memory engine on the VPS — the PGLite single-process rule that flips CLI vs MCP usage, freshness loops, cost-mode governance, and retrieval tuning. Trigger for anything GBrain after install (re-indexing, embed refreshes, overnight consolidation, doctor health, query quality, is-gbrain-actually-being-used, install/upgrade). Install mechanics themselves live in installing-clis-on-readonly-home (Bun/GMAPS section); MCP wiring + the mcp==1.0.0 stdio shim live in operating-hermes-gateway."
---

# Operating GBrain as Hermes' Memory Engine

GBrain is a third memory layer alongside built-in memory/skills and the vault
MCP (hermes-vault-mcp on :9123). Division of labor (Rob's words, agreed
2026-08-06): **Obsidian vault = static storage layer; GBrain = intelligent
compute/retrieval engine on top of those same markdown files.** GBrain does NOT
replace built-in memory (8K-cap governance stands) or skills — it adds semantic
search, hybrid query, link graph, and overnight consolidation over the
Syncthing-mirrored vault at `/root/.hermes/vault`.

## Layout on this VPS

- Bun: `/root/.hermes/bun/bin/` (BUN_INSTALL override — read-only `/root`)
- GBrain CLI: `/root/.hermes/bun/bin/gbrain` (v0.42.73.2, installed via
  `bun install -g github:garrytan/gbrain` — NEVER npm registry, the `gbrain`
  npm package is an unrelated squatter)
- Brain state: `GBRAIN_HOME=/root/.hermes/gbrain-home` (PGLite embedded
  Postgres in `brain/`, pgvector 1536-dim, `openai:text-embedding-3-large`)
- MCP wrapper: `/root/.hermes/bin/gbrain-mcp` (sets PATH + GBRAIN_HOME +
  GBRAIN_NO_ONBOARD_NUDGE=1, then `exec gbrain "$@"`)
- Hermes wiring: `mcp_servers.gbrain` in config.yaml → `gbrain serve` stdio,
  spawned by the gateway via `mcp_stdio_watchdog.py`. Exposes 106 tools.
- Embedding/chat keys: picked up from `/root/.hermes/.env` (OPENAI_API_KEY
  present; ANTHROPIC key enables query expansion — currently unset, so
  expansion is skipped).

## RULE 0: PGLite is single-process — the gateway owns the DB

When `gbrain serve` runs under the gateway, it holds an exclusive lock
(`$GBRAIN_HOME/brain/.gbrain-lock`). **Any CLI command (`gbrain import`,
`gbrain embed`, `gbrain query`, `gbrain doctor`) from a shell will refuse:**

> "GBrain's local database is already open through `gbrain serve` (MCP, PID
> N)... Stop `gbrain serve`, then retry this CLI command."

Consequences:

- **All routine ops go through MCP tools, not the CLI.** The 106-tool surface
  includes import/embed equivalents — have the agent (or a cron prompt) call
  them through the running server. Do NOT design a shell cron that runs
  `gbrain import && gbrain embed --stale`; it will fail with the lock error
  every time. (The original GBrain setup doc's crontab pattern assumes no
  long-lived `serve` process — wrong for a gateway install.)
- **CLI is for install-time / maintenance windows only** (gateway stopped or
  pre-wiring): `init`, `apply-migrations`, `upgrade`, deep `doctor --fix`.
- **Quick health check without touching the lock:** `pgrep -af "gbrain serve"`
  (child of `mcp_stdio_watchdog.py` = gateway owns it, healthy) and
  `/root/.hermes/venv/bin/hermes mcp` (should list `gbrain — custom — enabled`).
- **Lock proof = liveness proof.** If a CLI command refuses with the lock
  message naming the serve PID, that IS the confirmation the MCP server is
  up and owns the DB. Don't treat it as an error to fix.

## Cost governance (Rob is cost-sensitive — honor this)

- **Search mode: `conservative`** (set at install). `gbrain init` silently
  defaults to `tokenmax` — the most expensive tier, ~25x corner-to-corner
  spread at 10K queries/mo. Never silently accept a mode; the matrix must be
  shown to Rob. `gbrain config set search.mode <conservative|balanced|tokenmax>`.
- **Overnight consolidation / autopilot / takes-bootstrap: OFF by default.**
  These spend LLM tokens. Enable only after retrieval quality proves out, and
  only with an explicit `--max-usd` cap (`gbrain onboard --auto --max-usd 5`).
  `takes extract` sends page content to a chat model — two-gate opt-in by
  design; don't bypass.
- `GBRAIN_NO_ONBOARD_NUDGE=1` is set in the wrapper to keep banners out of
  MCP stdio frames (a banner on stdout corrupts JSON-RPC).

## Eval-week tuning notes (from first live queries, 2026-08-06)

- Import of the full vault: 56 pages, 116 chunks, ~20s; embed ~30s. Tiny
  corpus — cheap to re-import wholesale.
- First semantic query ("Rob's positioning for RRR") ranked Job Seeker docs
  above the RRR positioning file — keyword "positioning" collided with
  resume-tailoring docs. Retrieval works; ranking needs the consolidation
  passes and/or query expansion before trusting it for recall-critical answers.
  When a query misses, check `gbrain query` scores directly (in a maintenance
  window) before assuming the content isn't indexed.
- The vault corpus is small (2.5MB) — keyword fallback (`search` tool) is
  often as good as `query`; prefer `query` only when semantic fuzz matters.

## Verifying Hermes actually uses it

- MCP registration is per-session tool-list: a session started BEFORE the
  gateway restart won't see gbrain tools (stale cache, not a wiring failure).
  Test in a FRESH session.
- `journalctl -u hermes-gateway | grep -iE "gbrain|errlog"` — the mcp==1.0.0
  `errlog` stdio bug is shimmed (see operating-hermes-gateway); if `errlog`
  errors reappear after any pip reinstall, re-apply from
  `/root/.hermes/patch-backup-0.19.0/mcp_tool.py.pre-gbrain-20260806`.
- Standalone probe (gateway stopped or pre-serve): python stdio JSON-RPC
  `initialize` → `tools/list` against `/root/.hermes/bin/gbrain-mcp serve`
  should return 106 tools.

## Upgrade path

`gbrain upgrade` (self-update + migrations) — run in a maintenance window
(CLI needs the lock). Bun global installs can block the top-level postinstall
hook → schema_version 0; recovery: `gbrain apply-migrations --yes`
(issue #218). GBrain moves fast (multiple releases/week); pin expectations
accordingly and re-run `gbrain doctor --json` after any upgrade.

## Related

- Install mechanics (Bun via BUN_INSTALL, GBRAIN_HOME discovery, npm-squatter
  trap): `installing-clis-on-readonly-home` → `references/gmaps-on-vps.md`.
- MCP wiring, config.yaml string-quoted args fix, the errlog shim:
  `operating-hermes-gateway` (+ its `references/gbrain-memory-engine.md`).
- The vault MCP it complements (Claude Desktop side):
  `operating-hermes-gateway` → `references/remote-mcp-claude-desktop.md`.