gbrain-openclaw: Instructions file for Claude Code

GBrain for OpenClaw

Personal knowledge brain built for OpenClaw — SQLite + FTS5 + vector embeddings, MCP-native.

Project structure

src/cli.ts              # main entrypoint, command dispatcher
src/commands/           # one file per CLI command
src/core/               # db.ts, fts.ts, embeddings.ts, markdown.ts, links.ts
src/mcp/server.ts       # MCP server (stdio transport) — primary OpenClaw integration point
skills/*/SKILL.md       # fat skill files — deploy to ~/.openclaw/workspace/skills/
hooks/*/                # OpenClaw hooks (HOOK.md + hook.ts)
bin/gbrain              # compiled binary (bun build --compile)
test/core.test.ts       # tests

Key conventions

• DB: bun:sqlite, default ~/.openclaw/brain.db, overridable via GBRAIN_DB env or --db flag
• Slugs: people/jane-doe, companies/acme-corp (type-prefix + hyphenated name)
• Page architecture: compiled_truth (above ---, rewritten) + timeline (below ---, append-only)
• Embeddings: Float32Array blobs, pure JS cosine similarity, no native extensions
• Embeddings need OPENAI_API_KEY — gracefully degrade if absent

Dev workflow

bun run src/cli.ts <command>   # run in dev mode
bun test                       # run tests
bun build --compile --outfile bin/gbrain src/cli.ts  # compile binary

OpenClaw integration

• MCP server: gbrain serve --db ~/.openclaw/brain.db — register in ~/.openclaw/openclaw.json under mcp.servers
• Skills: copy skills/*/ to ~/.openclaw/workspace/skills/
• Hook: see hooks/gbrain-ingest-session/HOOK.md for session auto-ingest setup

Skills

Read skills/ingest/SKILL.md before ingesting any content. Read skills/query/SKILL.md before answering questions from the brain. Read skills/maintain/SKILL.md before running maintenance. Read skills/enrich/SKILL.md before enriching pages from external APIs. Read skills/briefing/SKILL.md before compiling a briefing.

---

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Use bunx <package> <command> instead of npx <package> <command>
• Bun automatically loads .env, so don't use dotenv.