OneBrain

One Obsidian vault → one local brain → every AI agent sharing the same memory. 100% on-device, $0 API.

OneBrain is a thin, reproducible setup layer that puts all of your AI agents
(Claude Code, Codex, Grok, a self-hosted gateway/bot, Claude Desktop/Cowork) on a
single shared memory served from your own machine over MCP. Edit a fact once in
Obsidian and all of them see it.

It is not a new database or model. The actual brain is gbrain.

Credit: gbrain by Garry Tan

The entire intelligence layer here — the index, the knowledge graph, the synthesis,
and the ~80 MCP tools — is gbrain, the
open-source local-brain project by Garry Tan.
OneBrain is just the operational wrapping around it: launchd services, a
PGLite-safe sync loop, offline embeddings, secret hygiene, sandboxed enrichment,
multi-agent wiring, and the install scripts.

All credit for the hard part goes to Garry Tan and the gbrain project. If you find
OneBrain useful, go star github.com/garrytan/gbrain.

OneBrain pins a specific gbrain version for reproducibility (see Prerequisites).
gbrain is licensed under its own terms; this repo's MIT license covers only the wrapper
scripts, LaunchAgents, installer, and docs in this repository.

The problem

Run several AI agents day to day and each one keeps its own memory. The same facts
about your world — people, companies, projects, preferences — live in 4+ places, drift
apart, and there's no single place to ask. Classic agent amnesia, times four.

The shape

            Obsidian vault  (Markdown — the only durable store)
                  │   auto-sync every 5 min (PGLite-safe: serve bounces around writes)
                  ▼
   gbrain  (PGLite index + nomic-embed via Ollama + knowledge graph + synthesis)
                  │   one HTTP MCP server · 127.0.0.1 · bearer-token auth
                  ▼
   Claude Code · Codex · Grok · Cursor · Qoder · Warp · your gateway/bot · Claude Desktop
                  └────────── all query the SAME brain ──────────┘

• Source of truth: your Obsidian vault. Plain Markdown. Agents read it and write
  durable facts back into it.
• Brain layer: gbrain — indexes the vault into
  PGLite (embedded Postgres), builds a typed knowledge graph, exposes ~80 tools over MCP.
• Embeddings: nomic-embed-text in Ollama. Zero external API, nothing leaves the
  machine, $0 per query.
• Clients: every agent wired to the one HTTP MCP endpoint, each in its own config.

The diagram above is also an interactive HTML card in docs/architecture.html.
For the story of how and why this was built, see docs/how-i-built-this.md.

Orchestration (optional, recommended)

The brain is passive — so you can put any agent in charge of it. Designate one agent as an
orchestrator that runs on a schedule, reads context from the brain, dispatches work to the
others, and writes results back to the vault. Two real, MCP-native runtimes with built-in cron
and sub-agent fan-out are documented end to end in docs/orchestrator.md:

• OpenClaw — gateway + agent runtime, multi-agent routing.
• Hermes (Nous Research) — autonomous agent, built-in cron, spawns subagents.

Each connects to OneBrain as a remote HTTP MCP server with one config block (exact syntax for
both in the doc). You don't need one — any worker agent can orchestrate on-demand — but an
orchestrator makes the loop persistent and scheduled.

What's in this repo

bin/                    wrapper scripts (serve, sync, enrichment, sentinel, env, desktop bridge)
launchagents/           macOS LaunchAgents (auto-start, survive reboot)
tools/onebrain-agents.sh  detect installed agents and wire them to the brain
config/eval-queries.txt   probe set for the nightly contradiction check
docs/clients.md         how to wire Claude / Codex / Grok / a gateway / Claude Desktop
docs/orchestrator.md    put an agent in charge: OpenClaw / Hermes (Nous) integration
docs/troubleshooting.md every lesson that bit during the build
docs/architecture.html  the architecture infographic
install.sh              one-command install (idempotent)
uninstall.sh            clean removal (leaves your vault + secrets + DB intact)
.env.example            secrets template, copy to ~/.secrets/.env

Nothing here contains a secret. The scripts read tokens from ~/.secrets/.env at runtime.

Prerequisites

Pin gbrain for reproducibility, e.g.:

git clone https://github.com/garrytan/gbrain ~/Code/gbrain
cd ~/Code/gbrain && git checkout <the-commit-you-tested> && bun install

This setup was built and tested against gbrain v0.42.65.0. Treat the pin as a gate:
re-test the sync/serve/enrichment loop before upgrading.

Upgrade procedure that worked (2026-07-24, v0.42.42.0 to v0.42.65.0, 369 commits):
stop ai.gbrain.server so the PGLite lock is free, copy brain.pglite aside, rebase any
local patches onto upstream, bun install, bun run src/cli.ts apply-migrations --yes,
jobs smoke, restart serve, then compare get_health against the pre-upgrade numbers.
Note that apply-migrations runs its smoke phase by shelling out to a gbrain binary on
PATH; if you deliberately have no such binary, that phase fails while the migrations
themselves have already applied. Run bun run src/cli.ts jobs smoke yourself to confirm.

