GBrain Agent Memory for Claude Code, Codex, and Hermes

# GBrain Agent Memory for Claude Code, Codex, and Hermes

AI Summary

Purpose:

• Documents how this server wires GBrain into Claude Code, Codex, and Hermes so agents can retrieve the LLM Wiki and shared project memory before answering or coding.

Key points:

• GBrain 0.42.51.0 is installed at /home/khw-bot/.bun/bin/gbrain via Bun 1.3.14.
• The local brain uses PGLite under the user's GBrain home and is initialized with gbrain init --pglite --no-embedding.
• Claude Code, Codex, and Hermes all have a gbrain MCP server configured as /home/khw-bot/.bun/bin/gbrain serve.
• llm-wiki is registered as a GBrain source and synced with --no-embed because no embedding provider key is configured yet.
• The retrieval-reflex integration is installed into this repository under skills/retrieval-reflex/ and adds a resolver row to AGENTS.md.

Relevant when:

• An agent needs to answer from durable project memory instead of guessing.
• An agent is about to discuss a named person, company, project, repo, or prior decision.
• Claude Code, Codex, or Hermes cannot see GBrain tools and needs setup or troubleshooting.
• A future agent needs to install the same GBrain retrieval policy into another repo.

Do not read full document unless:

• You are configuring GBrain/MCP, troubleshooting memory retrieval, or deciding how agents should query the brain.

Linked documents:

• AGENTS.md
• skills/retrieval-reflex/SKILL.md
• ai/wiki/concepts/llm-wiki.md
• ai/wiki/projects/hermes-discord-llm-wiki-system.md

Open Questions

• Embeddings are not enabled because ZEROENTROPY_API_KEY is not configured. Keyword search works; vector/hybrid quality should improve after adding an embedding provider and running gbrain embed --stale.
• gbrain health reports no graph links yet. The wiki currently has Markdown references but GBrain did not extract graph edges from the current page set.

Details

Current installation

Installed tools:

bun --version
# 1.3.14

gbrain --version
# gbrain 0.42.51.0

GBrain binary path:

/home/khw-bot/.bun/bin/gbrain

Local brain initialization used:

gbrain init --pglite --no-embedding --yes

Reason:

• PGLite keeps this local and simple; no Supabase/Postgres service is required.
• --no-embedding avoids blocking setup on a missing embedding provider key.

Current health snapshot after initial sync:

Pages:     169
Chunks:    814
Embedded:  0
Links:     0
Tags:      46
Timeline:  0

MCP wiring

All three local agent clients use the same stdio MCP server:

/home/khw-bot/.bun/bin/gbrain serve

Claude Code

Configured as a user-scoped MCP server:

claude mcp add -s user gbrain -- /home/khw-bot/.bun/bin/gbrain serve

Verify:

claude mcp list
# gbrain: /home/khw-bot/.bun/bin/gbrain serve - ✔ Connected

Codex

Configured as a global MCP server:

codex mcp add gbrain -- /home/khw-bot/.bun/bin/gbrain serve

Verify:

codex mcp list
codex mcp get gbrain
# command: /home/khw-bot/.bun/bin/gbrain
# args: serve
# status: enabled

Hermes

Configured in the active Hermes profile:

printf 'Y\n' | hermes mcp add gbrain --command /home/khw-bot/.bun/bin/gbrain --args serve

Verify:

hermes mcp list
# gbrain /home/khw-bot/.bun/bin/gbrain serve all ✓ enabled

Important:

• Hermes loads MCP tools at session start. After adding GBrain, start a new Hermes session before expecting mcp_gbrain_* tools to appear.

LLM Wiki source registration

The LLM Wiki is registered as a GBrain source:

gbrain sources add llm-wiki --path /home/khw-bot/workspace/repos/llm-wiki

Initial sync:

gbrain sync --source llm-wiki --no-embed --yes

