GBrain: Postgres-native Personal Knowledge Brain

The following tutorials are currently in development:

• VC Dealflow: Using gbrain whoknows, gbrain find-trajectory, and gbrain founder scorecard for managing founder and company data.
• Vault Migration: Migrating Notion, Obsidian, or Roam vaults using gbrain schema detect → suggest → review-candidates.
• Codebase Indexing: Initializing a brain in a code repo using voyage-code-3 embeddings and navigating via gbrain code-def, gbrain code-refs, and gbrain code-callers.
• Fully Local GBrain: Running with Ollama or llama.cpp for privacy-first, air-gapped, or regulated environments.
• The Dream Cycle: Setting up an overnight enrichment daemon for citations, deduplication, and automated scorecard generation.

The schema-author skill is used to evolve your brain's schema pack by adding page types, link verbs, prefixes, and flags. This is an authoring-time task used to change the rules of your brain (e.g., "what types exist?"), rather than a write-time task (e.g., "where does this specific note go?").

**Use this skill when you want to:

• Add a new page type (e.g., researcher).
• Propose new types based on corpus scans.
• Backfill page.type on existing untyped pages.
• Audit the health of your current schema pack.
• Make a type 'expert-routable' or 'extractable'.

**Do NOT use this skill for:

• Filing a single specific page (use brain-taxonomist instead).
• Checking schema as part of an EIIRP iteration (use eiirp instead).
• Looking up a type's settings (use gbrain schema explain <type> instead).
• Querying who knows about a topic (use gbrain whoknows <topic> instead).

The GBrain Admin Dashboard is a dense, utilitarian developer infrastructure tool designed for managing OAuth agents, API keys, and monitoring requests. It follows an 'Industrial/Utilitarian' aesthetic, prioritizing function and data density over decoration.

Core Principles:

• Function-first: Every pixel must serve an informational purpose.
• Zero Decoration: No gradients, shadows, or accent colors for decoration. The data is the interface.
• Cockpit Mood: Designed for operators, not consumers. It is a high-density ops dashboard.
• Dark Theme Only: No light mode is supported.

GBrain provides an evaluation framework for maintainers and contributors to ensure changes to retrieval logic (search, ranking, embeddings, intent classification, query expansion, source boost, hybrid fusion) do not cause regressions.

There are two primary evaluation paths:

1. Retrieval Ranking (The Replay Loop): Uses captured real-world queries to compare current results against a baseline. This is used to detect if code changes shifted search results or increased latency.
2. Memory Behavior (BrainBench): Uses gbrain eval brainbench to gate memory-related behaviors like Retrieval Reflex, conversation-to-facts write-back, and source isolation.

For the NDJSON wire format used by these evaluations, refer to eval-capture.md.

Minions is a Postgres-native job queue designed for durable, observable background work that must survive restarts, persist across sessions, or scale via parallel fan-out. It provides a single, steerable queue interface for two distinct types of work:

1. Deterministic Shell Jobs: For reproducible command execution, ETL, or cron tasks where no LLM reasoning is required.
2. LLM Subagent Jobs: For open-ended reasoning, research, or iterative agentic workflows.

Routing Decision Guide:

• Shell Job: Use when the user asks for a deterministic command/script or provides explicit cmd/argv parameters.
• Subagent Job: Use when the user asks for research, reasoning, or an iterative agent.
• Inline Execution: Consider for single, simple operations lasting <30s.
• Minion Job: Use when the work requires restart durability or observability.

GBrain is a compiled intelligence system designed for personal knowledge management at scale. Unlike a traditional note-taking app, it treats every page as an intelligence assessment consisting of two parts:

1. Compiled Truth: A section representing the current best understanding of a topic, which is rewritten as new evidence emerges.
2. Timeline: An append-only, immutable evidence trail of facts, references, or events.

GBrain uses a Postgres-native backend (with pgvector) to provide high-performance hybrid search (combining vector semantic search and keyword search) and manages the intelligence lifecycle via AI agents.

There are four primary schema packs available, each serving a different functional purpose:

• gbrain-base: The foundation upon which other packs extend.
• gbrain-creator: Focuses on the atom and concept lifecycle (content creation).
• gbrain-investor: Adds an investment lens (deals, theses, and bet resolutions).
• gbrain-engineer: Acts as a bridge for technical learning, specifically for gstack integrations.
• gbrain-everything: A meta-pack that combines the Creator, Investor, and Engineer lenses into a single active brain.

A Schema Pack is the single source of truth for the structure of your brain. It defines which directories exist, what types live in them, how the agent should infer types from file paths, and how different types are connected via link verbs.

Every core operation—including filing, querying, routing experts, and fact extraction—consults the active schema pack at runtime. It is a dynamic artifact that allows the agent to understand the 'shape' of your data.

GBrain operates on two primary engines via a unified BrainEngine interface:

• PGLite: A zero-config Postgres 17 via WASM engine, ideal for personal brains up to ~50K pages.
• Postgres + pgvector: Used for shared, large, or multi-machine deployments (e.g., Supabase).

Key Concepts:

• Brain vs. Source: A brain is the database instance. A source is a specific repository (wiki, knowledge base, etc.) within that brain. Routing is determined by .gbrain-source dotfiles.
• System of Record: Your knowledge is stored in a standard Git repository as markdown files. GBrain syncs these into Postgres. Deletions in Git result in soft-deletes in the database.