Gbrain

Compiled personal knowledge graph for AI agents.

GBrain is a local-first knowledge brain built on a single SQLite file. It combines full-text search, vector embeddings, structured queries, a CLI, and an MCP server in one place.

It is not a note app, and it is not a generic RAG pipeline. The core model is:

• compiled truth: the current understanding, rewritten as new information arrives
• timeline: append-only evidence, never rewritten

That makes GBrain useful anywhere knowledge compounds around entities and relationships across time.

Based on the original GBrain spec: compiled truth + timeline, thin CLI + fat skills, MCP-native from day one.

What it is

Most knowledge tools fall into one of two buckets.

The first bucket is note apps. You write things down, link pages, and organize folders.

The second bucket is RAG infrastructure. You throw documents into a vector store and retrieve chunks later.

GBrain sits in a different spot. It is a compiled knowledge graph for people, companies, deals, concepts, projects, and sources. It keeps:

brain.db
  pages               compiled truth + timeline per entity
  page_fts            FTS5 full-text index
  page_embeddings     vector embeddings per chunk
  links               cross-references
  tags                tag index
  timeline_entries    structured timeline rows
  raw_data            raw enrichment payloads
  ingest_log          ingest audit trail
  config              runtime settings

One file. No server. No Docker. No separate vector database.

Who it's for

GBrain works best when your core asset is not documents, but entities plus context that accumulates over time.

Natural fits:

• investors tracking founders, companies, deals, and relationship context
• founders tracking investors, partners, customers, and competitive context
• sales or BD teams tracking stakeholders, follow-ups, and account history
• researchers maintaining evolving understanding of papers, concepts, and experiments
• operators running AI workflows that need memory beyond a single session

What all of these share: the information gets more useful when it compounds, and you need it back later in a structured form.

What it's not

GBrain is not:

• a hosted SaaS product
• a team wiki with multi-user collaboration
• a code index for source repositories
• a drafting or writing editor

It is a local knowledge layer that AI agents and MCP clients can query and update.

Why MCP-native

The point of GBrain is not just storing data. The point is making that memory available to agents.

Any MCP-capable client can talk to the same brain:

• Claude Code
• Codex
• OpenClaw
• other MCP clients that speak stdio transport

The storage is local. The access is standardized. The memory persists across sessions.

OpenClaw-specific setup now has its own guide:

• docs/openclaw.md
• hooks/gbrain-ingest-session/HOOK.md

Install

Prerequisites:

• Bun 1.3.11
• macOS or Linux
• optional: OPENAI_API_KEY or OPENROUTER_API_KEY for embeddings and hybrid query

One-command install for the latest release binary:

curl -fsSL https://raw.githubusercontent.com/laozhong86/gbrain/main/install.sh | sh

The installer verifies the downloaded binary against the published SHA256SUMS file before replacing the target executable.

If you also want the OpenClaw plugin checkout installed and wired up:

curl -fsSL https://raw.githubusercontent.com/laozhong86/gbrain/main/install.sh | sh -s -- --with-openclaw

From source:

git clone https://github.com/laozhong86/gbrain.git
cd gbrain

bun install
bun run check
bun test
bun run build

Install the binary:

mkdir -p ~/.local/bin
cp bin/gbrain ~/.local/bin/gbrain
chmod +x ~/.local/bin/gbrain

Initialize a local brain:

mkdir -p ~/.gbrain
gbrain init ~/.gbrain/main.db
gbrain stats --db ~/.gbrain/main.db

Quick verification:

gbrain version
gbrain --tools-json
gbrain stats --db ~/.gbrain/main.db

If you are wiring GBrain into OpenClaw, you can opt into the OpenClaw preset:

export GBRAIN_PROFILE=openclaw
gbrain init
gbrain stats

That makes the default database path ~/.openclaw/brain.db unless --db or GBRAIN_DB overrides it.

Embeddings

Lexical search works without model credentials:

gbrain search "Jensen Huang" --db ~/.gbrain/main.db

Embeddings and hybrid semantic query require a provider key.

OpenAI:

export OPENAI_API_KEY=your_key

OpenRouter:

