mirror of https://github.com/garrytan/gbrain.git synced 2026-08-14 00:48:18 +00:00

Files

T

Garry TanandClaude Fable 5 15ecc65b24 v0.45.7.0 feat(mcp,context): ambient recall — context_pack + delta frozen verbs + boundary runtime (#1 ) (#4028 )

* 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>

2026-08-12 10:56:11 -07:00

5.2 KiB

Raw Permalink Blame History

Connect GBrain to Claude Code

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.

Want the full agent — identity, per-turn context, schedules, and a private repo as its durable body — not just a memory? That's gbrain bootstrap: see the paste block in the README and docs/guides/bootstrap.md. Open a new empty folder (bootstrap creates the private repo for you), or make an empty private repo under your own account and open the clone — bootstrap adopts it.

Option 1: Local (recommended, zero server needed)

claude mcp add gbrain -- gbrain serve --surface verbs

That's it. Claude Code spawns gbrain serve as a stdio subprocess. No server, no tunnel, no token needed. Works with both PGLite and Supabase engines.

--surface verbs exposes the five-verb memory protocol (recall, remember, entity, synthesize, forget — MEMORY_VERBS v1), the surface built for agents and quickstarts. Drop the flag for the full operation catalog (get_page, put_page, search, graph ops, …) — full is the default and what existing installs already run.

Option 2: Remote, one command (fastest from a bearer token)

If GBrain is running somewhere as an HTTP server (gbrain serve --http, see the ngrok-tunnel recipe) and you have a bearer token, let gbrain connect generate the wire-up for you.

On the host (or anywhere gbrain is installed), mint a token and print the block:

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

gbrain connect prints a short, copy-paste block. Paste it into Claude Code — it runs the claude mcp add for you and tells the agent to call get_brain_identity and list_skills so it immediately knows what the brain can do.

Already on the machine you want to wire up? Skip the copy-paste and let connect do it directly, with a built-in token smoke-test:

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

(--install runs claude mcp add, then verifies the token by calling get_brain_identity — so a wrong or expired token fails now, not silently on the agent's first request. The URL is normalized: a bare host without /mcp gets it appended; pass an explicit https:// scheme.)

Pipe-friendly machine output (token redacted unless --show-token):

gbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token gbrain_xxx --json

Option 3: Remote, manual `claude mcp add`

Equivalent to what gbrain connect generates, if you'd rather run it yourself:

claude mcp add gbrain -t http \
  https://YOUR-DOMAIN.ngrok.app/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

Replace YOUR-DOMAIN with your ngrok domain and YOUR_TOKEN with a token from gbrain auth create "claude-code".

A gbrain auth create token is a long-lived, full-access secret. Keep it private (it lands in ~/.claude.json), and prefer a scoped/short-lived token where your host supports one.

Verify

In Claude Code, try:

search for [any topic in your brain]

You should see results from your GBrain knowledge base.

list_skills returns nothing? Skill discovery is gated by mcp.publish_skills on the host. New brains from gbrain init default it ON; brains upgraded from an older release stay OFF until you opt in. Enable it on the host with gbrain config set mcp.publish_skills true. Skill discovery and the core tools named here (search, query, get_page, put_page, think, find_experts) are full-surface — on --surface verbs the agent sees only the seven memory verbs, and list_skills isn't on the surface at all. Note: capture is a CLI-only command, not an MCP tool — the agent writes over MCP with put_page. Why brains differ on the default: tutorial A1.

Ambient recall at session boundaries (v0.45.7)

Two frozen verbs close the "no question fired" gap for long-lived sessions: context_pack (session-start warm-up + post-compaction rehydration) and delta ("what changed since my last wake" for heartbeats). Both are zero-LLM, sub-second, world-visibility by default, and available on --surface verbs.

Automatic (PGLite brains via gbrain bootstrap): the bootstrap hook installer wires SessionStart (injects a warm pack; also fires on post-compaction re-entry, source=compact) and PreCompact (banks the window's standing entities so that rehydration pack is warm) into .claude/settings.local.json. Nothing to call; GBRAIN_HOOKS=0 disables.
Manual (any brain, incl. remote/Postgres): call the verbs yourself at boundaries — context_pack(entities, budget_tokens) at session start / after compaction, delta(session_id, budget_tokens) on wakes. See ambient recall for the placement frontier and the per-verb latency table.

Remove

claude mcp remove gbrain

5.2 KiB Raw Permalink Blame History