mirror of https://github.com/garrytan/gbrain.git synced 2026-07-30 11:22:34 +00:00

Files

T

Garry TanandClaude Fable 5 f60ba9c83d test+docs(protocol): conformance suite, p99 gate, MEMORY_VERBS_v1 doc, funnel

test/memory-verbs-conformance.test.ts: 26 tests through dispatchToolCall —
G1B superset regression (legacy fields byte-equal, additions allowed), budget
math incl. budget<first-item, keyword degradation (never an error), remember
provenance/ttl-trap/null-echo, remote round-trip via the world default +
private facts hidden, entity card schema-validated with the chat gateway
rigged to throw (zero-LLM guard) + all arms + fence test, synthesize
[EXPENSIVE + annotations + clean unavailable, forget idempotency/not_found,
writeSingleFact X1 supersession via the embed-transport seam + degraded
dedup, the F3 negative self-test (the runner FAILS lying servers: dropped
fields, bad enums, re-typed ids), fixture-mirror drift guard.
test/mcp-surface.test.ts: verbs=exactly 5, full=identity, dispatch-layer
fail-closed, strict flag parsing. test/entity-card-perf.slow.test.ts: 20K
pages/100K links/30K aliases/40K facts — measured p99 22.9ms vs the 100ms
contract + a recalibrated 50x ratio guard; wired into the CI perf job along
with stdio self-certification (23/23 CONFORMANT live). tool-defs byte-
stability test now pins per-op: ops WITHOUT annotations keep the exact
pre-v1 shape.

docs/protocol/MEMORY_VERBS_v1.md: the frozen contract — envelopes, error
codes, additive-forever policy, ttl forms (P30D rejected), status-not-
status_text, surface modes + why default full, per-harness installs, consent
line, conformance pass criteria + copyable --target examples, local-only
stats privacy, 200K manual bench recipe. README quickstart + docs/mcp pages
moved to --surface verbs with the claude-not-found recovery; llms-config
registered + bundles rebuilt; KEY_FILES entries for the 7 new modules.

Cathedral 1 stage 4/4 (#cathedral-1)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-06-12 10:24:47 -07:00

2.6 KiB

Raw Blame History

Connect GBrain to Codex

New to this? The Give your coding agent a memory tutorial walks both paths (local-from-nothing and connect-to-an-existing-brain) end to end, plus the brain-first protocol that makes it worth it. This page is the connection reference.

Codex CLI (@openai/codex, v0.130+) supports remote streamable-HTTP MCP servers with a bearer token read from an environment variable. The token lives in your shell env, not in Codex's config file.

Fastest path: `gbrain connect`

Run anywhere gbrain is installed (mint a token on the brain host first):

gbrain auth create "codex"
gbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token gbrain_xxx --agent codex

This prints a copy-paste block. Or wire it up directly and smoke-test the token:

gbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token gbrain_xxx --agent codex --install

--install runs codex mcp add for you, then makes one real call to the brain so a wrong/expired token fails right away. Because Codex reads the token from the env var at runtime, keep GBRAIN_REMOTE_TOKEN exported in your shell profile.

Manual setup

export GBRAIN_REMOTE_TOKEN=gbrain_xxx
codex mcp add gbrain --url https://YOUR-DOMAIN.ngrok.app/mcp \
  --bearer-token-env-var GBRAIN_REMOTE_TOKEN

Codex stores the env-var name (GBRAIN_REMOTE_TOKEN), not the token itself, and reads the value when it launches the MCP server. Add the export line to your ~/.zshrc / ~/.bashrc so it's set in every session.

Verify

In Codex, ask it to use the brain:

Call get_brain_identity, then search my brain for [topic].

get_brain_identity confirms whose brain you're connected to; list_skills shows everything it can do.

list_skills empty? It's gated by mcp.publish_skills on the host (default ON for gbrain init brains, OFF for brains upgraded from older releases). Enable it on the host: gbrain config set mcp.publish_skills true. The core tools (search, query, get_page, put_page, think, find_experts) work regardless. capture is CLI-only, not an MCP tool — write over MCP with put_page.

Remove

codex mcp remove gbrain

Notes

The token is a long-lived, full-access secret. Keep GBRAIN_REMOTE_TOKEN out of version control and prefer a scoped token if your host supports one.
Local stdio also works if you run the brain on the same machine: codex mcp add gbrain -- gbrain serve --surface verbs — the five-verb memory protocol (MEMORY_VERBS v1); drop the flag for the full operation catalog.

2.6 KiB Raw Blame History