garrytan/gbrain

⭐ 14,336  ·  TypeScript  ·  GitHub Repo

Garry's Opinionated OpenClaw/Hermes Agent Brain

1-Sentence Summary

Self-wiring knowledge graph giving AI agents persistent, structured memory with production-proven retrieval accuracy.

🔥 Key Capabilities & USP

• Self-Wiring Knowledge Graph – Automatically extracts entities (people, companies) and creates typed relationships (works_at, invested_in, founded) with zero LLM calls. Solves the pain point of agents treating every interaction as a fresh context window, enabling structured queries like "who works at Acme AI?" without manual schema design.
• Hybrid Search with Backlink-Boosted Ranking – Combines vector embeddings, graph traversal, and backlink signals to achieve P@5 49.1% and R@5 97.9% on benchmarks. This beats pure vector-only and BM25 approaches by over 31 points, directly addressing the "smart but forgetful" problem where agents lose context across sessions.
• 34 Pre-Built Agent Skills – Ships organized skill files (RESOLVER.md, AGENTS.md) that instruct AI agents on research, synthesis, and code analysis tasks. Eliminates the need to manually craft agent instructions for common operations.
• MCP Server with OAuth 2.1 – Exposes 30+ MCP tools via stdio or HTTP with production-grade OAuth 2.1, scoped operations, and an embedded React admin dashboard. Enables remote agent integration with ChatGPT, Claude Desktop, and Perplexity without compromising security.
• Built-in Benchmarking & Evaluation – Supports LongMemEval, BrainBench-Real session capture, and gbrain eval commands for reproducible retrieval quality measurement. Lets teams prove their memory system works rather than relying on anecdotal evidence.

USP: A production-proven brain (17,888 pages, 4,383 people, 723 companies) that combines graph-based entity linking with vector search, all running in-browser with no external infrastructure and 2-second database initialization.

Technical Architecture

Component	Technology	Details
Database	PGLite (in-browser PostgreSQL)	Ready in 2 seconds, no server required, runs entirely locally
Runtime	Bun (JavaScript/TypeScript)	CLI and server runtime with fast startup
Search	Hybrid (Vector + Graph + Backlink)	Combines embeddings with entity linking and backlink-boosted ranking
Agent Protocol	MCP (Model Context Protocol)	Supports stdio and HTTP transport
Auth	OAuth 2.1	Production-grade for remote clients (ChatGPT, Claude Desktop, Perplexity)
Code Analysis	Cathedral II engine	Call-graph edges with two-pass retrieval (code-callers, code-callees, code-def, code-refs)
Admin UI	Embedded React dashboard	Accessible via http://localhost:3131/admin

Quick Start Guide

# Install (standalone CLI)
git clone https://github.com/garrytan/gbrain.git && cd gbrain && bun install && bun link

# Initialize your local brain (ready in 2 seconds)
gbrain init

# Import your notes
gbrain import ~/notes/

# Query your brain
gbrain query "what themes show up across my notes?"

# Start MCP server for agent integration (Claude Code, Cursor, Windsurf)
# Add to MCP config:
{
  "mcpServers": {
    "gbrain": { "command": "gbrain", "args": ["serve"] }
  }
}

# Remote MCP with OAuth 2.1
gbrain serve --http --port 3131
open http://localhost:3131/admin

# Code analysis commands
gbrain code-callers searchKeyword
gbrain code-callees searchKeyword
gbrain code-def BrainEngine
gbrain code-refs BrainEngine
gbrain query "how does N+1 handling work" --near-symbol BrainEngine.searchKeyword --walk-depth 2

# Agent install (paste into agent)
Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md

Pros, Cons & Use Cases

Pros

• Production-proven at scale – 17,888 pages, 4,383 people, 723 companies indexed with strong retrieval metrics
• Extremely fast setup – ~30 minutes to a fully working brain; database ready in 2 seconds
• Zero external infrastructure – PGLite runs in-browser, no server, no cloud dependencies
• Strong benchmark performance – P@5 49.1%, R@5 97.9% beats vector-only and BM25 by 31+ points
• Rich code analysis – Cathedral II engine provides call-graph-aware retrieval for engineering teams

Cons

• No simple npm/bun install – Cannot use bun install -g or npm due to postinstall hook issues and package name squatting
• Manual clone workflow required – Requires git clone + bun install + bun link sequence
• npm registry squatting – The gbrain package name is occupied by an unrelated project
• Local-only operations – sync_brain and file_upload are rejected over HTTP, limiting some remote workflows

Who should NOT use this?

• Teams requiring a managed cloud service – This is a self-hosted, local-first tool; no SaaS offering exists
• Non-TypeScript/Bun environments – Tightly coupled to Bun runtime; no Python, Go, or Rust bindings
• Users wanting a GUI-first experience – Primary interface is CLI and MCP; the admin dashboard is supplementary
• Teams without MCP-compatible agents – Value diminishes if you're not using OpenClaw, Hermes Agent, Claude Code, Cursor, or Windsurf

Ideal Use Cases

• AI agent developers building autonomous agents that need persistent, structured memory across meetings, emails, calls, and notes
• Engineering teams using GStack who need code-aware retrieval with call-graph traversal
• Knowledge workers running OpenClaw or Hermes Agent deployments who want a "second brain" that actually remembers
• Teams evaluating retrieval quality – Built-in benchmarking lets you measure and compare against baselines

Community & Activity

With 14,336 stars and a last update on May 10, 2026, GBrain shows strong community interest and active maintenance. The project has clearly resonated with the AI agent development community, evidenced by its rapid star growth and production-scale deployment (17,888 pages indexed). The combination of a novel self-wiring knowledge graph approach with concrete benchmark results suggests this isn't just hype—it's a tool that teams are actively using and contributing to.