This project addresses the challenge of managing and leveraging personal knowledge bases, typically stored as markdown files, as they scale beyond simple text search. It provides a retrieval layer and agent integration framework, enabling AI agents to interact with and augment this knowledge, leading to compounding intelligence over time. GBrain is targeted at individuals managing extensive personal notes, researchers, and developers building AI agents that require persistent, evolving knowledge.

How It Works

GBrain transforms a Git repository of markdown files into a searchable knowledge base using Postgres with the pgvector extension. It implements a hybrid search strategy combining keyword, vector (HNSW), and RRF fusion, augmented by multi-query expansion. The core knowledge model features a "compiled truth" (current understanding, subject to revision) above a strict "append-only timeline" (immutable evidence trail) for each page. AI agents interact via a CLI or MCP interface, executing a read-write loop where new information enriches the brain, making the agent progressively smarter with each interaction.

Quick Start & Requirements

• Primary Install: Via bun (standalone CLI, library, or within OpenClaw/Hermes Agent). Example: bun add github:garrytan/gbrain.
• Prerequisites:
  • Bun JavaScript runtime.
  • Postgres database with pgvector extension (Supabase Pro tier, $25/mo, recommended).
  • OpenAI API key (for embeddings, e.g., text-embedding-3-large).
  • Anthropic API key (for LLM features like multi-query expansion).
  • Note: Basic functionality (keyword search, markdown interaction) is possible without Postgres or API keys, but significantly limited.
• Setup: A guided gbrain init wizard configures the database connection and schema. Importing ~7,000 files takes ~30 seconds for text indexing and ~10-15 minutes for embedding generation.
• Relevant Links: GBRAIN_SKILLPACK.md (agent reference), GBRAIN_RECOMMENDED_SCHEMA.md (schema design), ENGINES.md (pluggable backends).

Highlighted Details

• Hybrid Search: Fuses keyword (tsvector) and vector (HNSW) search with RRF scoring, enhanced by multi-query expansion and 4-layer deduplication for robust retrieval.
• Compiled Truth + Timeline: A structured knowledge model separating current understanding from immutable historical evidence, enabling both dynamic synthesis and verifiable recall.
• File Migration: Manages large binary assets (images, PDFs) by migrating them from Git to cloud storage (S3, R2, Supabase Storage) using redirection mechanisms, preserving Git repo size and file accessibility.
• Agent Skill System: Leverages "fat markdown skills" (e.g., ingest.md, query.md) to define agent behavior and interaction patterns, separating agent logic from the GBrain core.

Maintenance & Community

No specific details regarding maintainers, community channels (like Discord/Slack), or active sponsorships were found in the provided README text. Development appears focused on core functionality and architecture.

Licensing & Compatibility

• License: MIT.
• Compatibility: Permissive MIT license allows for commercial use and integration into closed-source applications. Designed to be compatible with any AI agent capable of reading and writing files.

Limitations & Caveats

• Cost: Full functionality requires a paid Supabase Pro plan ($25/mo) and incurs costs for OpenAI/Anthropic API usage for embeddings and LLM features.
• Dependencies: Requires the Bun JavaScript runtime. Integration with AI agents necessitates implementing the provided "skill" patterns.
• Setup Overhead: Requires setting up external services (Supabase) and obtaining API keys, adding to the initial setup complexity beyond just installing the tool.