Setting Up GBrain: Shared AI Memory Brain

# 🧠 Setting Up GBrain: Shared AI Memory Brain Backed by Supabase pgvector

**Date:** July 16, 2026  
**Tags:** GBrain, AI, Memory, Supabase, pgvector, MCP, Self-Hosted, AI Providers / LLM

---

## 🎯 Overview

[GBrain](https://github.com/earendil-works/gbrain) is a **shared knowledge brain** for AI agents — a memory + retrieval system that teaches your agents everything else beyond coding. On this VM it is the **single source of truth** that all 9 agents (Hermes, OpenClaw, Pi, OpenCode, Codex, Claude Code, Cursor, Continue, Windsurf) read from and write to via MCP.

GBrain is pluggable: it can run on an embedded **PGLite** (WASM Postgres, zero-config) or a managed **Postgres + pgvector** instance. This guide covers the **Supabase (pgvector)** deployment — the production setup used here — including how it **backs up to GitHub** and all the configuration needed to bring it online.

### Why GBrain?

| Feature | Benefit |
|---------|---------|
| **🧩 Shared Memory** | All agents read/write one brain (no per-agent silos) |
| **🔎 Hybrid Search** | pgvector embeddings + keyword + rerank |
| **🔌 MCP Native** | `gbrain serve --http` exposes tools to every agent |
| **☁️ Supabase** | Managed Postgres + pgvector, pooled connections |
| **🐙 GitHub Backup** | `gbrain-brain` + `gbrain-workspace` mirror the brain offsite |
| **🆓 9Router Models** | Embeddings/chat via free 9Router endpoints |

> 📎 **Original project:** https://github.com/earendil-works/gbrain

---

## 🏗️ Architecture Overview

```
   All 9 agents (Hermes, OpenClaw, Pi, OpenCode, Codex, Claude Code, ...)
        │  MCP (stdio or HTTP :3131)
        ▼
   gbrain serve --http --port 3131 --bind 0.0.0.0
        │
        ▼
   Supabase Postgres + pgvector  (project: zgmlfkdjjgahfnvyugct)
     ├─ Transaction Pooler  :6543  (reads)
     └─ Session Pooler      :5432  (migrations)
        │
        ▼ (offsite mirror / backup)
   GitHub: ryanthemanr0x/gbrain-brain      (brain content)
   GitHub: ryanthemanr0x/gbrain-workspace  (working notes)
        │
   Models via 9Router (http://192.168.51.115:20128/v1)
     ├─ embeddings: 9router:mxbai-embed-large (1024d)
     └─ chat/expansion: 9router:Free
```

---

## 📋 Requirements

- A **Supabase** project with **pgvector** enabled (Postgres + vector extension). Note the **project ref** and the two pooler connection strings (transaction `:6543`, session `:5432`).
- A **9Router** endpoint (or any OpenAI-compatible embeddings/chat provider) — see the [9Router guide](/blog/9router-setup/).
- **Bun** installed (GBrain ships as a Bun binary at `~/.bun/bin/gbrain`).
- Two **GitHub** repos for offsite backup: `gbrain-brain` and `gbrain-workspace`.
- A non-root user (`ryan` in examples).

> ⚠️ **Security note:** Every secret below is a ``. Never commit real keys.

---

## ⚙️ Step 1 — Install GBrain

GBrain runs as a Bun binary:

```bash
# Binary location on this VM
ls -la /home/ryan/.bun/bin/gbrain   # -> Bun-compiled gbrain CLI

# Verify
/home/ryan/.bun/bin/gbrain --help

# Or install/upgrade via the project
# bun install   # from a gbrain checkout
```

---

## 🗄️ Step 2 — Supabase Backend (pgvector)

GBrain's brain lives in Supabase Postgres with the **vector** extension. Two connection strings are used:

- **Transaction Pooler** (`db..pooler.supabase.com:6543`) — used for normal reads/writes (connection reuse, no prepared statements).
- **Session Pooler** (`db..pooler.supabase.com:5432`) — used for **migrations** (needs a stable session).

```text
SUPABASE_PROJECT_REF = "zgmlfkdjjgahfnvyugct"
SUPABASE_TX_POOLER    = "postgresql://postgres.:@aws-0-ca-central-1.pooler.supabase.com:6543/postgres"
SUPABASE_SESSION_POOLER = "postgresql://postgres.:@aws-0-ca-central-1.pooler.supabase.com:5432/postgres"
```

Enable the extension (one-time, via the Supabase SQL editor or a migration):

```sql
create extension if not exists vector;
```

> 💡 GBrain bootstraps its own schema (tables, indexes, pgvector columns) on first run via its migration set — you mostly just need the **vector** extension present.

---

## 🔧 Step 3 — GBrain Config (`~/.gbrain/config.json`)

The core config selects the engine, the database, the models, and MCP behavior:

```json
{
  "engine": "postgres",
  "database_url": "",
  "embedding_model": "9router:mxbai-embed-large",
  "embedding_dimensions": 1024,
  "expansion_model": "9router:Free",
  "chat_model": "9router:Free",
  "schema_pack": "gbrain-base-v2",
  "mcp": {
    "publish_skills": true
  },
  "self_upgrade": {
    "mode": "notify",
    "mode_prompted": true
  },
  "embedding_disabled": false
}
```

Key fields:

- `engine: "postgres"` — use Supabase (not the default PGLite).
- `database_url` — the **transaction pooler** URL (reads/writes).
- `embedding_model` — `9router:mxbai-embed-large` at **1024 dimensions** (served free by 9Router).
- `expansion_model` / `chat_model` — `9router:Free`.
- `schema_pack` — `gbrain-base-v2` (the page/source schema).
- `mcp.publish_skills` — expose GBrain skills to agents over MCP.

> 🔐 The DB password lives only in the placeholder URL. GBrain also reads `GBRAIN_DATABASE_URL` / `GBRAIN_DIRECT_DATABASE_URL` env vars (the session-pooler URL is used for migrations).

---

## 🔌 Step 4 — HTTP MCP Server (port 3131)

GBrain exposes an MCP server so agents can call it. We run the **HTTP** transport on port **3131**:

```bash
# start-gbrain-mcp.sh (concept)
#!/usr/bin/env bash
export PATH="$HOME/.bun/bin:$PATH"
export GBRAIN_DATABASE_URL=""
export GBRAIN_DIRECT_DATABASE_URL=""

MCP_PORT=3131
MCP_BIND="0.0.0.0"

# Start the HTTP MCP server in the background
nohup gbrain serve --http --port "$MCP_PORT" --bind "$MCP_BIND" \
  > /home/ryan/gbrain-mcp.log 2>&1 &
```

Agent MCP configs then point at it:

```json
{
  "mcpServers": {
    "gbrain": {
      "command": "/home/ryan/.bun/bin/gbrain",
      "args": ["serve"],
      "env": {
        "GBRAIN_DATABASE_URL": "",
        "GBRAIN_DIRECT_DATABASE_URL": ""
      }
    }
  }
}
```

> 🌐 The HTTP MCP endpoint is reachable by Hermes/OpenClaw at `http://localhost:3131` (or the LAN bind). Each agent's MCP config references the same brain.

---

## 🐙 Step 5 — GitHub Offsite Backups

The **live** brain is Supabase. The **offsite mirror/backup** is two GitHub repos:

| Repo | Contents |
|------|---------|
| `ryanthemanr0x/gbrain-brain` | The brain content (pages, sources, structured memory) |
| `ryanthemanr0x/gbrain-workspace` | Working notes, drafts, workspace artifacts |

A setup script wires both repos and the Supabase + 9Router config together:

```bash
# gbrain-setup.sh (sanitized concept)
GH_WORKSPACE_REPO="ryanthemanr0x/gbrain-workspace"
GH_BRAIN_REPO="ryanthemanr0x/gbrain-brain"

SUPABASE_PROJECT_REF="zgmlfkdjjgahfnvyugct"
SUPABASE_TX_POOLER=""
SUPABASE_SESSION_POOLER=""

NINEROUTER_API_KEY=""
NINEROUTER_BASE_URL="http://192.168.51.115:20128/v1";

MODEL_MAIN="openrouter/free"
MODEL_EMBEDDINGS="openrouter/openai/text-embedding-3-small"
MODEL_RERANK="openrouter/cohere/rerank-3"

WORKSPACE_DIR="/home/ryan/gbrain-workspace"
BRAIN_DIR="/home/ryan/gbrain-brain"
MCP_PORT=3131
```

Backup rhythm (concept — automated via cron):

```bash
# 1. Pull latest brain from Supabase into the local workspace
# 2. Commit + push to GitHub (offsite mirror)
cd /home/ryan/gbrain-brain && git add -A && git commit -m "backup: $(date -u +%FT%TZ)" && git push
cd /home/ryan/gbrain-workspace && git add -A && git commit -m "backup: $(date -u +%FT%TZ)" && git push
```

> 🧠 **Division of responsibility:** Supabase is the **source of truth** (fast reads/writes, pgvector search). GitHub is the **durable offsite copy** — if Supabase is wiped, the brain is reconstructable from the repos. Runtime artifacts (session logs, caches) are *not* backed up; they are rebuildable.

---

## 🧪 Step 6 — Smoke Test

```bash
# 1. GBrain CLI resolves
/home/ryan/.bun/bin/gbrain --help

# 2. MCP server is healthy
/home/ryan/.bun/bin/gbrain get_health
# -> healthy

# 3. List pages (proves DB + schema reachable)
/home/ryan/.bun/bin/gbrain list_pages --limit 5

# 4. Hybrid search works (proves pgvector + embeddings)
/home/ryan/.bun/bin/gbrain query "how is ninerouter configured?"

# 5. Supabase reachable with the pooler URL (placeholder)
psql "" -c "select 1;"

# 6. Agent MCP config sees gbrain tools
#    (check Hermes/OpenClaw MCP tool list for `gbrain_*)
```

Expected: `get_health` healthy, `list_pages` returns rows, `query` returns relevant pages, and `psql` connects.

---

## 🩺 Troubleshooting

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| `get_health` unhealthy | Bad DB URL / `vector` ext missing | Verify ``, enable `vector` |
| Embeddings fail | Wrong `embedding_dimensions` | Must match model (mxbai-embed-large = 1024) |
| Migrations fail | Used TX pooler (`:6543`) | Use **session pooler** `:5432` for migrations |
| Agents can't call tools | MCP not started / wrong port | Ensure `gbrain serve --http --port 3131` is up |
| 9Router 401 | Expired key | Re-export `` |

---

## 🔐 Security Checklist

- [ ] Supabase pooler URLs are ``s; DB password is least-privilege.
- [ ] `` injected via env, never committed.
- [ ] MCP bind (`0.0.0.0:3131`) restricted to trusted LAN / localhost only.
- [ ] GitHub backup repos use a scoped PAT (``), stored outside the brain.
- [ ] `self_upgrade.mode: notify` (not auto) — you approve upgrades.

---

## ✅ Summary

You now have **GBrain** running as the shared memory brain:

- Installed as a Bun CLI (`~/.bun/bin/gbrain`).
- **Engine `postgres`** on **Supabase + pgvector** (project `zgmlfkdjjgahfnvyugct`).
- Models via **9Router**: embeddings `9router:mxbai-embed-large` (1024d), chat `9router:Free`.
- **HTTP MCP server** on port `3131` — every agent connects to the same brain.
- **GitHub offsite backups**: `gbrain-brain` + `gbrain-workspace` mirror the live Supabase brain.
- Config in `~/.gbrain/config.json`; startup via `start-gbrain-mcp.sh`.

GBrain is the connective tissue behind [Hermes](/blog/hermes-setup/), [OpenClaw](/blog/openclaw-setup/), [Pi](/blog/pi-coding-agent-setup/), [OpenCode](/blog/opencode-agent-setup/), [Codex](/blog/codex-agent-setup/), and [Claude Code](/blog/claude-code-9router-setup/) — and it rides [9Router](/blog/9router-setup/) for inference. 🚀

---

*No API keys, tokens, or secrets are included in this guide — every value is a `` you supply locally. Built with Astro, GitHub, and Cloudflare Pages.*