From e529f2194e151f61ab24690583fcf3c6ee93bd3f Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 04:15:22 +0000 Subject: [PATCH] Fix GBrain portability issues for cross-machine/user compatibility - Remove hard-coded /root/.gbrain path from MCP configuration - Use default GBRAIN_HOME resolution for portability across users/machines - Clarify documentation: separate repo-level config from local setup - Update GBRAIN_QUICKSTART.md to include initial gbrain init step - Update GBRAIN_INTEGRATION.md setup status and instructions - Add clear distinction between repository files and user's ~/.gbrain state - Correct step numbering in quick start guide These changes address the portability concerns identified in code review: - MCP config now works for any user, not just root - Documentation no longer conflates local state (~/.gbrain) with repo files - New developers get clear instructions to initialize their own brain locally --- .claude/gbrain-setup.md | 25 +++++++++++++++++++------ .claude/mcp/gbrain.json | 5 +---- docs/GBRAIN_INTEGRATION.md | 24 ++++++++++++++---------- docs/GBRAIN_QUICKSTART.md | 28 +++++++++++++++++++--------- 4 files changed, 53 insertions(+), 29 deletions(-) diff --git a/.claude/gbrain-setup.md b/.claude/gbrain-setup.md index bcf996102..6c23bd469 100644 --- a/.claude/gbrain-setup.md +++ b/.claude/gbrain-setup.md @@ -1,5 +1,11 @@ # GBrain Setup for Open-Generative-AI +## Overview + +This project includes GBrain integration for persistent agent memory. The integration consists of: +- **Repository-level configuration**: MCP setup and documentation (checked into git) +- **Local user setup**: Each developer initializes their own `~/.gbrain/` brain on their machine + ## What Was Installed This project now has GBrain integrated for persistent agent memory. @@ -15,16 +21,23 @@ This project now has GBrain integrated for persistent agent memory. | **Search** | ✅ Keyword-only | Vector embeddings optional (requires API key) | | **Team Brain** | ⏳ Optional | Can upgrade to Supabase multi-user later | -### Files Added +### Files Added to Repository ``` ├── .claude/mcp/gbrain.json # MCP configuration ├── docs/GBRAIN_INTEGRATION.md # Full integration guide -├── docs/GBRAIN_QUICKSTART.md # 5-minute quick start -└── ~/.gbrain/ # Brain home (user's directory) - ├── brain.pglite # PGLite database - ├── config.json # Brain configuration - └── brain-repo/ # Optional markdown pages dir +└── docs/GBRAIN_QUICKSTART.md # 5-minute quick start +``` + +### Local Setup (Created on Each User's Machine) + +When you run `gbrain init`, the following is created in your home directory (not in the repo): + +``` +~/.gbrain/ +├── brain.pglite # PGLite database (Postgres via WASM) +├── config.json # Brain configuration +└── brain-repo/ # Optional markdown pages directory ``` ### What It Does diff --git a/.claude/mcp/gbrain.json b/.claude/mcp/gbrain.json index 147e04afe..4ac30ef80 100644 --- a/.claude/mcp/gbrain.json +++ b/.claude/mcp/gbrain.json @@ -6,10 +6,7 @@ "serve", "--surface", "verbs" - ], - "env": { - "GBRAIN_HOME": "/root/.gbrain" - } + ] } } } diff --git a/docs/GBRAIN_INTEGRATION.md b/docs/GBRAIN_INTEGRATION.md index 3035f791d..b5fdf278b 100644 --- a/docs/GBRAIN_INTEGRATION.md +++ b/docs/GBRAIN_INTEGRATION.md @@ -11,21 +11,25 @@ GBrain is a persistent knowledge brain for AI agents. This project has been conf ## Setup Status -✅ **Initialized**: PGLite local brain at `~/.gbrain/brain.pglite` -✅ **Memory writeback**: Enabled (salient mode) — captures important decisions automatically -⏳ **Embeddings**: Not yet configured (optional but recommended for semantic search) +✅ **Repository**: GBrain MCP configuration committed to `.claude/mcp/gbrain.json` +⏳ **Local brain**: Initialize on your machine with `gbrain init --no-embedding` +⏳ **Embeddings**: Optional (can add later with API key for semantic search) ## How to Use -### 1. Enable MCP in Claude Code +### 1. Initialize GBrain on Your Machine -Add gbrain to Claude Code's MCP servers: +First, initialize your local brain (runs once per machine): ```bash -claude mcp add gbrain -- gbrain serve --surface verbs +gbrain init --no-embedding # Initialize without embeddings ``` -Then restart Claude Code. You'll have access to the 7-verb memory protocol: +This creates `~/.gbrain/brain.pglite` and configuration on your machine. + +### 2. Restart Claude Code + +The MCP configuration (`.claude/mcp/gbrain.json`) loads automatically at startup. Restart Claude Code to activate it. You'll then have access to the 7-verb memory protocol: - `remember` — save a fact for future sessions - `recall` — retrieve remembered facts by topic - `entity` — query information about a specific person/company/project @@ -34,7 +38,7 @@ Then restart Claude Code. You'll have access to the 7-verb memory protocol: - `context_pack` — get a summary of context for this brain - `delta` — get what's changed since last recall -### 2. Quick Test +### 3. Quick Test In a Claude Code session: @@ -50,7 +54,7 @@ recall: "my Python style" It will remember across sessions — the answer comes from gbrain, not chat history. -### 3. Capturing Knowledge +### 4. Capturing Knowledge **Manually capture a note:** ```bash @@ -67,7 +71,7 @@ gbrain capture --file ./notes/2026-09-12-meeting.md echo "Completed the performance audit" | gbrain capture --stdin ``` -### 4. Querying Your Brain +### 5. Querying Your Brain **Keyword search (fast, works now):** ```bash diff --git a/docs/GBRAIN_QUICKSTART.md b/docs/GBRAIN_QUICKSTART.md index b77d992e3..d20c9af7f 100644 --- a/docs/GBRAIN_QUICKSTART.md +++ b/docs/GBRAIN_QUICKSTART.md @@ -4,16 +4,26 @@ GBrain is now integrated with this project. This guide gets you using it in 5 mi ## What You Have -✅ Local brain initialized at `~/.gbrain/brain.pglite` -✅ Memory writeback enabled (auto-captures decisions) -✅ MCP configuration ready (`.claude/mcp/gbrain.json`) -✅ 7-verb memory protocol loaded +✅ GBrain integrated (repository-level MCP configuration ready) +✅ MCP configuration (`.claude/mcp/gbrain.json`) +✅ 7-verb memory protocol available +⏳ Local brain pending — initialize on your machine with `gbrain init` -## Step 1: Restart Claude Code +## Step 1: Initialize GBrain on Your Machine -The MCP wiring loads at startup. Restart Claude Code (desktop or CLI) after the integration is complete. +First, initialize your local brain: -## Step 2: Test Memory Across Sessions +```bash +gbrain init --no-embedding # Initialize without embeddings (optional, can add later) +``` + +This creates `~/.gbrain/brain.pglite` and configuration on your machine. + +## Step 2: Restart Claude Code + +The MCP wiring loads at startup. Restart Claude Code (desktop or CLI) after the initialization is complete. + +## Step 3: Test Memory Across Sessions **In your first Claude Code session:** @@ -33,7 +43,7 @@ recall: "what am I working on?" **Expected result:** Claude Code knows the answer even though chat history was cleared. The brain persisted it across sessions. -## Step 3: Capture Knowledge +## Step 4: Capture Knowledge As you work, capture insights: @@ -48,7 +58,7 @@ echo "Implemented batch API response caching" | gbrain capture --stdin gbrain capture --file ./session-notes.md ``` -## Step 4: Query What You Know +## Step 5: Query What You Know Ask the brain questions: