Gbrain Obsidian Integration

GBrain + Obsidian Integration

DEPRECATED — GBrain was removed from this stack on 2026-05-10. The MCP server config was deleted from root config.yaml and the plugin directory at ~/.hermes/plugins/gbrain/ is orphaned (not referenced by any config). This skill is preserved for reference only — it documents the integration pattern if GBrain is reinstated.

Purpose: Connect GBrain (knowledge graph engine) with an existing Obsidian vault that uses PARA structure, enabling the agent to maintain a separate compiled knowledge base while you write in your normal vault.

Trigger: User asks how to use GBrain with Obsidian, or wants to set up a team knowledge base with GBrain backing an Obsidian vault.

Architecture Decision

First, choose your integration pattern:

Approach A: Separate Brain + Mirror (Recommended for existing PARA vaults)

Layout:

~/Hermes Vault/Hermes/          ← your writing surface (PARA)
  1-Projects/
  2-Areas/
  3-Resources/
  4-Archive/
  Memory/
  Sessions/
  icarus/
  Team-Wiki/                    ← READ-ONLY mirror of ~/.hermes/brain/markdown/
     people/
     companies/
     concepts/
     comparisons/
     queries/
     SCHEMA.md
     index.md
     log.md

~/.hermes/brain/                ← GBrain's authoritative markdown mirror
   people/
   companies/
   ...
   brain.db                      ← PGLite database

~/.local/share/gbrain/          ← GBrain's structured database only
   gbrain.db

Flow:

1. You write markdown in your vault using PARA folders (unchanged workflow).
2. Cron job runs gbrain sync → imports vault markdown → extracts entities, links, timeline → updates brain.db and regenerates markdown into ~/.hermes/brain/.
3. One-way mirror (symlink or rsync) copies ~/.hermes/brain/markdown/* → vault/Team-Wiki/ so you can browse the compiled knowledge in Obsidian's Graph View.
4. Hermes queries GBrain via MCP tools (gbrain query, gbrain search) for intelligent answers.
5. Agent-written material goes into ~/.hermes/brain/ (not your PARA folders), keeping human and agent layers separate.

When to choose:

• You already have an established PARA vault
• You want to keep your manual notes untouched by agent automation
• You want clean separation: human writing surface vs. agent-compiled knowledge
• Team-Wiki structure is for browsing what the agent knows, not for your daily capture

Approach B: Direct Vault Usage (GBrain owns the wiki)

Layout:

~/Hermes Vault/Hermes/
  people/
  companies/
  concepts/
  raw/
  SCHEMA.md
  index.md
  log.md

Flow:

• GBrain's WIKI_PATH points directly at your vault
• Agent reads/writes wiki pages in-place
• Obsidian shows the same files the agent maintains

When to choose:

• Starting fresh with no existing vault content
• Want a single source of truth
• Comfortable with agent-written pages mixing with human notes (use clear naming conventions)

Drawbacks for PARA users:

• Requires restructuring your vault from PARA to GBrain's schema
• Migration step needed (gbrain migrate from Obsidian → GBrain format)
• Your existing PARA folders would need to be moved or archived

Platform Compatibility & Path Selection

macOS 15.6 (Darwin 26.3) has a known WASM regression that breaks PGLite. If you're on this or a later macOS version, skip to Path B (Postgres fallback). On earlier macOS versions, PGLite should work fine.

Quick check:

sw_vers | grep ProductVersion
# 15.6+ → use Postgres; <15.6 → PGLite safe

Or attempt a dry-run: gbrain init — if you see "PGLite failed to initialize its WASM runtime. This is most commonly the macOS 26.3 WASM bug", switch to Postgres.

Path A: Standard PGLite Setup (macOS < 15.6)

[Existing PGLite steps go here — unchanged]

Path B: Postgres Fallback (macOS 15.6+ or PGLite failure)

Uses a real PostgreSQL server instead of PGLite. More setup steps but fully reliable on affected macOS versions. Production-grade anyway (faster, multi-device ready, concurrent-safe).

B1. Install PostgreSQL 17

brew install postgresql@17

B2. Initialise a dedicated data directory

Avoid clobbering any existing Postgres cluster:

mkdir -p ~/.hermes/shared-brain/pgdata
initdb -D ~/.hermes/shared-brain/pgdata -U $(whoami) -E UTF8
chmod 0700 ~/.hermes/shared-brain/pgdata

B3. Start the PostgreSQL server

Choose one launch method:

Option A — via brew services (auto-starts on login):

brew services start postgresql@17

Option B — manual background (easier to port-pin for this setup):

# Start on port 5433 and bind to /tmp socket
postgres -D ~/.hermes/shared-brain/pgdata -p 5433 -k /tmp &

Verify it's running:

ps aux | grep postgres | grep 5433
pg_isready -p 5433 -h /tmp

B4. Create the GBrain database

# Using createdb (respects the data directory config)
createdb -D ~/.hermes/shared-brain/pgdata brain_hermes

# Or via SQL:
psql -d postgres -p 5433 -h /tmp -c "CREATE DATABASE brain_hermes OWNER $(whoami);"

B5. Install required PostgreSQL extensions

# Vector for embeddings
brew install pgvector

# Load extensions into the brain_hermes database
psql -d brain_hermes -p 5433 -h /tmp -c "CREATE EXTENSION IF NOT EXISTS vector;"
psql -d brain_hermes -p 5433 -h /tmp -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"

B6. Configure GBrain to use Postgres

Create or edit ~/.gbrain/config.json:

{
  "engine": "postgres",
  "database_url": "postgres://$(whoami)@localhost:5433/brain_hermes?host=/tmp"
}

Key details:

• engine must be "postgres" (PGLite uses different connection semantics)
• ?host=/tmp tells libpq to use the Unix socket at /tmp/.s.PGSQL.5433
• Alternatively omit ?host=/tmp and use -h /tmp on psql; the URL alone often suffices

Alternatively set via environment (Hermes prefers this):

export GBRAIN_DATABASE_URL="postgres://$(whoami)@localhost:5433/brain_hermes"

Hermes MCP server will pick this up if defined in ~/.hermes/config.yaml under env.

B7. Initialise GBrain's schema

cd ~/.hermes/plugins/gbrain
./bin/gbrain init

Expected output:

✓ Database connected
✓ Schema version latest
✓ GBrain ready at postgres://… brain_hermes

If you see "PGLite failed to initialize its WASM runtime. This is most commonly the macOS 26.3 WASM bug", your config is still pointing to PGLite. Double‑check ~/.gbrain/config.json and any GBRAIN_DATABASE_URL env var overriding it.

B8. Keep PostgreSQL running across reboots

# brew services (you already started it above)
brew services enable postgresql@17

# or: create a launchd plist similar to the Windows version, targeting:
#   /usr/local/bin/postgres -D ~/.hermes/shared-brain/pgdata -p 5433 -k /tmp

B9. Resume Path A

Rejoin the shared workflow at Step 4 (Import vault) and continue through 5–10. Differences:

• DB engine: postgres
• Connection via URL (no local file path)
• PostgreSQL process must stay alive (brew services handles this)
• Performance is faster and concurrent-safe

Migration note: If you already tried PGLite and have a brain.pglite directory, keep it as a backup or delete it. To migrate existing data you'd need both engines available: gbrain migrate --to postgres. In our case we started fresh.

Platform diagnostic

When the user reports "PGLite failed to initialize its WASM runtime", confirm:

1. sw_vers | grep ProductVersion → 15.6+ (Darwin 26.3) is the trigger
2. No workaround exists for WASM; the only fix is switching to Postgres engine
3. Path B above is the recommended permanent solution (not a temporary workaround)

Recommended Setup (Approach A)

Prerequisites

• Bun runtime: curl -fsSL https://bun.sh/install | bash
• GBrain plugin already cloned: ~/.hermes/plugins/gbrain/ (if not, git clone https://github.com/garrytan/gbrain.git ~/.hermes/plugins/gbrain)
• OpenAI-compatible API key for embeddings (your existing OPENAI_API_KEY in ~/.config/nim/env.sh works)
• Obsidian vault path confirmed: ~/Hermes Vault/Hermes

Step-by-Step

1. Install Bun & GBrain dependencies

# Install Bun (if not already)
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"

# Install GBrain
cd ~/.hermes/plugins/gbrain
bun install
bun link  # makes `gbrain` CLI available in ~/.bun/bin

Verify: gbrain --version should print a version.

2. Create brain repository

mkdir -p ~/.hermes/brain
cd ~/.hermes/brain
git init

This repo will contain GBrain's markdown mirror (not your vault). Keep it separate.

3. Initialize GBrain database

gbrain init  # creates PGLite DB at ~/.local/share/gbrain/gbrain.db

PGLite is zero-config (no Postgres server needed). For large vaults (1000+ files), consider Supabase + pgvector instead — see gbrain docs/ENGINES.md.

4. Import your Obsidian vault

gbrain import ~/Hermes\ Vault/Hermes --no-embed

This scans your vault's markdown, extracts frontmatter and wikilinks, and writes pages into ~/.hermes/brain/markdown/ following GBrain's schema (people, companies, concepts, etc.). The --no-embed flag skips vector embedding for now (fast import).

Expected: New markdown files appear under ~/.hermes/brain/ in category directories, plus timeline.md and link index.

5. Generate embeddings

gbrain embed --stale

This processes all pages missing embeddings, calls your OpenAI-compatible endpoint (text-embedding-3-large by default), and stores vectors in the DB. Time depends on vault size (~1 sec per 100 pages on average).

6. Backfill knowledge graph

gbrain extract links --source db
gbrain extract timeline --source db

Populates the typed relationship graph (attended, works_at, founded, etc.) and structured timeline from existing content. These tables auto-update on future writes; this is a one-time backfill.

7. Set up live sync (cron)

Configure a recurring job to keep brain current:

# Add to crontab (edit with `crontab -e`)
*/15 * * * * cd ~/.hermes/brain && gbrain sync --follow >> ~/.hermes/logs/gbrain-sync.log 2>&1
# Daily embed refresh (catches new pages)
0 3 * * * cd ~/.hermes/brain && gbrain embed --stale >> ~/.hermes/logs/gbrain-embed.log 2>&1
# Weekly health check
0 6 * * 1 cd ~/.hermes/brain && gbrain doctor --json >> ~/.hermes/logs/gbrain-doctor.log 2>&1