Install

# 1. secrets
cp .env.example ~/.secrets/.env && chmod 600 ~/.secrets/.env
$EDITOR ~/.secrets/.env          # set tokens + OBSIDIAN_VAULT_PATH + GBRAIN_REPO

# 2. one-time index of your vault (serve must be stopped; PGLite single-writer)
cd ~/Code/gbrain && env -u OPENAI_API_KEY bun run src/cli.ts sync --repo "$OBSIDIAN_VAULT_PATH"

# 3. install services (add --enrichment for the nightly sandboxed self-tidy)
./install.sh

Verify:

launchctl print gui/$(id -u)/ai.gbrain.server | grep state
curl -s -H "Authorization: Bearer $GBRAIN_REMOTE_TOKEN" http://127.0.0.1:3131/health

Then wire your agents — docs/clients.md.

What you get

• Shared memory across every agent, queryable in natural language.
• 100% offline — embeddings and storage never leave the machine; no per-query cost.
• Survives reboot — LaunchAgents auto-start; works before you even sign in to apps.
• Safe by construction — secrets evicted from the vault, loopback + bearer auth,
  PGLite-safe sync, and a sandboxed enrichment daemon with a kill-switch + watchdog.
• Reversible — your vault is plain Markdown under git; the gbrain DB is a rebuildable index.
• Verified, not assumed — a daily sentinel that refuses to absorb its own regressions, an
  off-machine vault backup on every commit, and a wiring report that checks config against reality.

Wiring agents (and checking they are actually wired)

tools/onebrain-agents.sh          # report which installed agents can reach the brain
tools/onebrain-agents.sh --wire   # wire the ones that cannot
tools/onebrain-agents.sh --json   # machine-readable, for a cron or dashboard

It detects Claude Code, Codex, Grok, Cursor, Qoder, QoderWork, Warp, Hermes, opencode and
Antigravity, writes each one's native format (JSON mcpServers or TOML [mcp_servers.*]),
backs the config up first, and only ever touches the gbrain entry. It is idempotent, so it
is safe on a cron. Agents whose MCP schema it cannot verify are reported as MANUAL rather
than written to blindly.

Why this exists. An audit on 2026-07-24 found this project's own architecture diagram
claiming four agents were wired while the busiest one, Claude Code, had zero MCP servers
configured and no occurrence of the string gbrain anywhere in its config. Nine of twelve
installed agents could not reach the brain their own instruction files named as the source of
truth. Documentation drifted from reality because nothing compared the two. Run the report,
do not trust the diagram.

Verification: the part that actually keeps this honest

A memory system fails quietly. Nothing errors, answers just get subtly wrong. Every real
fault found in this stack was silent:

So the wrapper ships three checks:

• bin/gbrain-sentinel.sh (ai.gbrain.doctor, daily): queries the running server over
  MCP, compares against ~/.gbrain/health-baseline.json, and on regression writes
  ~/.gbrain/ALERT.json, sends a push notification, and holds the baseline at the last
  known-good values so the regression keeps alerting until it is genuinely fixed. Only a
  clean run advances the baseline. Delete the baseline file to accept new numbers on purpose.
• Off-machine backup inside bin/gbrain-sync.sh: mirrors the vault git to a second
  machine on every changed commit, connection-bounded and non-fatal so an unreachable target
  can never stall or fail brain sync.
• config/eval-queries.txt: questions about facts that actually go stale in your world,
  fed to gbrain eval suspected-contradictions nightly. Runs fully local at $0.

If you take one thing from this repo, take the sentinel pattern. A detector that heals its
own alarm is worse than no detector, because it looks like everything is fine.

Choosing a local chat model

chat_model is only needed for the synthesis and dream tiers, not for search or embeddings.
Size it to the machine, and measure rather than trusting ollama ps, which reports
"100% GPU" even while the model is thrashing through swap.

Measured on a Mac mini M4 / 16GB:

The larger model is not the better model when it does not fit.

Multi-machine

Run the same install on a second Mac. Keep the vault in sync with Obsidian Sync (each
machine runs its own gbrain index over the same Markdown, so page counts converge rather
than match instantly). Run the heavier --enrichment agent on one machine only.

Security notes

• Tokens live only in ~/.secrets/.env (chmod 600) and are read at runtime. Never commit them.
• The MCP server binds to 127.0.0.1 and still requires a bearer token.
• Keep secrets out of the indexed vault — anything indexed is visible to every wired agent.
• See docs/troubleshooting.md for the full list of footguns.

License

MIT (this repo's wrapper code/docs) — see LICENSE.
The brain itself, gbrain by Garry Tan, is a
separate project under its own license. Please credit it.