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>
147 lines
7.4 KiB
Markdown
147 lines
7.4 KiB
Markdown
# Install
|
|
|
|
**Recommended door: the agent bootstrap.** Open your agent (Codex, Claude Code,
|
|
or any harness) in the folder that will become its home and paste the block
|
|
from the [README's install section](../README.md) — the agent fetches
|
|
`BOOTSTRAP_FOR_AGENTS.md` from the `latest-stable` tag, installs the CLI,
|
|
initializes a local PGLite brain, wires MCP, and isn't done until
|
|
`gbrain bootstrap verify` exits 0. Full contract, security posture, and
|
|
uninstall: [docs/guides/bootstrap.md](guides/bootstrap.md).
|
|
|
|
The paths below are the manual equivalents and deep-dive detail. Pick one.
|
|
Mix later if needed.
|
|
|
|
## 1. Run with an agent platform
|
|
|
|
Already running [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)?
|
|
|
|
```bash
|
|
bun install -g github:garrytan/gbrain#latest-stable
|
|
gbrain init --pglite # 2 seconds; no server
|
|
gbrain skillpack scaffold --all # scaffolds every bundled skill (skills/manifest.json) into your agent workspace
|
|
gbrain doctor # green checks all the way down
|
|
```
|
|
|
|
Your agent now reads `skills/RESOLVER.md` once per request, routes intent to the right skill, executes. New entity mentions create new pages. Daily cron runs enrichment overnight.
|
|
|
|
Scaffolded skills are first-class files in your agent repo — edit freely. To pull upstream gbrain improvements later, `gbrain skillpack reference <name>` diffs your local copy vs the bundle. The legacy `skillpack install` managed-block model was retired in v0.36.0.0; if you're upgrading from an older release, run `gbrain skillpack migrate-fence` once to strip the legacy fence and keep your existing skill rows.
|
|
|
|
To upgrade later: `gbrain upgrade` runs schema migrations + post-upgrade prompts (chunker bumps, the v0.36.2.0 ZeroEntropy switch). Always TTY-only; non-TTY upgrades skip prompts with informational stderr lines.
|
|
|
|
## 2. CLI standalone
|
|
|
|
No agent platform, just shell + MCP-aware editor.
|
|
|
|
```bash
|
|
bun install -g github:garrytan/gbrain#latest-stable
|
|
gbrain init --pglite
|
|
```
|
|
|
|
> **If `bun install -g` hits a postinstall error** (Bun blocks postinstall hooks in some environments), the CLI prints a recovery hint pointing at [#218](https://github.com/garrytan/gbrain/issues/218). Run `gbrain doctor` to diagnose, then `gbrain apply-migrations --yes` manually. The deterministic fallback is `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && bun install && bun link`.
|
|
|
|
The init flow detects your repo size and suggests Supabase for brains > 1000 markdown files. To switch later:
|
|
|
|
```bash
|
|
gbrain migrate --to supabase # PGLite → Postgres
|
|
gbrain migrate --to pglite # Postgres → PGLite (rare)
|
|
```
|
|
|
|
For shared / large / multi-machine deployments (a team or company brain with multiple users hitting one server over HTTP MCP with OAuth scoping per user), follow the dedicated walkthrough: **[Tutorial: set up GBrain as your company brain](tutorials/company-brain.md)**.
|
|
|
|
API keys live in `~/.gbrain/config.json` (file plane) or env vars (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ZEROENTROPY_API_KEY`, `VOYAGE_API_KEY`, `ANTHROPIC_API_KEY`). Set via CLI:
|
|
|
|
```bash
|
|
gbrain config set zeroentropy_api_key sk-...
|
|
gbrain config set openrouter_api_key sk-or-...
|
|
gbrain config set anthropic_api_key sk-ant-...
|
|
```
|
|
|
|
Common follow-ups:
|
|
|
|
```bash
|
|
gbrain import ~/my-knowledge # bulk-import a markdown folder
|
|
gbrain sync --watch # live-sync a git repo (autopilot mode)
|
|
gbrain autopilot --install # background daemon for nightly enrichment
|
|
```
|
|
|
|
**Wire this same local brain into your coding agent** — zero server, zero token:
|
|
|
|
```bash
|
|
claude mcp add gbrain -- gbrain serve --surface verbs # Claude Code
|
|
codex mcp add gbrain -- gbrain serve --surface verbs # Codex
|
|
```
|
|
|
|
The agent spawns `gbrain serve` as a stdio subprocess against your local brain. `--surface verbs` gives the agent the five-verb memory protocol (`recall`, `remember`, `entity`, `synthesize`, `forget` — [MEMORY_VERBS v1](protocol/MEMORY_VERBS_v1.md)) instead of the full tool catalog; drop the flag (default `full`) for every operation. Full walkthrough (both this local path and connecting to a remote brain), plus the brain-first protocol to paste into `CLAUDE.md` / `AGENTS.md`: **[Give your coding agent a memory](tutorials/connect-coding-agent.md)**.
|
|
|
|
## 3. MCP server (any MCP client)
|
|
|
|
```bash
|
|
gbrain serve # stdio MCP (Claude Desktop / Code / Cursor)
|
|
gbrain serve --surface verbs # stdio MCP, just the 7 memory verbs (quickstart)
|
|
gbrain serve --http # HTTP MCP with OAuth 2.1 + admin dashboard
|
|
```
|
|
|
|
**Wire a coding agent to a remote brain in one command** (when you have an HTTP
|
|
server + a bearer token): `gbrain connect` prints a paste-ready setup block, or
|
|
`--install` runs it and smoke-tests the token.
|
|
|
|
```bash
|
|
gbrain auth create "claude-code"
|
|
gbrain connect https://your-host/mcp --token gbrain_xxx # Claude Code (default)
|
|
gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex # Codex (env-var bearer)
|
|
gbrain connect https://your-host/mcp --agent perplexity --oauth --register # Perplexity (OAuth)
|
|
```
|
|
|
|
Per-client setup guides live in [`docs/mcp/`](mcp/):
|
|
|
|
- [`docs/mcp/CLAUDE_CODE.md`](mcp/CLAUDE_CODE.md)
|
|
- [`docs/mcp/CODEX.md`](mcp/CODEX.md)
|
|
- [`docs/mcp/CLAUDE_DESKTOP.md`](mcp/CLAUDE_DESKTOP.md)
|
|
- [`docs/mcp/CHATGPT.md`](mcp/CHATGPT.md)
|
|
- [`docs/mcp/PERPLEXITY.md`](mcp/PERPLEXITY.md)
|
|
- [`docs/mcp/DEPLOY.md`](mcp/DEPLOY.md) — production deploy patterns
|
|
|
|
The HTTP server ships with an admin SPA at `/admin`, an SSE activity feed at `/admin/events`, DCR-style client registration, scope-gated `read`/`write`/`admin` access, and rate limiting.
|
|
|
|
## Thin-client mode
|
|
|
|
Connect to someone else's brain without running a local engine:
|
|
|
|
```bash
|
|
gbrain init --mcp-only # configures remote MCP, skips local DB
|
|
```
|
|
|
|
Useful for: team mounts, brain-as-a-service deployments, dev machines without disk space. Most local commands refuse with a paste-ready hint. See [`docs/architecture/topologies.md`](architecture/topologies.md).
|
|
|
|
## Verifying the install
|
|
|
|
```bash
|
|
gbrain bootstrap verify # the whole install contract; exits non-zero on failure
|
|
gbrain doctor --json # full health check
|
|
gbrain models # which AI models are configured for what
|
|
gbrain models doctor # 1-token probe per configured model
|
|
```
|
|
|
|
If anything's yellow, `gbrain doctor` names the fix command in the message. Most issues are missing API keys or stale schema (`gbrain upgrade --force-schema`). For the manual check-by-check runbook, see [docs/GBRAIN_VERIFY.md](GBRAIN_VERIFY.md).
|
|
|
|
## Troubleshooting
|
|
|
|
### PGLite crashes at startup (`RuntimeError: Aborted()`)
|
|
|
|
This crash (typically first seen after a macOS upgrade) is **not** a
|
|
macOS/WASM incompatibility — an unclean shutdown tore the data dir's
|
|
write-ahead log, and every subsequent open fails WAL replay. The short
|
|
version of the recovery ladder:
|
|
|
|
1. **Auto-repair (default):** run any gbrain command — gbrain detects the
|
|
abort, resets the WAL in place (data preserved, backup kept), and
|
|
continues. Then run `gbrain doctor`.
|
|
2. **Manual repair:** `gbrain pglite-repair --dry-run`, then
|
|
`gbrain pglite-repair --yes`.
|
|
3. **Rebuild:** `gbrain reinit-pglite`.
|
|
4. **Switch engines:** Supabase or native Homebrew Postgres + pgvector.
|
|
|
|
The full ladder — safety bounds, kill-switches, when WAL repair can't help,
|
|
and the Homebrew Postgres recipe — lives in
|
|
[docs/ENGINES.md](ENGINES.md#troubleshooting-startup-abort-runtimeerror-aborted).
|