Important: Use --follow mode for the sync job — it runs continuously, watches for filesystem changes via fswatch, and updates immediately. The cron entry above starts it every 15 min; if it's already running, the new instance exits immediately (idempotent).

Alternatively, use GBrain's built-in cron-scheduler skill if you prefer agent-managed scheduling.

8. Mirror brain to Team-Wiki (one-way)

The agent writes to ~/.hermes/brain/markdown/. To browse these pages in Obsidian, mirror them into your vault:

Option A: Symbolic link (simple, live)

mkdir -p ~/Hermes\ Vault/Hermes/Team-Wiki
ln -s ~/.hermes/brain/markdown/* ~/Hermes\ Vault/Hermes/Team-Wiki/
# Note: ln -s doesn't merge directories; better to symlink the parent:
rmdir ~/Hermes\ Vault/Hermes/Team-Wiki  # if empty
ln -s ~/.hermes/brain/markdown ~/Hermes\ Vault/Hermes/Team-Wiki

Option B: Rsync (copy, safe)

mkdir -p ~/Hermes\ Vault/Hermes/Team-Wiki
rsync -av --delete ~/.hermes/brain/markdown/ ~/Hermes\ Vault/Hermes/Team-Wiki/

Automate with a cron (runs after sync):

*/16 * * * * rsync -av --delete ~/.hermes/brain/markdown/ ~/Hermes\ Vault/Hermes/Team-Wiki/ >> ~/.hermes/logs/gbrain-mirror.log 2>&1

Recommendation: Use symlink if you're the only user and want live updates. Use rsync if multiple people write to the vault or you want to avoid symlink clutter in Obsidian.

9. Configure Hermes MCP access

Edit ~/.hermes/config.yaml (create if missing):

mcp_servers:
  gbrain:
    command: ~/.hermes/plugins/gbrain/bin/gbrain
    args: ["serve"]
    enabled: true
    # Optional: filter tools if you want subset
    # tools:
    #   allow: ["query", "search", "put_page", "sync"]

Restart Hermes. Verify with /plugins — should list gbrain MCP server.

Now Hermes can call GBrain tools directly:

• /gbrain query "who works at Acme?"
• /gbrain search "quantum crypto" (hybrid)
• /gbrain graph-query "marcus-reid" --depth 2

10. Populate vault with GBrain skill reference

Copy the 26 GBrain skill docs into your vault for manual reading:

