mirror of
https://github.com/garrytan/gbrain.git
synced 2026-08-14 00:48:18 +00:00
Garry TanandClaude Fable 5
15ecc65b24
* feat(mcp,context): ambient recall — context_pack + delta frozen verbs + boundary runtime (#1) Two new frozen MEMORY_VERBS (context_pack, delta) on the pull surface + a Claude Code hook boundary runtime on the push surface, sharing one stateless assembler core (assembleTurnContext mode: turn|pack|delta) and a keyset session cursor (migration v126). World-only by default; include_private gated fail-closed to trusted-local. protocol_version stays 1 (additive 5→7 verbs). Survived three adversarial review waves. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * v0.45.7.0 feat(mcp,context): ambient recall — context_pack + delta frozen verbs + boundary runtime (#1) Two new frozen MEMORY_VERBS (context_pack, delta) grow the frozen set 5→7 without a wire bump — all seven stamp protocol_version: 1. context_pack assembles a deterministic, zero-LLM, budget-packed bundle (entity cards + open threads + hot facts) for a set of standing entities; delta returns only what changed since a timestamp for cheap heartbeats, with a per-session keyset cursor for at-least-once delivery. A boundary runtime wires these into Claude Code lifecycle hooks (SessionStart warm pack, PreCompact entity banking for post-compaction rehydration); Codex and any MCP host pull the same verbs at their own boundaries. World-only by default on all arms; include_private widens only for local trusted callers. Migration v126 adds session_context_state (additive). Includes the coverage close-out wave (~55 tests): real-serve compact→ session-start round trip over the live socket, --surface verbs stdio session pinning exactly 7 tools fail-closed, HTTP-transport verb calls with per-token cursor isolation, Postgres engine-parity for keyset pagination + the session-cursor table, migration v126 shape + rewind test, sub-second latency gates, CLI-level invocations, rendered-protocol boundary assertions, and a live-Codex boundary-call check. The wave caught and fixed three real bugs: the delta CLI wedging on first wake (floating GC promise racing engine teardown), the compact hook probing the PGLite socket on a Postgres config with a leftover database_path, and the verbs-surface banner hardcoding a stale verb count. Also the /document-release sweep: stale "five verbs" → seven across the protocol doc, README, INSTALL, DEPLOY, the Claude Code MCP guide, and the query skill; deferred scope filed in TODOS. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(release): bump openclaw.plugin.json to 0.45.7.0 — the sixth version location The #4033 merge auto-resolved the OpenClaw plugin manifest at master's version while the trio moved to 0.45.7.0, failing the manifest drift test on CI shard 4. Register the file in CLAUDE.md's version-locations table (five → six) so every future ship and merge re-bumps it with the trio. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
# Connect GBrain to Codex
|
|
|
|
> New to this? The [Give your coding agent a memory](../tutorials/connect-coding-agent.md)
|
|
> 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.
|
|
>
|
|
> Want the **full agent** — identity, memory, schedules, and a private repo as its
|
|
> durable body — not just a connection? That's `gbrain bootstrap`: see the paste
|
|
> block in the README and [docs/guides/bootstrap.md](../guides/bootstrap.md).
|
|
|
|
Recent versions of the Codex CLI (`@openai/codex`) support 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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 — enable
|
|
> it with `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, so write over MCP with `put_page`. Why brains differ on the default:
|
|
> [tutorial A1](../tutorials/connect-coding-agent.md#a1-on-the-host-serve-over-http).
|
|
|
|
## Remove
|
|
|
|
```bash
|
|
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 memory-verb
|
|
protocol ([MEMORY_VERBS v1](../protocol/MEMORY_VERBS_v1.md)); drop the flag
|
|
for the full operation catalog.
|
|
- **Ambient recall (Codex has no lifecycle hooks — use the pull path).** At the
|
|
start of a topical thread and after a compaction, call
|
|
`context_pack(entities, budget_tokens)` to warm the standing entities; on a
|
|
periodic wake call `delta(session_id, budget_tokens)` for "what changed since
|
|
my last wake" (deduped per session). Both are zero-LLM, sub-second, world-only
|
|
by default, and on `--surface verbs`. See
|
|
[ambient recall](../guides/ambient-recall.md) for the placement frontier.
|