diff --git a/AGENTS.md b/AGENTS.md index fdde87467..4a5482ebf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,11 +6,19 @@ start here. ## Install (5 min) -1. Clone: `git clone https://github.com/garrytan/gbrain ~/gbrain && cd ~/gbrain` -2. Install: `bun install` -3. Init the brain: `gbrain init` (defaults to PGLite, zero-config). For 1000+ files or +1. Install gbrain via Bun (the canonical path): + ```bash + curl -fsSL https://bun.sh/install | bash + export PATH="$HOME/.bun/bin:$PATH" + bun install -g github:garrytan/gbrain + ``` + If `bun install -g` aborts or `gbrain doctor` reports `schema_version: 0`, + the CLI prints a recovery hint pointing at [#218](https://github.com/garrytan/gbrain/issues/218). + Run `gbrain apply-migrations --yes` to recover, or fall back to the + deterministic install: `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && bun install && bun link`. +2. Init the brain: `gbrain init` (defaults to PGLite, zero-config). For 1000+ files or multi-machine sync, init suggests Postgres + pgvector via Supabase. -4. **STOP — ask the user about search mode.** `gbrain init` auto-applied a +3. **STOP — ask the user about search mode.** `gbrain init` auto-applied a default but printed a 9-cell cost matrix (mode × downstream model) preceded by `[AGENT]` markers. You MUST relay the matrix to the operator and confirm their choice before continuing. Cost spread between corners @@ -18,7 +26,7 @@ start here. [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) Step 3.5 for the exact ask-the-user protocol. Same banner fires on `gbrain post-upgrade` for existing users (search modes were added in v0.32.3). -5. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full 9-step flow +4. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full 9-step flow (API keys, identity, cron, verification). ## Read this order @@ -49,8 +57,9 @@ writing or reviewing an operation, consult `src/core/operations.ts` for the cont [`docs/mcp/DEPLOY.md`](./docs/mcp/DEPLOY.md). - **Debug:** [`docs/GBRAIN_VERIFY.md`](./docs/GBRAIN_VERIFY.md), [`docs/guides/minions-fix.md`](./docs/guides/minions-fix.md), `gbrain doctor --fix`. -- **Migrate:** [`docs/UPGRADING_DOWNSTREAM_AGENTS.md`](./docs/UPGRADING_DOWNSTREAM_AGENTS.md), - [`skills/migrations/`](./skills/migrations/), `gbrain apply-migrations`. +- **Migrate / upgrade:** `gbrain upgrade` (binary self-update + schema migrations + post-upgrade prompts), + [`docs/UPGRADING_DOWNSTREAM_AGENTS.md`](./docs/UPGRADING_DOWNSTREAM_AGENTS.md), + [`skills/migrations/`](./skills/migrations/), `gbrain apply-migrations --yes` (manual schema-only). - **Eval retrieval changes:** capture is off by default. To benchmark a retrieval change against real captured queries, set `GBRAIN_CONTRIBUTOR_MODE=1`, then `gbrain eval export --since 7d > base.ndjson` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cafd50e8..e98550680 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,7 +190,7 @@ See `docs/ENGINES.md` for the full guide. In short: 3. Run the test suite against your engine 4. Document in `docs/` -The SQLite engine is designed and ready for implementation. See `docs/SQLITE_ENGINE.md`. +The original SQLite engine plan was superseded by PGLite (embedded Postgres 17 via WASM), which uses the same SQL dialect as Postgres and eliminates the need for a separate FTS5/sqlite-vss translation layer. See [`docs/ENGINES.md`](docs/ENGINES.md) for the engine architecture and the rationale. ## CONTRIBUTOR_MODE — turn on the dev loop diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md index e77d5ddcf..8af59a02e 100644 --- a/INSTALL_FOR_AGENTS.md +++ b/INSTALL_FOR_AGENTS.md @@ -16,32 +16,43 @@ If you fetched this file by URL without cloning yet, the companion files live at ## Step 1: Install GBrain +Default path (Bun is required — gbrain is a Bun + TypeScript runtime): + ```bash -git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain curl -fsSL https://bun.sh/install | bash export PATH="$HOME/.bun/bin:$PATH" -bun install && bun link +bun install -g github:garrytan/gbrain ``` Verify: `gbrain --version` should print a version number. If `gbrain` is not found, restart the shell or add the PATH export to the shell profile. -> **Do NOT use `bun install -g github:garrytan/gbrain`.** Bun blocks the top-level -> postinstall hook on global installs, so schema migrations never run and the CLI -> aborts with `Aborted()` when it opens PGLite. Use the `git clone + bun link` path -> above. Tracking issue: [#218](https://github.com/garrytan/gbrain/issues/218). +> **If `bun install -g` aborts or `gbrain doctor` reports `schema_version: 0`** (Bun +> occasionally blocks the top-level postinstall hook on global installs, so schema +> migrations don't run automatically), the CLI prints a recovery hint pointing at +> [#218](https://github.com/garrytan/gbrain/issues/218). Run `gbrain apply-migrations --yes` +> to recover. If that doesn't work, fall back to the deterministic install path: +> +> ```bash +> git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain +> bun install && bun link +> ``` ## Step 2: API Keys -Ask the user for these: +Ask the user for these. gbrain defaults to the ZeroEntropy embedding + reranker stack +(as of v0.36.2.0); OpenAI/Voyage are still supported as fallbacks via `gbrain config +set embedding_model `. ```bash -export OPENAI_API_KEY=sk-... # required for vector search -export ANTHROPIC_API_KEY=sk-ant-... # optional, improves search quality +export ZEROENTROPY_API_KEY=ze-... # default embedding + reranker (v0.36.2.0+) +export OPENAI_API_KEY=sk-... # fallback for vector search; also used for chat models +export ANTHROPIC_API_KEY=sk-ant-... # optional, improves search quality via query expansion ``` -Save to shell profile or `.env`. Without OpenAI, keyword search still works. -Without Anthropic, search works but skips query expansion. +Save to shell profile or `.env`. Keys are picked up by `gbrain config set` automatically +or can be stored in `~/.gbrain/config.json` (file plane). Without any embedding provider, +keyword search still works. Without Anthropic, search works but skips query expansion. ## Step 3: Create the Brain @@ -152,8 +163,24 @@ and supports `--since YYYY-MM-DD` for incremental runs. ## Step 5: Load Skills -Read `~/gbrain/skills/RESOLVER.md`. This is the skill dispatcher. It tells you which -skill to read for any task. Save this to your memory permanently. +If you're running an agent platform (OpenClaw, Hermes, or any repo with a workspace), +scaffold the bundled skills into it: + +```bash +cd /path/to/agent/workspace +gbrain skillpack scaffold --all # copy 43 curated skills + RESOLVER.md +``` + +Scaffolded skills are first-class files in your repo. Edit freely; re-running scaffold +refuses to overwrite anything that exists. Use `gbrain skillpack reference ` to +diff against gbrain's bundle when you want upstream improvements. (The legacy +`gbrain skillpack install` managed-block model was retired in v0.36.0.0 — run +`gbrain skillpack migrate-fence` once if upgrading from an older release.) + +Whether you scaffolded or not, read `skills/RESOLVER.md` (in your workspace, or the +bundled copy at `~/gbrain/skills/RESOLVER.md` when running from the cloned repo). It's +the skill dispatcher — tells you which skill to read for any task. Save this to your +memory permanently. The three most important skills to adopt immediately: @@ -181,14 +208,17 @@ If skipped, minimal defaults are installed automatically. ## Step 7: Recurring Jobs -Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab): +Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab), or skip the +platform glue entirely with `gbrain autopilot --install` (built-in self-maintaining daemon): - **Live sync** (every 15 min): `gbrain sync --repo ~/brain && gbrain embed --stale` -- **Auto-update** (daily): `gbrain check-update --json` (tell user, never auto-install) -- **Dream cycle** (nightly): read `docs/guides/cron-schedule.md` for the full protocol. + — or `gbrain sync --watch` for a continuous loop. +- **Auto-update** (daily): `gbrain check-update --json` (tell user, never auto-install). +- **Dream cycle** (nightly): `gbrain dream` runs the 8-phase overnight maintenance cycle. Entity sweep, citation fixes, memory consolidation, plus (v0.23+) overnight conversation - synthesis and cross-session pattern detection. 8 phases, one cron-friendly command. This - is what makes the brain compound. Do not skip it. + synthesis and cross-session pattern detection. One cron-friendly command. This is what + makes the brain compound. Do not skip it. See `docs/guides/cron-schedule.md` for the + full protocol. - **Weekly**: `gbrain doctor --json && gbrain embed --stale` ## Step 8: Integrations @@ -206,9 +236,18 @@ actually works) is the most important. ## Upgrade +If you installed via `bun install -g`: + +```bash +gbrain upgrade # self-updates the binary, runs schema migrations, + # and prints post-upgrade notes for the version range +``` + +If you installed via `git clone + bun link`: + ```bash cd ~/gbrain && git pull origin master && bun install -gbrain init # apply schema migrations (idempotent) +gbrain apply-migrations --yes # apply schema migrations (idempotent) gbrain post-upgrade # show migration notes for the version range ``` diff --git a/README.md b/README.md index fcf7865d3..8acd88795 100644 --- a/README.md +++ b/README.md @@ -22,14 +22,14 @@ GBrain runs in three shapes. Pick the one that matches how you use AI agents tod ### Run with your agent platform -Already using [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)? GBrain installs as a skillpack into your agent's workspace. +Already using [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)? GBrain installs as a skillpack scaffold into your agent's workspace. ```bash gbrain init --pglite -gbrain skillpack install +gbrain skillpack scaffold --all # or: scaffold per skill ``` -That's it. Your agent picks up 43 skills (signal detection, brain-ops, ingest, enrich, citation-fixer, daily-task-manager, cron-scheduler, eval framework, and 35 more). Routing lives in `skills/RESOLVER.md` — the agent reads it once per request, picks the right skill, executes. +That's it. Your agent picks up 43 skills (signal detection, brain-ops, ingest, enrich, citation-fixer, daily-task-manager, cron-scheduler, eval framework, and 35 more). Routing lives in `skills/RESOLVER.md` — the agent reads it once per request, picks the right skill, executes. Scaffolded skills are first-class members of your agent repo — you own them, edit freely; `gbrain skillpack reference ` diffs your copy against gbrain's bundle when you want to pull upstream improvements. (The legacy `gbrain skillpack install` managed-block model was retired in v0.36.0.0; run `gbrain skillpack migrate-fence` once if you're upgrading from an older release.) ### CLI standalone @@ -94,7 +94,7 @@ The whole loop is described in [`docs/architecture/topologies.md`](docs/architec Data flowing into the brain. Each integration is a recipe — markdown + setup hints — that ships in `recipes/` and is discoverable via `gbrain integrations list`. -- **Voice**: Whisper or Groq voice-to-brain capture. Setup in [`docs/integrations/voice.md`](docs/integrations/voice.md). +- **Voice**: Phone calls create brain pages via Twilio + OpenAI Realtime (or DIY STT+LLM+TTS). Setup recipe: [`recipes/twilio-voice-brain.md`](recipes/twilio-voice-brain.md). - **Email + calendar**: webhook handlers that route to brain signals. [`docs/integrations/meeting-webhooks.md`](docs/integrations/meeting-webhooks.md). - **Embedding providers**: 14 recipes covering OpenAI (default fallback), Voyage, ZeroEntropy (default), Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy. Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md). - **Credential gateway**: vault-aware secret distribution. [`docs/integrations/credential-gateway.md`](docs/integrations/credential-gateway.md). diff --git a/docs/GBRAIN_V0.md b/docs/GBRAIN_V0.md index 9edc21c0d..73a581fc7 100644 --- a/docs/GBRAIN_V0.md +++ b/docs/GBRAIN_V0.md @@ -1,5 +1,12 @@ # GBrain v0: Postgres-Native Personal Knowledge Brain +> **Historical design doc.** This is the original v0 spec from before PGLite landed. Several +> forward-looking sections — most notably the SQLite engine plan — were superseded by +> PGLite (embedded Postgres via WASM), which uses the same SQL dialect as Postgres and +> eliminates the need for a separate FTS5/sqlite-vss translation layer. Kept here for +> historical context; see [`ENGINES.md`](ENGINES.md) for the current engine architecture and +> the [`CHANGELOG.md`](../CHANGELOG.md) for the actual implementation history. + ## What this is GBrain is a compiled intelligence system. Not a note-taking app. Not "chat with your notes." @@ -517,7 +524,7 @@ See `docs/ENGINES.md` for the pluggable engine architecture and future backend p - **Intelligence compiler.** Treat every fact as a first-class claim with source span, entity links, validity window, confidence, and contradiction status. "What changed, why, and what evidence would flip it again?" From Codex review. Builds on compiled truth model. - **Active skills via Trigger.dev.** Application-specific briefings, meeting prep. Belongs in OpenClaw, not generic brain infra. - **Multi-user access.** Supabase RLS + per-user API keys. v0 is single-user. -- **SQLite engine.** Community PRs welcome. See `docs/SQLITE_ENGINE.md`. +- **SQLite engine.** Superseded by PGLite (embedded Postgres 17 via WASM) before v1. See [`ENGINES.md`](ENGINES.md) for the current engine architecture. - **Docker Compose for self-hosted Postgres.** Community PRs welcome. - **Web UI.** Optional Vercel-hosted dashboard for browsing brain pages. @@ -531,7 +538,7 @@ This means: - A future DuckDB engine could implement analytics-heavy workloads - The CLI, MCP server, and library consumers never know which engine runs underneath -See `docs/ENGINES.md` for the full interface spec and `docs/SQLITE_ENGINE.md` for the SQLite implementation plan. +See [`ENGINES.md`](ENGINES.md) for the full interface spec. (The original SQLite engine plan was superseded by PGLite; the contract-first `BrainEngine` interface made that swap clean.) ## Review history diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 70277db7b..edb0c6ed0 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -8,14 +8,16 @@ Already running [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](htt ```bash bun install -g github:garrytan/gbrain -gbrain init --pglite # 2 seconds; no server -gbrain skillpack install # 43 skills into your agent workspace -gbrain doctor # green checks all the way down +gbrain init --pglite # 2 seconds; no server +gbrain skillpack scaffold --all # 43 skills scaffolded 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. -To upgrade later: `gbrain upgrade` runs schema migrations + post-upgrade prompts (chunker bumps, the v0.36.0.0 ZE switch). Always TTY-only; non-TTY upgrades skip prompts with informational stderr lines. +Scaffolded skills are first-class files in your agent repo — edit freely. To pull upstream gbrain improvements later, `gbrain skillpack reference ` 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 @@ -26,6 +28,8 @@ bun install -g github:garrytan/gbrain 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 diff --git a/llms-full.txt b/llms-full.txt index 16bc0aedd..0a27d3cde 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -19,11 +19,19 @@ start here. ## Install (5 min) -1. Clone: `git clone https://github.com/garrytan/gbrain ~/gbrain && cd ~/gbrain` -2. Install: `bun install` -3. Init the brain: `gbrain init` (defaults to PGLite, zero-config). For 1000+ files or +1. Install gbrain via Bun (the canonical path): + ```bash + curl -fsSL https://bun.sh/install | bash + export PATH="$HOME/.bun/bin:$PATH" + bun install -g github:garrytan/gbrain + ``` + If `bun install -g` aborts or `gbrain doctor` reports `schema_version: 0`, + the CLI prints a recovery hint pointing at [#218](https://github.com/garrytan/gbrain/issues/218). + Run `gbrain apply-migrations --yes` to recover, or fall back to the + deterministic install: `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && bun install && bun link`. +2. Init the brain: `gbrain init` (defaults to PGLite, zero-config). For 1000+ files or multi-machine sync, init suggests Postgres + pgvector via Supabase. -4. **STOP — ask the user about search mode.** `gbrain init` auto-applied a +3. **STOP — ask the user about search mode.** `gbrain init` auto-applied a default but printed a 9-cell cost matrix (mode × downstream model) preceded by `[AGENT]` markers. You MUST relay the matrix to the operator and confirm their choice before continuing. Cost spread between corners @@ -31,7 +39,7 @@ start here. [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) Step 3.5 for the exact ask-the-user protocol. Same banner fires on `gbrain post-upgrade` for existing users (search modes were added in v0.32.3). -5. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full 9-step flow +4. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full 9-step flow (API keys, identity, cron, verification). ## Read this order @@ -62,8 +70,9 @@ writing or reviewing an operation, consult `src/core/operations.ts` for the cont [`docs/mcp/DEPLOY.md`](./docs/mcp/DEPLOY.md). - **Debug:** [`docs/GBRAIN_VERIFY.md`](./docs/GBRAIN_VERIFY.md), [`docs/guides/minions-fix.md`](./docs/guides/minions-fix.md), `gbrain doctor --fix`. -- **Migrate:** [`docs/UPGRADING_DOWNSTREAM_AGENTS.md`](./docs/UPGRADING_DOWNSTREAM_AGENTS.md), - [`skills/migrations/`](./skills/migrations/), `gbrain apply-migrations`. +- **Migrate / upgrade:** `gbrain upgrade` (binary self-update + schema migrations + post-upgrade prompts), + [`docs/UPGRADING_DOWNSTREAM_AGENTS.md`](./docs/UPGRADING_DOWNSTREAM_AGENTS.md), + [`skills/migrations/`](./skills/migrations/), `gbrain apply-migrations --yes` (manual schema-only). - **Eval retrieval changes:** capture is off by default. To benchmark a retrieval change against real captured queries, set `GBRAIN_CONTRIBUTOR_MODE=1`, then `gbrain eval export --since 7d > base.ndjson` @@ -1909,32 +1918,43 @@ If you fetched this file by URL without cloning yet, the companion files live at ## Step 1: Install GBrain +Default path (Bun is required — gbrain is a Bun + TypeScript runtime): + ```bash -git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain curl -fsSL https://bun.sh/install | bash export PATH="$HOME/.bun/bin:$PATH" -bun install && bun link +bun install -g github:garrytan/gbrain ``` Verify: `gbrain --version` should print a version number. If `gbrain` is not found, restart the shell or add the PATH export to the shell profile. -> **Do NOT use `bun install -g github:garrytan/gbrain`.** Bun blocks the top-level -> postinstall hook on global installs, so schema migrations never run and the CLI -> aborts with `Aborted()` when it opens PGLite. Use the `git clone + bun link` path -> above. Tracking issue: [#218](https://github.com/garrytan/gbrain/issues/218). +> **If `bun install -g` aborts or `gbrain doctor` reports `schema_version: 0`** (Bun +> occasionally blocks the top-level postinstall hook on global installs, so schema +> migrations don't run automatically), the CLI prints a recovery hint pointing at +> [#218](https://github.com/garrytan/gbrain/issues/218). Run `gbrain apply-migrations --yes` +> to recover. If that doesn't work, fall back to the deterministic install path: +> +> ```bash +> git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain +> bun install && bun link +> ``` ## Step 2: API Keys -Ask the user for these: +Ask the user for these. gbrain defaults to the ZeroEntropy embedding + reranker stack +(as of v0.36.2.0); OpenAI/Voyage are still supported as fallbacks via `gbrain config +set embedding_model `. ```bash -export OPENAI_API_KEY=sk-... # required for vector search -export ANTHROPIC_API_KEY=sk-ant-... # optional, improves search quality +export ZEROENTROPY_API_KEY=ze-... # default embedding + reranker (v0.36.2.0+) +export OPENAI_API_KEY=sk-... # fallback for vector search; also used for chat models +export ANTHROPIC_API_KEY=sk-ant-... # optional, improves search quality via query expansion ``` -Save to shell profile or `.env`. Without OpenAI, keyword search still works. -Without Anthropic, search works but skips query expansion. +Save to shell profile or `.env`. Keys are picked up by `gbrain config set` automatically +or can be stored in `~/.gbrain/config.json` (file plane). Without any embedding provider, +keyword search still works. Without Anthropic, search works but skips query expansion. ## Step 3: Create the Brain @@ -2045,8 +2065,24 @@ and supports `--since YYYY-MM-DD` for incremental runs. ## Step 5: Load Skills -Read `~/gbrain/skills/RESOLVER.md`. This is the skill dispatcher. It tells you which -skill to read for any task. Save this to your memory permanently. +If you're running an agent platform (OpenClaw, Hermes, or any repo with a workspace), +scaffold the bundled skills into it: + +```bash +cd /path/to/agent/workspace +gbrain skillpack scaffold --all # copy 43 curated skills + RESOLVER.md +``` + +Scaffolded skills are first-class files in your repo. Edit freely; re-running scaffold +refuses to overwrite anything that exists. Use `gbrain skillpack reference ` to +diff against gbrain's bundle when you want upstream improvements. (The legacy +`gbrain skillpack install` managed-block model was retired in v0.36.0.0 — run +`gbrain skillpack migrate-fence` once if upgrading from an older release.) + +Whether you scaffolded or not, read `skills/RESOLVER.md` (in your workspace, or the +bundled copy at `~/gbrain/skills/RESOLVER.md` when running from the cloned repo). It's +the skill dispatcher — tells you which skill to read for any task. Save this to your +memory permanently. The three most important skills to adopt immediately: @@ -2074,14 +2110,17 @@ If skipped, minimal defaults are installed automatically. ## Step 7: Recurring Jobs -Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab): +Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab), or skip the +platform glue entirely with `gbrain autopilot --install` (built-in self-maintaining daemon): - **Live sync** (every 15 min): `gbrain sync --repo ~/brain && gbrain embed --stale` -- **Auto-update** (daily): `gbrain check-update --json` (tell user, never auto-install) -- **Dream cycle** (nightly): read `docs/guides/cron-schedule.md` for the full protocol. + — or `gbrain sync --watch` for a continuous loop. +- **Auto-update** (daily): `gbrain check-update --json` (tell user, never auto-install). +- **Dream cycle** (nightly): `gbrain dream` runs the 8-phase overnight maintenance cycle. Entity sweep, citation fixes, memory consolidation, plus (v0.23+) overnight conversation - synthesis and cross-session pattern detection. 8 phases, one cron-friendly command. This - is what makes the brain compound. Do not skip it. + synthesis and cross-session pattern detection. One cron-friendly command. This is what + makes the brain compound. Do not skip it. See `docs/guides/cron-schedule.md` for the + full protocol. - **Weekly**: `gbrain doctor --json && gbrain embed --stale` ## Step 8: Integrations @@ -2099,9 +2138,18 @@ actually works) is the most important. ## Upgrade +If you installed via `bun install -g`: + +```bash +gbrain upgrade # self-updates the binary, runs schema migrations, + # and prints post-upgrade notes for the version range +``` + +If you installed via `git clone + bun link`: + ```bash cd ~/gbrain && git pull origin master && bun install -gbrain init # apply schema migrations (idempotent) +gbrain apply-migrations --yes # apply schema migrations (idempotent) gbrain post-upgrade # show migration notes for the version range ``` @@ -2293,14 +2341,14 @@ GBrain runs in three shapes. Pick the one that matches how you use AI agents tod ### Run with your agent platform -Already using [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)? GBrain installs as a skillpack into your agent's workspace. +Already using [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)? GBrain installs as a skillpack scaffold into your agent's workspace. ```bash gbrain init --pglite -gbrain skillpack install +gbrain skillpack scaffold --all # or: scaffold per skill ``` -That's it. Your agent picks up 43 skills (signal detection, brain-ops, ingest, enrich, citation-fixer, daily-task-manager, cron-scheduler, eval framework, and 35 more). Routing lives in `skills/RESOLVER.md` — the agent reads it once per request, picks the right skill, executes. +That's it. Your agent picks up 43 skills (signal detection, brain-ops, ingest, enrich, citation-fixer, daily-task-manager, cron-scheduler, eval framework, and 35 more). Routing lives in `skills/RESOLVER.md` — the agent reads it once per request, picks the right skill, executes. Scaffolded skills are first-class members of your agent repo — you own them, edit freely; `gbrain skillpack reference ` diffs your copy against gbrain's bundle when you want to pull upstream improvements. (The legacy `gbrain skillpack install` managed-block model was retired in v0.36.0.0; run `gbrain skillpack migrate-fence` once if you're upgrading from an older release.) ### CLI standalone @@ -2365,7 +2413,7 @@ The whole loop is described in [`docs/architecture/topologies.md`](docs/architec Data flowing into the brain. Each integration is a recipe — markdown + setup hints — that ships in `recipes/` and is discoverable via `gbrain integrations list`. -- **Voice**: Whisper or Groq voice-to-brain capture. Setup in [`docs/integrations/voice.md`](docs/integrations/voice.md). +- **Voice**: Phone calls create brain pages via Twilio + OpenAI Realtime (or DIY STT+LLM+TTS). Setup recipe: [`recipes/twilio-voice-brain.md`](recipes/twilio-voice-brain.md). - **Email + calendar**: webhook handlers that route to brain signals. [`docs/integrations/meeting-webhooks.md`](docs/integrations/meeting-webhooks.md). - **Embedding providers**: 14 recipes covering OpenAI (default fallback), Voyage, ZeroEntropy (default), Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy. Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md). - **Credential gateway**: vault-aware secret distribution. [`docs/integrations/credential-gateway.md`](docs/integrations/credential-gateway.md).