gbrain-agent-knowledge

What this skill does

```markdown
---
name: gbrain-agent-knowledge
description: Skill for using GBrain — a Postgres-backed markdown knowledge brain with hybrid search for AI agents
triggers:
  - set up gbrain for my agent
  - help me build a knowledge brain
  - index my markdown files with gbrain
  - search my notes with an AI agent
  - gbrain import and query
  - set up agent memory with markdown and postgres
  - configure gbrain skillpack
  - connect gbrain to my AI agent
---

# GBrain Agent Knowledge Skill

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

GBrain is a markdown-first, Postgres-backed knowledge brain for AI agents. It turns a git repo of markdown files into a hybrid-searchable (vector + keyword + RRF) knowledge base. The agent reads from and writes to the brain, compounding knowledge over time. Built to work with OpenClaw and Hermes Agent, but usable with any agent that can run CLI commands or call MCP tools.

---

## What GBrain Does

- **Indexes markdown files** into Postgres + pgvector via chunking and OpenAI embeddings
- **Hybrid search** — keyword (tsvector), vector (pgvector), and RRF fusion in one query
- **Knowledge model** — compiled truth header + append-only timeline per page
- **MCP layer** — exposes `gbrain search`, `gbrain get`, `gbrain query` as agent tools
- **Dream cycle** — nightly cron that enriches entities, fixes links, and consolidates memory
- **Works without Postgres** — the schema and skillpack work with plain markdown + grep until scale demands more

---

## Installation

### Prerequisites

| Dependency | Purpose | Source |
|---|---|---|
| Bun | Runtime | `curl -fsSL https://bun.sh/install \| bash` |
| Supabase (Pro) | Postgres + pgvector | [supabase.com](https://supabase.com) |
| OpenAI API key | Embeddings (`text-embedding-3-large`) | `OPENAI_API_KEY` env var |
| Anthropic API key | Multi-query expansion, LLM chunking | `ANTHROPIC_API_KEY` env var |

### Install GBrain

```bash
# Install via bun
bun add github:garrytan/gbrain

# Or globally
bun add -g github:garrytan/gbrain
```

### Environment Variables

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
# Supabase URL is configured interactively via: gbrain init --supabase
```

### Initialize

```bash
gbrain init --supabase
# Follow the wizard to connect your Supabase database
# This runs the SQL migrations (pgvector, tsvector, RRF functions)
```

---

## Key CLI Commands

### Import

```bash
# Import a markdown repo (skip embedding for speed, embed in background)
gbrain import ~/git/brain/ --no-embed

# Import and embed immediately
gbrain import ~/Documents/obsidian-vault/

# Import with Obsidian wikilink conversion
gbrain import ~/Documents/obsidian-vault/ --convert-wikilinks
```

### Stats

```bash
gbrain stats
# Pages: 342, Chunks: 1,847, Embedded: 1,847, Links: 0
```

### Search and Query

```bash
# Hybrid search (keyword + vector + RRF)
gbrain query "competitive dynamics in fintech"

# Get a specific page by slug or path
gbrain get people/pedro-franceschi

# Keyword-only search (no embeddings required)
gbrain search "board meeting March"

# Semantic search (requires embeddings)
gbrain query "what have I said about founder resilience?"
```

### Sync

```bash
# Pick up changes from the markdown repo after manual edits
gbrain sync

# Sync a specific directory
gbrain sync ~/git/brain/people/
```

### Discover

```bash
# Scan machine for markdown repos
gbrain discover
# Reports paths, file counts, type (plain markdown vs Obsidian vault)
```

---

## Knowledge Model (Markdown Schema)

Every page follows the **compiled truth + append-only timeline** pattern. Never edit the timeline — always append. Rewrite the compiled truth section when evidence changes.

### Person Page (`people/jordan-smith.md`)

```markdown
# Jordan Smith

**Role:** Partner, Accel
**Company:** [[companies/accel]]
**First met:** 2021-03-15 (YC Demo Day)
**Contact:** [email protected]

## Compiled Truth

Jordan leads Series A in developer tools. Focused on infra and AI-native companies.
Strong network in NYC. Warm intro from Pedro (2022). Key relationship for fundraising.
Prefers Slack over email. Responds fast to concrete asks.

## Open Threads

- [ ] Follow up on the infra fund thesis deck (due 2026-04-15)
- [ ] Intro to their new operating partner

## Timeline

- 2021-03-15 — Met at YC Demo Day. Brief intro. Source: calendar/yc-demo-day-2021
- 2022-06-01 — Pedro intro'd over email. Discussed Series A landscape. Source: email
- 2024-11-20 — Coffee in NYC. Talked about AI-native infra thesis. Source: meeting-transcripts/2024-11-20-jordan
- 2026-04-08 — Zoom: shared deck draft. Positive signal on market size. Source: calendar/zoom-jordan-2026-04-08
```

### Company Page (`companies/accel.md`)

```markdown
# Accel

**Type:** Venture Capital
**Stage:** Series A–C
**HQ:** Palo Alto / London / NYC
**Key contacts:** [[people/jordan-smith]], [[people/rich-wong]]

## Compiled Truth

Top-tier global VC. Strong in developer tools, infra, and fintech.
Accel's NYC presence has grown since 2022. Jordan is the primary contact.
Portfolio includes Brex, Atlassian, Slack.

## Timeline

- 2022-06-01 — First contact via Jordan intro. Source: email
- 2024-11-20 — Jordan meeting. Discussed fund cycle and portfolio fit. Source: meeting-transcripts/2024-11-20-jordan
```

### Original Idea Page (`originals/shame-founder-performance.md`)

```markdown
# Shame and Founder Performance

**Thesis category:** Psychology / Leadership
**Created:** 2025-08-12
**Status:** Developing

## Compiled Truth

Founders who operate from shame (fear of judgment, proving worth) hit a ceiling earlier
than founders who operate from curiosity. Shame optimizes for external validation;
curiosity optimizes for truth. The transition from shame-driven to curiosity-driven is
often the unlock at the Series B inflection point.

## Evidence

- 2025-08-12 — Observed in 3 portfolio companies simultaneously. Source: notes/coaching-session-aug-2025
- 2025-09-04 — Brené Brown's research on shame vs guilt maps onto this. Source: media/brene-brown-daring-greatly
- 2026-01-17 — Jordan independently raised something similar in our meeting. Source: meeting-transcripts/2026-01-17-jordan
```

---

## Agent Integration Patterns

### The Brain-Agent Loop

```
Signal arrives (meeting, email, tweet, note)
  → Agent detects entities (people, companies, ideas)
  → READ: gbrain search / gbrain get (check brain first)
  → Respond with full context
  → WRITE: update markdown pages with new information
  → gbrain sync (index changes)
```

### Entity Detection (spawn on every message)

When a message mentions a person, company, or original idea:

1. `gbrain get people/<slug>` — check if page exists
2. If exists: read compiled truth, check open threads
3. If not exists: create new page from schema template
4. After conversation: append new facts to timeline, rewrite compiled truth if needed
5. `gbrain sync` to re-index

### Meeting Ingestion (7-step enrichment)

```
1. gbrain search <person> — pull dossier before meeting
2. During/after: capture transcript → meeting-transcripts/<date>-<person>.md
3. Extract entities mentioned: people, companies, ideas
4. For each entity: gbrain get <entity> → append timeline entry
5. Update compiled truth for each entity page
6. Create new pages for unknown entities
7. gbrain sync
```

### MCP Tool Usage (OpenClaw / Hermes)

When installed as an MCP skill, these tools are available to the agent:

```
gbrain_search(query: string) → ranked list of pages
gbrain_get(slug: string) → full page content
gbrain_query(query: string) → hybrid search with scores
gbrain_sync() → re-index changed files
```

---

## Programmatic Usage (TypeScript)

```typescript
import { GBrain } from 'gbrain'

const brain = new GBrain({
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseKey: process.env.SUPABASE_SERVICE_KEY!,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
})

// Hybrid search
c