export OPENROUTER_API_KEY=your_key
export OPENROUTER_HTTP_REFERER=https://your-site.example
export OPENROUTER_X_TITLE=GBrain

Typical verification:

gbrain embed --all --db ~/.gbrain/main.db
gbrain query "who knows Jensen Huang?" --db ~/.gbrain/main.db

CLI usage

# Write a page from stdin
cat page.md | gbrain put people/jane-doe --db ~/.gbrain/main.db

# Read a page
gbrain get people/jane-doe --db ~/.gbrain/main.db

# Full-text search
gbrain search "Series A" --db ~/.gbrain/main.db

# Hybrid semantic search
gbrain query "who is connected to Anthropic?" --db ~/.gbrain/main.db

# Filtered list
gbrain list --type person --limit 20 --db ~/.gbrain/main.db

# Timeline
gbrain timeline people/jane-doe --db ~/.gbrain/main.db
gbrain timeline-add people/jane-doe --date 2026-04-06 --summary "Met at demo day" --source meeting --db ~/.gbrain/main.db

# Import / export
gbrain import /path/to/notes --db ~/.gbrain/main.db
gbrain export --dir ./export --db ~/.gbrain/main.db

# Embeddings
gbrain embed --all --db ~/.gbrain/main.db

MCP usage

GBrain exposes an MCP server over stdio:

gbrain serve --db ~/.gbrain/main.db

A typical MCP config looks like this:

{
  "mcpServers": {
    "gbrain": {
      "command": "gbrain",
      "args": ["serve", "--db", "/Users/you/.gbrain/main.db"]
    }
  }
}

The current tool surface includes:

• brain_get
• brain_put
• brain_ingest
• brain_link
• brain_search
• brain_query
• brain_timeline
• brain_timeline_add
• brain_tags
• brain_tag
• brain_list
• brain_backlinks
• brain_stats
• brain_raw

OpenClaw

OpenClaw is now a first-class integration target for this repo.

The OpenClaw path adds three things on top of the generic MCP setup:

• the GBRAIN_PROFILE=openclaw runtime preset
• the shipped skills/ pack
• the optional session ingest hook in hooks/gbrain-ingest-session

Use the dedicated guide for the full install path:

• docs/openclaw.md

Once the package is published, the versioned plugin install path is:

openclaw plugins install @laozhong86/gbrain-openclaw
openclaw gateway restart

That installs the published GBrain OpenClaw plugin package without requiring a source checkout. The package metadata and release workflow are prepared for this path; the actual registry publish still depends on maintainer npm credentials. On first load, the plugin auto-provisions mcp.servers.gbrain if it is missing. The local gbrain binary still needs to exist.

For local development or pre-publish testing, the repo path still works:

openclaw plugins install /absolute/path/to/GBrain/plugins/openclaw
openclaw gateway restart

Skills

Shipped workflow guides live under skills/:

• skills/gbrain-cli
• skills/ingest
• skills/query
• skills/maintain
• skills/enrich
• skills/briefing

These are the operational layer on top of the CLI and MCP surface.

Upgrade

If you installed the compiled binary:

gbrain upgrade --check
gbrain upgrade

gbrain upgrade downloads the latest matching binary from GitHub Releases, verifies it against the published SHA256SUMS, and replaces the local executable in place.

Current release assets cover:

• gbrain-linux-x64
• gbrain-darwin-arm64
• gbrain-darwin-x64

If self-update is unavailable on the current platform, the manual path still works:

git pull
bun install
bun run check
bun test
bun run build
cp bin/gbrain ~/.local/bin/gbrain
chmod +x ~/.local/bin/gbrain

Development

Before finishing work:

bun run check
bun test
bun run build

Related docs

• DEPLOYMENT.md
• CLAUDE.md

License

MIT

See LICENSE.

Credits

Original GBrain spec and architecture — Garry Tan

The core ideas come from the GBrain spec: compiled truth + timeline, thin CLI + fat skills, and MCP-native local memory.

Repository implementation and packaging — laozhong86

This repository turns that spec into a working local CLI, MCP server, release workflow, and operator-facing skill pack.