# GBrain

> An open-source CLI and TypeScript library that gives AI agents a persistent, searchable knowledge base built from markdown files, with hybrid vector+keyword search powered by Postgres and pgvector.

GBrain is an open-source personal knowledge base engine designed to be installed and operated by AI agents. It indexes markdown files into a local or cloud Postgres database with pgvector, enabling hybrid search (vector + keyword + RRF fusion) so agents can read context before every response and write new knowledge after every conversation. The system supports a "compiled truth + timeline" knowledge model, 30+ MCP tools, and integration recipes for Gmail, Google Calendar, Twitter, Twilio voice calls, and meeting transcripts. Setup takes approximately 30 minutes with a frontier model like Claude or GPT handling the installation automatically.

- **PGLite local brain** — *Run `gbrain init` for an embedded Postgres 17.5 brain via WASM with no server, no accounts, and no connection strings required.*
- **Hybrid search with RRF fusion** — *Combines vector (HNSW cosine) and keyword (tsvector) search with Reciprocal Rank Fusion and multi-query expansion via Claude Haiku for best-in-class recall.*
- **30 MCP tools** — *Expose `get_page`, `put_page`, `search`, `query`, `traverse_graph`, `sync_brain`, and more to any MCP client including Claude Code, Cursor, Windsurf, and Claude Desktop.*
- **Integration recipes** — *Agent-readable markdown recipes for Gmail, Google Calendar, Twitter/X, Twilio voice-to-brain, and Circleback meeting transcripts; the agent reads the recipe, asks for API keys, and wires everything up.*
- **Compiled truth + timeline model** — *Every brain page stores a rewritable "compiled truth" section above a separator and an append-only evidence timeline below, keeping facts current while preserving provenance.*
- **Pluggable engine architecture** — *Swap between PGLiteEngine (local, zero-config) and PostgresEngine (Supabase Pro) with a single `gbrain migrate --to supabase` command.*
- **File storage migration** — *Three-stage lifecycle (mirror → redirect → clean) moves binary attachments to S3-compatible or Supabase Storage while preserving all markdown references.*
- **TypeScript library** — *Import `createEngine` from `gbrain` to embed the brain directly in any TypeScript/Bun project with the same operations as the CLI and MCP server.*
- **GBRAIN_SKILLPACK** — *A reference playbook telling agents when to read, when to write, how to detect entities, run enrichment pipelines, and maintain the brain autonomously via cron jobs.*

## Features
- Local PGLite embedded Postgres brain (no server required)
- Hybrid vector + keyword search with RRF fusion
- Multi-query expansion via Claude Haiku
- 30 MCP tools via stdio
- Remote MCP server via Supabase Edge Functions
- Integration recipes for Gmail, Google Calendar, Twitter/X, Twilio, Circleback
- Compiled truth + append-only timeline knowledge model
- Pluggable engine: PGLite (local) or Postgres (Supabase)
- Bidirectional migration between PGLite and Supabase
- Three-stage binary file migration to cloud storage
- TypeScript library with createEngine API
- GBRAIN_SKILLPACK agent playbook
- 37 CLI operations
- Idempotent markdown import with SHA-256 content hashing
- Three chunking strategies: recursive, semantic, LLM-guided
- Page versioning and revert
- Typed link graph with recursive CTE traversal
- Daily briefing and meeting prep skills
- Migration from Obsidian, Notion, Logseq, Roam
- Health dashboard with stale/orphan detection

## Integrations
OpenAI (text-embedding-3-large), Anthropic Claude (Haiku, Opus), Supabase (Postgres + pgvector), Gmail, Google Calendar, Twitter/X, Twilio, Circleback, ngrok, Claude Code, Claude Desktop, Cursor, Windsurf, Perplexity, OpenClaw, Hermes Agent, AWS S3, Cloudflare R2, MinIO, Supabase Storage

## Platforms
WINDOWS, MACOS, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/garrytan/gbrain
- Documentation: https://github.com/garrytan/gbrain/blob/master/docs/GBRAIN_SKILLPACK.md
- Repository: https://github.com/garrytan/gbrain
- EveryDev.ai: https://www.everydev.ai/tools/gbrain