diff --git a/README.md b/README.md index a28cd77b7..332b4f26a 100644 --- a/README.md +++ b/README.md @@ -13,95 +13,81 @@ GBrain is designed to be installed and operated by an AI agent. If you don't hav - **[OpenClaw](https://openclaw.ai)** — Deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/openclaw/alphaclaw) (one click, requires 8GB+ RAM instance) - **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — Deploy on [Railway using this template](https://github.com/praveen-ks-2001/hermes-agent-template) (one click) -## Start here: paste this into your agent +## Start here -Copy this block into OpenClaw or Hermes Agent. The agent will install GBrain, set up the brain schema, import your files, configure all integrations, and verify everything works. GBrain needs a persistent agent that can run cron jobs and background sync. +**https://github.com/garrytan/gbrain** — clone this repo into your agent's filesystem. It's home base for docs, skills, upgrades, and recipes. To upgrade later: `git pull origin main && bun install`. + +Copy this block into [OpenClaw](https://openclaw.ai), [Hermes](https://github.com/NousResearch/hermes-agent), or any persistent AI agent. The agent reads the docs, does the work, and asks you for API keys. ~30 minutes. ``` -GOAL: I want an opinionated AI agent setup that actually works. Get me -there. Install GBrain, set up the brain schema, import my files, -configure all integrations, and verify everything works. Do not skip -steps. Verify each step before proceeding. If a step fails, stop -and fix it. +INSTALL: -You don't need a server to start. gbrain init defaults to PGLite -(embedded Postgres 17.5 via WASM). No Supabase account, no Docker, -no connection strings. One command and you have a full Postgres brain -with pgvector, hybrid search, and all 37 operations. When your brain -outgrows local (1000+ files), gbrain migrate --to supabase moves -everything to managed Postgres in one shot. - -The knowledge model is markdown files in a git repo. Read -docs/GBRAIN_SKILLPACK.md for the full agent playbook and -docs/GBRAIN_RECOMMENDED_SCHEMA.md for the brain directory structure. - -STEP 1 — INSTALL - curl -fsSL https://bun.sh/install | bash && source ~/.bashrc - bun add github:garrytan/gbrain + git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain + curl -fsSL https://bun.sh/install | bash + source ~/.bashrc 2>/dev/null; source ~/.zshrc 2>/dev/null + export PATH="$HOME/.bun/bin:$PATH" + bun install && bun link Verify: gbrain --version -STEP 2 — DATABASE - Run: gbrain init - This creates a local PGLite brain (embedded Postgres, no server). - Brain ready in ~2 seconds. No accounts, no connection strings. - Verify: gbrain doctor --json (all checks pass) +API KEYS — ask the user for these. Embeddings and search need them: - For large brains (1000+ files) or remote access, use Supabase: - gbrain init --supabase - You can migrate anytime: gbrain migrate --to supabase + export OPENAI_API_KEY=sk-... # required for vector search + export ANTHROPIC_API_KEY=sk-ant-... # required for multi-query expansion + Save these in your environment permanently (shell profile or .env). -STEP 3 — SCHEMA - Read docs/GBRAIN_RECOMMENDED_SCHEMA.md — this is the brain's directory - structure. Set up the MECE directories (people/, companies/, deals/, - concepts/, etc.) with README.md resolvers in each. The schema tells - you exactly what goes where and how to resolve ambiguity. - The agent maintains this structure automatically after setup. +SET UP THE BRAIN: -STEP 4 — IMPORT - Find markdown: find ~/git ~/Documents ~/notes -maxdepth 3 -name "*.md" | head -30 - Tell user what you found. Import: gbrain import /path/ --no-embed - Verify: gbrain stats (page count > 0) + gbrain init # PGLite, no server needed + Verify: gbrain doctor --json # all checks pass -STEP 5 — SEARCH - Run: gbrain embed --stale (generates vector embeddings, ~1 min per 1000 pages) - Then: gbrain query "what are the key themes across these documents?" - Show the user the results. This is the magic moment. - Verify: results include semantic matches, not just keyword hits + The user's markdown files (notes, docs, brain repo) are SEPARATE from + this tool repo. Ask the user where their files are, or create a new + brain repo: mkdir -p ~/brain && cd ~/brain && git init -STEP 6 — GO LIVE - a. Read docs/GBRAIN_SKILLPACK.md — adopt brain-first lookup, entity - detection, and back-linking into your behavior immediately - b. Set up live sync: gbrain sync --repo /path/ && gbrain embed --stale - (see docs/guides/live-sync.md for cron/watch/webhook options) - c. Set up auto-update: gbrain check-update --json on a daily cron - (never auto-install — always ask the user first) - d. Run verification: read and execute docs/GBRAIN_VERIFY.md + Read ~/gbrain/docs/GBRAIN_RECOMMENDED_SCHEMA.md — set up the MECE + directory structure (people/, companies/, concepts/, etc.) inside the + user's brain repo, NOT inside ~/gbrain. -STEP 7 — INTEGRATIONS - Run: gbrain integrations list - For EVERY available recipe, set it up. Each recipe is a markdown file - that tells the agent exactly what credentials to ask for, how to - validate them, and how to wire the integration. The agent reads the - recipe, asks the user for API keys, and handles the rest. - Voice, email, calendar, Twitter — install them all. - Verify: gbrain integrations doctor (all health checks pass) + gbrain import ~/brain/ --no-embed # import markdown files + gbrain embed --stale # generate vector embeddings + gbrain query "key themes across these documents?" -DONE. Tell the user: "GBrain is live. You have [N] pages with hybrid -search. I now check the brain before answering questions. All available -integrations are configured." +GO LIVE — read and permanently adopt these docs from ~/gbrain/: + + docs/GBRAIN_SKILLPACK.md — the full agent playbook. Save to your + memory: brain-first lookup on every message, entity detection, + back-linking. This changes how you behave permanently. + + Set up recurring jobs using your platform's scheduler (crontab, + OpenClaw cron, Railway cron, or a process manager): + - 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 — entity sweep, citation fixes, memory consolidation. + This is what makes the brain compound. Do not skip it. + - Weekly: gbrain doctor --json && gbrain embed --stale + + docs/GBRAIN_VERIFY.md — run all 6 verification checks. #4 (live sync + actually works) is the most important. + +INTEGRATIONS — run gbrain integrations list. Read and set up EVERY + available recipe. Each recipe in ~/gbrain/recipes/ is a self-contained + installer: it tells you what credentials to ask for, how to validate + them, and what cron job to register. Ask the user for each API key. + Verify: gbrain integrations doctor + +UPGRADE: cd ~/gbrain && git pull origin main && bun install ``` ### Without an agent (standalone CLI) ```bash -bun add -g github:garrytan/gbrain +git clone https://github.com/garrytan/gbrain.git && cd gbrain && bun install && bun link gbrain init # local brain, ready in 2 seconds -gbrain import ~/git/brain/ # index your markdown +gbrain import ~/notes/ # index your markdown gbrain query "what themes show up across my notes?" ``` -Run `gbrain --help` for all commands. See [MCP setup](docs/mcp/DEPLOY.md) for connecting Claude Desktop, Perplexity, etc. - ## Getting Data In Once GBrain is installed, your agent needs data flowing in. GBrain ships integration recipes that your agent sets up for you. It reads the recipe, asks for API keys, validates each one, and runs a smoke test. [Markdown is code](docs/ethos/THIN_HARNESS_FAT_SKILLS.md)... the recipe IS the installer. @@ -376,20 +362,11 @@ PGLite (default) requires no external database. For production scale (7K+ pages, ## Upgrade -Upgrade depends on how you installed: - ```bash -# Installed via bun (standalone or library) -bun update gbrain - -# Installed via ClawHub -clawhub update gbrain - -# Compiled binary -# Download the latest from https://github.com/garrytan/gbrain/releases +cd ~/gbrain && git pull origin main && bun install ``` -After upgrading, run `gbrain init` again to apply any schema migrations (idempotent, safe to re-run). +Then run `gbrain init` to apply any schema migrations (idempotent, safe to re-run). ## Setup details