Garry TanandClaude Opus 4.8
a996e42856
* fix(bootstrap): harden create-repo-first repo adoption `gbrain bootstrap repo` adopts an empty, private, personally-owned GitHub repo the human created (create-repo-first), instead of only ever creating one. This hardens the existing adoption branch: - Empty-only adoption + pending_repo_url proof: a non-empty origin is refused (ORIGIN_NOT_EMPTY) unless it matches this workspace's pending marker (our own interrupted push). Never adopts a user's existing project from a git-ancestry guess, and never silently no-ops without pushing. - Repo-local git identity is set on the adopt path too (fresh-machine commits). - repo_url is recorded only AFTER a successful push (pending marker before); a failed push no longer looks "done" to `bootstrap status`. - Pre-push secret scan also covers an already-committed tree; ls-files failure fails closed. - assertOriginMatches binds BOTH the fetch URL and a configured push URL to the verified-private repo, so a foreign pushurl can't leak the workspace. - disposition: 'created' | 'adopted' | 'reused' replaces the overloaded flag. - Hook push-gate: the no-daemon session-end / recovery push is deferred until the repo phase records repo_url AND the current origin still matches it, so nothing is published to an unverified or redirected remote. Adds ORIGIN_NOT_EMPTY / REMOTE_CHECK_FAILED error codes. * docs(bootstrap): lead with the repo, document create-repo-first README (Claude Code + Codex) now opens with "the folder you open becomes your agent's private repo" and adds a "prefer to make the repo yourself?" callout for the create-repo-first path (empty, personal-account repo). Updates the bootstrap guide, the Claude Code MCP note, and the KEY_FILES / AGENT_BOOTSTRAP_PLAN invariants to describe adoption instead of "foreign origins refused". * v0.45.1.0 fix(bootstrap): create-repo-first repo adoption + hardening Bumps VERSION/package.json to 0.45.1.0, adds the CHANGELOG entry, refreshes the runbook + template-repo version stamps, and regenerates the llms bundle. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(todos): file P2 follow-up — index-blob secret scan for bootstrap pushes * ci(gitleaks): run the free CLI instead of the license-gated v2 action gitleaks-action@v2 now enforces a paid GITLEAKS_LICENSE and fails the job ("missing gitleaks license") for accounts it can't validate over the API — blocking every PR's merge gate. Replace it with the open-source gitleaks CLI (pinned 8.30.1, checksum-verified against the release's own checksums file), scanning the PR/push commit range with the committed .gitleaks.toml allowlist. Same secret-scan coverage, no license wall. * v0.45.2.0 chore(release): re-bump 0.45.1.0 -> 0.45.2.0 Re-target the release version at the user's request. Updates VERSION, package.json, the CHANGELOG header + self-repair block, the runbook + template-repo version stamps, the TODOS follow-up reference, and the llms bundle. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(perf): raise entity-card ratio ceiling 50x -> 100x (CI flake) The RATIO GUARD asserted entity p99 <= 50x max(getPage p50, 1ms). On a fast runner getPage p50 floors to 1ms and a normal entity p99 (~50ms) reads as ~52x, tripping the gate even though absolute p99 (52ms) is well under the 100ms budget — a p99 tail divided by a sub-ms median. At the 1ms floor, 50x also made the ratio STRICTER than the test's own 100ms absolute budget. Raise the ceiling to 100x: still far below the >=200x O(N)-regression signal the guard exists to catch, and consistent with (never stricter than) the absolute budget. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4.2 KiB
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 createtoken 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_skillsreturns nothing? Skill discovery is gated bymcp.publish_skillson the host. New brains fromgbrain initdefault it ON; brains upgraded from an older release stay OFF until you opt in. Enable it on the host withgbrain 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 verbsthe agent sees only the five memory verbs, andlist_skillsisn't on the surface at all. Note:captureis a CLI-only command, not an MCP tool — the agent writes over MCP withput_page. Why brains differ on the default: tutorial A1.
Remove
claude mcp remove gbrain