mkdir -p ~/Hermes\ Vault/Hermes/3-Resources/Skills/Agents/GBrain/
cp -r ~/.hermes/plugins/gbrain/skills/* ~/Hermes\ Vault/Hermes/3-Resources/Skills/Agents/GBrain/

Update your 3-Resources/Skills/Agents/gbrain.md index note to point to these local copies.

Optional: Auto-enrichment

If you want GBrain to pull external data (web search, social profiles) when entities are mentioned:

gbrain integrations install web-search  # or: twitter, email, etc.

Each integration has its own credential requirements. Run gbrain integrations list to browse.

Key Conventions

GBrain's schema (what gets created under ~/.hermes/brain/)

markdown/
├── people/                # Person pages (slugified name)
│   └── marcus-reid.md
├── companies/             # Company pages
│   └── acme-ai.md
├── concepts/              # Topics, techniques, frameworks
├── comparisons/           # Side-by-side analyses
├── queries/               # Past query results worth saving
├── timeline.md            # All dated events across entities
├── SCHEMA.md              # Conventions (read by agent before writing)
└── index.md               # Catalog of pages

Page format (each .md file):

---
title: Marcus Reid
type: person
created: 2026-04-20
updated: 2026-04-23
tags: [person, investor, ai]
sources: [raw/meetings/2026-04-20-acme-meeting.md]
---

## Summary
CTO at Acme AI, previously at Meta. Focused on quantum-resistant cryptography.

## Current
- **Role:** CTO
- **Company:** [[acme-ai]]
- **Joined:** 2024-01

## See Also
- [[priya-patel]] — co-founder
- [[threshold-ventures]] — investor

---

## Timeline
- 2026-04-20 — attended meeting with Acme AI team [source: meetings/2026-04-20]
- 2026-04-18 — mentioned in tweet about quantum crypto [source: raw/tweets/...]

Vault PARA vs Team-Wiki

• PARA folders (1-Projects/, 2-Areas/, etc.): Your manual notes. Free-form. No schema enforcement.
• Team-Wiki/: Agent-generated, GBrain-sourced. Read-only for you. Reflects what the brain knows.

Do NOT edit files under Team-Wiki/ manually — they'll be overwritten on next sync. To correct something, edit the source note in your PARA vault or use gbrain put_page to update the brain's data layer; the next sync regenerates the markdown.

Querying the Brain

Once MCP is live, ask Hermes:

/gbrain query "what have I discussed with Marcus about quantum?"
/gbrain search "Series B funding"           # hybrid: vector + keyword
/gbrain graph-query "acme-ai" --depth 2     # show connections
/gbrain get "people/marcus-reid"            # raw page
/gbrain stats                               # page count, link density

All results cite sources (links to vault files or raw sources).

Maintenance

• Weekly: gbrain doctor --json — health check (broken links, orphans, stale pages)
• Monthly: gbrain extract links --source db (redundant but safe) and gbrain lint (if available)
• Log rotation: GBrain auto-rotates its internal logs; your vault Team-Wiki/log.md rotates at 500 entries via Secretary

Troubleshooting

Related Skills

• obsidian — read/write vault files directly
• obsidian-memory-bridge — syncs Hermes memory to Memory/Hermes Memory.md
• llm-wiki — Karpathy's wiki pattern (GBrain implements this with graph + embeddings)
• team-wiki/setup (create if needed) — bootstraps Team-Wiki directory structure, SCHEMA.md, index.md
• team-wiki/sync-gbrain (create if needed) — automates the GBrain sync + mirror cron as an agent skill

Next Steps After Setup

1. Test the pipeline: Write a test note in 0-Inbox/ containing "Meeting with [[Marcus Reid]] from [[Acme AI]]". Wait 15 min (or run gbrain sync --once manually). Check ~/.hermes/brain/people/ for new pages.
2. Browse Team-Wiki: Open Obsidian, look at Team-Wiki/ graph. Verify links appear.
3. Query via Hermes: /gbrain query "who is Marcus Reid?"
4. Set up Secretary: Ensure Secretary profile runs the obsidian-memory-bridge skill to keep Memory/ current.
5. Configure cron: Double-check cron jobs are active with crontab -l.

References

• GBrain docs: ~/.hermes/plugins/gbrain/README.md, docs/GBRAIN_RECOMMENDED_SCHEMA.md
• Hermes MCP: website/docs/user-guide/features/mcp.md
• Obsidian vault: ~/Hermes Vault/Hermes/
• Icarus memory fabric: vault/icarus/