garrytan/gbrain

GBrain – a personal‑agent memory daemon

What it is

• GBrain is a self‑hosted service that gives any LLM‑powered agent a structured, editable memory store you control. It records facts (pages) together with their source URLs, lets you correct or withdraw entries, and can surface that knowledge as either raw chunks, synthesized answers, or a typed knowledge‑graph.

Key ideas

• Explicit, provenance‑rich facts – every piece of information is stored as a page with a citation, so the agent can point you to the original source.
• Correction & withdrawal – you can update or delete facts, and the system tracks those changes.
• Shared across agents – the same brain can be attached to multiple agents (e.g., Grok Bot, Muse, Claude Code, Codex) while keeping each agent’s identity separate.
• Optional layers – start with simple keyword retrieval; later enable semantic search, LLM‑based synthesis (answers with citations), or a graph view for relationship queries.
• Company‑brain mode – with authentication, remote clients can read/write only within the permissions you grant, making it usable as a shared corporate knowledge base.

How you use it

1. Add to an existing agent – run the gbrain setup <harness> command (Claude Code, Codex, Grok Bot, etc.). The tool injects a small launcher into the agent, creates a local brain directory, and wires up MCP (the “memory‑client‑protocol”) so the agent can call remember, recall, correct, etc.
2. Run it as a standalone service – gbrain init … creates a daemon that you can expose over MCP (e.g., via a Tailscale tailnet). Other machines or cloud agents can then say “use my brain over mcp” to connect.
3. Connect a hosted brain – use the OAuth / private‑machine flow to attach a remote brain to a cloud‑hosted harness.

Typical workflow

• The daemon continuously ingests your data (emails, meeting notes, tweets, voice transcripts, etc.) and enriches it overnight.
• When you ask a question, the agent calls the brain:
  • Keyword/semantic search → returns relevant pages.
  • Synthesis layer (optional) → the LLM builds a concise answer, cites each fact, and adds a gap analysis note telling you what the brain doesn’t know.
  • Graph adapter (optional) → you can ask relational questions like “who works at Acme?” and get answers derived from stored edges without extra LLM calls.

Why it matters

• Eliminates the “search‑then‑read” loop: the brain does the reading and summarising for you.
• Provides a single source of truth for personal or corporate knowledge, with audit‑able provenance.
• Works on your own hardware and data, so you keep control over privacy and cost.

Installation snapshot

# Install the binary via Bun (required version ≥ 1.4)
bun install -g github:garrytan/gbrain

# Quick setup for Claude Code (or Codex)
gbrain setup claude-code   # add --dry-run to preview, --remove to undo

• The setup command creates the brain directory, writes MCP hooks, and runs a health‑check (gbrain doctor).
• For a pure CLI brain (no agent) you can run:

gbrain init --pglite --no-embedding   # keyless, local SQLite‑style store
gbrain import ~/my-notes/ --no-embed  # index markdown files

• Remote exposure: gbrain mcp expose (optionally --funnel for cloud agents) publishes the daemon over your Tailscale network.

Supported agents / integrations

• Grok Bot – install an isolated launcher that keeps the brain on your machine.
• Muse / Muse Code – similar flow, with native editable memory plus GBrain’s portable layer.
• Claude Code & Codex – plugin‑based installation (codex plugin add gbrain@gbrain etc.)
• OpenClaw / Hermes – full‑stack deployments where the brain runs 24/7 on a server.
• Any MCP‑compatible client – Cursor, Windsurf, custom stdio tools can add a gbrain command to their MCP config.

Performance hint

• The built‑in benchmark (BrainBench) shows the graph adapter improves precision/recall on relationship queries (P@5 0.342 vs 0.192 for plain hybrid retrieval).

Safety & limits

• The brain does not guarantee that remote callers can’t see local files; permissions are enforced per‑source and per‑operation.
• The daemon is not distributed on npm – installing the wrong gbrain package can shadow the real binary. The README warns to use the Bun‑based install only.

Bottom line GBrain is a production‑grade, self‑hosted memory layer for LLM agents. It lets you keep a searchable, cite‑backed knowledge base under your control, share it across personal or corporate agents, and optionally get LLM‑generated answers or graph‑style queries without leaving your own infrastructure.