If sync reports failed files, inspect and fix them rather than silently skipping. During the initial setup, one Markdown file contained a raw NUL byte in a code snippet and was fixed by replacing the actual byte with the text escape \\x00.

After sync, verify:

gbrain sources list
gbrain stats
gbrain search 'LLM Wiki'
gbrain query 'What is the LLM Wiki?' --no-expand

Expected behavior:

• Search/query should return pages such as ai/wiki/concepts/llm-wiki and other LLM Wiki pages.

Retrieval Reflex integration

retrieval-reflex teaches host agents when to look up brain pages instead of answering from stale memory.

Installed into this repo with:

gbrain integrations install retrieval-reflex --target /home/khw-bot/workspace/repos/llm-wiki

This created:

skills/retrieval-reflex/SKILL.md
skills/retrieval-reflex/.gbrain-source.json

It also appended a resolver row to AGENTS.md:

retrieval-reflex | a named person/company/project/place becomes the subject; a brain-page pointer appears in context; "who is", "what do we know about", "tell me about"; about to assert a non-trivial detail about a named entity

If another repo lacks the plugin/policy, install it with:

gbrain integrations install retrieval-reflex --target /path/to/target-repo

Then commit the resulting skills/retrieval-reflex/ directory and AGENTS.md changes if that repo tracks agent policy files.

How agents should use GBrain while talking

Use GBrain before answering when the user asks about:

• a named person;
• a company, project, repo, or system;
• a prior decision or worklog item;
• a portfolio/resume fact;
• a non-trivial historical detail that may be in llm-wiki.

Recommended escalation:

1. Search first:

``bash gbrain search '<entity or question>' ``

1. Use hybrid/expanded retrieval when the question is broader:

``bash gbrain query '<question>' ``

1. Read the specific page before relying on details:

``bash gbrain get '<slug>' ``

1. Use graph/backlinks only if relationship context matters:

``bash gbrain graph '<slug>' --depth 1 gbrain backlinks '<slug>' ``

For MCP-capable clients, prefer the MCP tools over shell commands when available:

• search / query for discovery;
• get_page for exact source text;
• get_backlinks / traverse_graph for relationship context;
• get_health / get_stats for troubleshooting.

Prompting pattern for Claude Code and Codex

When launching a coding agent on this server, include an explicit retrieval instruction if the task depends on prior context:

Before answering or editing, use the gbrain MCP server to search the LLM Wiki for relevant repo notes, worklogs, and decisions. Read exact pages before making claims. If GBrain has no result, say so and fall back to filesystem inspection.

For named-entity questions:

Use the retrieval-reflex policy: if a person/company/project/repo is the subject, query GBrain first and read the page before asserting details.

Troubleshooting

gbrain command not found

Use the absolute path:

/home/khw-bot/.bun/bin/gbrain --version

If Bun is missing:

curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
bun install -g github:garrytan/gbrain

MCP server missing from a client

Re-add the server with the absolute path:

claude mcp add -s user gbrain -- /home/khw-bot/.bun/bin/gbrain serve
codex mcp add gbrain -- /home/khw-bot/.bun/bin/gbrain serve
printf 'Y\n' | hermes mcp add gbrain --command /home/khw-bot/.bun/bin/gbrain --args serve

Hermes has config but no GBrain tools in this session

Start a new Hermes session. Hermes discovers MCP tools at session startup.

Embedding warnings

Current setup intentionally has no embedding key. Keyword search works, but gbrain doctor may warn:

embedding_model="zeroentropyai:zembed-1" but ZEROENTROPY_API_KEY is not set

To enable embeddings later:

export ZEROENTROPY_API_KEY='<key>'
gbrain embed --stale

Do not commit keys to the repo.

Sync blocked by bad Markdown

Run:

gbrain sync --source llm-wiki --no-embed --yes

If it fails, check:

cat ~/.gbrain/sync-failures.jsonl

Fix malformed Markdown/encoding issues and rerun. Use --skip-failed only when the file is intentionally excluded and the failure is understood.