c0b621923b
* fix: splitBody and inferType for wiki-style markdown content - splitBody now requires explicit timeline sentinel (<!-- timeline -->, --- timeline ---, or --- directly before ## Timeline / ## History). A bare --- in body text is a markdown horizontal rule, not a separator. This fixes the 83% content truncation @knee5 reported on a 1,991-article wiki where 4,856 of 6,680 wikilinks were lost. - serializeMarkdown emits <!-- timeline --> sentinel for round-trip stability. - inferType extended with /writing/, /wiki/analysis/, /wiki/guides/, /wiki/hardware/, /wiki/architecture/, /wiki/concepts/. Path order is most-specific-first so projects/blog/writing/essay.md → writing, not project. - PageType union extended: writing, analysis, guide, hardware, architecture. Updates test/import-file.test.ts to use the new sentinel. Co-Authored-By: @knee5 (PR #187) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: JSONB double-encode bug on Postgres + parseEmbedding NaN scores Two related Postgres-string-typed-data bugs that PGLite hid: 1. JSONB double-encode (postgres-engine.ts:107,668,846 + files.ts:254): ${JSON.stringify(value)}::jsonb in postgres.js v3 stringified again on the wire, storing JSONB columns as quoted string literals. Every frontmatter->>'key' returned NULL on Postgres-backed brains; GIN indexes were inert. Switched to sql.json(value), which is the postgres.js-native JSONB encoder (Parameter with OID 3802). Affected columns: pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata. page_versions.frontmatter is downstream via INSERT...SELECT and propagates the fix. 2. pgvector embeddings returning as strings (utils.ts): getEmbeddingsByChunkIds returned "[0.1,0.2,...]" instead of Float32Array on Supabase, producing [NaN] cosine scores. Adds parseEmbedding() helper handling Float32Array, numeric arrays, and pgvector string format. Throws loud on malformed vectors (per Codex's no-silent-NaN requirement); returns null for non-vector strings (treated as "no embedding here"). rowToChunk delegates to parseEmbedding. E2E regression test at test/e2e/postgres-jsonb.test.ts asserts jsonb_typeof = 'object' AND col->>'k' returns expected scalar across all 5 affected columns — the test that should have caught the original bug. Runs in CI via the existing pgvector service. Co-Authored-By: @knee5 (PR #187 — JSONB triple-fix) Co-Authored-By: @leonardsellem (PR #175 — parseEmbedding) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat: extract wikilink syntax with ancestor-search slug resolution extractMarkdownLinks now handles [[page]] and [[page|Display Text]] alongside standard [text](page.md). For wiki KBs where authors omit leading ../ (thinking in wiki-root-relative terms), resolveSlug walks ancestor directories until it finds a matching slug. Without this, wikilinks under tech/wiki/analysis/ targeting [[../../finance/wiki/concepts/foo]] silently dangled when the correct relative depth was 3 × ../ instead of 2. Co-Authored-By: @knee5 (PR #187) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat: gbrain repair-jsonb + v0.12.1 migration + CI grep guard - New gbrain repair-jsonb command. Detects rows where jsonb_typeof(col) = 'string' and rewrites them via (col #>> '{}')::jsonb across 5 affected columns: pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter. Idempotent — re-running is a no-op. PGLite engines short-circuit cleanly (the bug never affected the parameterized encode path PGLite uses). --dry-run shows what would be repaired; --json for scripting. - New v0_12_1.ts migration orchestrator. Phases: schema → repair → verify. Modeled on v0_12_0 pattern, registered in migrations/index.ts. Runs automatically via gbrain upgrade / apply-migrations. - CI grep guard at scripts/check-jsonb-pattern.sh fails the build if anyone reintroduces the ${JSON.stringify(x)}::jsonb interpolation pattern. Wired into bun test via package.json. Best-effort static analysis (multi-line and helper-wrapped variants are caught by the E2E round-trip test instead). - Updates apply-migrations.test.ts expectations to account for the new v0.12.1 entry in the registry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.12.1) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: update project documentation for v0.12.1 - CLAUDE.md: document repair-jsonb command, v0_12_1 migration, splitBody sentinel contract, inferType wiki subtypes, CI grep guard, new test files (repair-jsonb, migrations-v0_12_1, markdown) - README.md: add gbrain repair-jsonb to ADMIN command reference - INSTALL_FOR_AGENTS.md: fix verification count (6 -> 7), add v0.12.1 upgrade guidance for Postgres brains - docs/GBRAIN_VERIFY.md: add check #8 for JSONB integrity on Postgres-backed brains - docs/UPGRADING_DOWNSTREAM_AGENTS.md: add v0.12.1 section with migration steps, splitBody contract, wiki subtype inference - skills/migrate/SKILL.md: document native wikilink extraction via gbrain extract links (v0.12.1+) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
155 lines
5.8 KiB
Markdown
155 lines
5.8 KiB
Markdown
# GBrain Installation Guide for AI Agents
|
|
|
|
Read this entire file, then follow the steps. Ask the user for API keys when needed.
|
|
Target: ~30 minutes to a fully working brain.
|
|
|
|
## Step 1: Install GBrain
|
|
|
|
```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
|
|
```
|
|
|
|
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.
|
|
|
|
## Step 2: API Keys
|
|
|
|
Ask the user for these:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY=sk-... # required for vector search
|
|
export ANTHROPIC_API_KEY=sk-ant-... # optional, improves search quality
|
|
```
|
|
|
|
Save to shell profile or `.env`. Without OpenAI, keyword search still works.
|
|
Without Anthropic, search works but skips query expansion.
|
|
|
|
## Step 3: Create the Brain
|
|
|
|
```bash
|
|
gbrain init # PGLite, no server needed
|
|
gbrain doctor --json # verify all checks pass
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
mkdir -p ~/brain && cd ~/brain && git init
|
|
```
|
|
|
|
Read `~/gbrain/docs/GBRAIN_RECOMMENDED_SCHEMA.md` and set up the MECE directory
|
|
structure (people/, companies/, concepts/, etc.) inside the user's brain repo,
|
|
NOT inside ~/gbrain.
|
|
|
|
## Step 4: Import and Index
|
|
|
|
```bash
|
|
gbrain import ~/brain/ --no-embed # import markdown files
|
|
gbrain embed --stale # generate vector embeddings
|
|
gbrain query "key themes across these documents?"
|
|
```
|
|
|
|
## Step 4.5: Wire the Knowledge Graph
|
|
|
|
If the user already had a brain repo (Step 3 imported existing markdown), backfill
|
|
the typed-link graph and structured timeline. This populates the `links` and
|
|
`timeline_entries` tables that future writes will maintain automatically.
|
|
|
|
```bash
|
|
gbrain extract links --source db --dry-run | head -20 # preview
|
|
gbrain extract links --source db # commit
|
|
gbrain extract timeline --source db # dated events
|
|
gbrain stats # verify links > 0
|
|
```
|
|
|
|
For brand-new empty brains, skip this step — auto-link populates the graph as the
|
|
agent writes pages going forward. There is nothing to backfill yet.
|
|
|
|
After this step:
|
|
- `gbrain graph-query <slug> --depth 2` works (relationship traversal)
|
|
- Search ranks well-connected entities higher (backlink boost)
|
|
- Every future `put_page` auto-creates typed links and reconciles stale ones
|
|
|
|
If a user has a very large brain (>10K pages), `extract --source db` is idempotent
|
|
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.
|
|
|
|
The three most important skills to adopt immediately:
|
|
|
|
1. **Signal detector** (`skills/signal-detector/SKILL.md`) — fire this on EVERY
|
|
inbound message. It captures ideas and entities in parallel. The brain compounds.
|
|
|
|
2. **Brain-ops** (`skills/brain-ops/SKILL.md`) — brain-first lookup on every response.
|
|
Check the brain before any external API call.
|
|
|
|
3. **Conventions** (`skills/conventions/quality.md`) — citation format, back-linking
|
|
iron law, source attribution. These are non-negotiable quality rules.
|
|
|
|
## Step 6: Identity (optional)
|
|
|
|
Run the soul-audit skill to customize the agent's identity:
|
|
|
|
```
|
|
Read skills/soul-audit/SKILL.md and follow it.
|
|
```
|
|
|
|
This generates SOUL.md (agent identity), USER.md (user profile), ACCESS_POLICY.md
|
|
(who sees what), and HEARTBEAT.md (operational cadence) from the user's answers.
|
|
|
|
If skipped, minimal defaults are installed automatically.
|
|
|
|
## Step 7: Recurring Jobs
|
|
|
|
Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab):
|
|
|
|
- **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`
|
|
|
|
## Step 8: Integrations
|
|
|
|
Run `gbrain integrations list`. Each recipe in `~/gbrain/recipes/` is a self-contained
|
|
installer. It tells you what credentials to ask for, how to validate, and what cron
|
|
to register. Ask the user which integrations they want (email, calendar, voice, Twitter).
|
|
|
|
Verify: `gbrain integrations doctor` (after at least one is configured)
|
|
|
|
## Step 9: Verify
|
|
|
|
Read `docs/GBRAIN_VERIFY.md` and run all 7 verification checks. Check #4 (live sync
|
|
actually works) is the most important.
|
|
|
|
## Upgrade
|
|
|
|
```bash
|
|
cd ~/gbrain && git pull origin main && bun install
|
|
gbrain init # apply schema migrations (idempotent)
|
|
gbrain post-upgrade # show migration notes for the version range
|
|
```
|
|
|
|
Then read `~/gbrain/skills/migrations/v<NEW_VERSION>.md` (and any intermediate
|
|
versions you skipped) and run any backfill or verification steps it lists. Skipping
|
|
this is how features ship in the binary but stay dormant in the user's brain.
|
|
|
|
For v0.12.0+ specifically: if your brain was created before v0.12.0, run
|
|
`gbrain extract links --source db && gbrain extract timeline --source db` to
|
|
backfill the new graph layer (see Step 4.5 above).
|
|
|
|
For v0.12.2+ specifically: if your brain is Postgres- or Supabase-backed and
|
|
predates v0.12.2, the `v0_12_2` migration runs `gbrain repair-jsonb`
|
|
automatically during `gbrain post-upgrade` to fix the double-encoded JSONB
|
|
columns. PGLite brains no-op. If wiki-style imports were truncated by the old
|
|
`splitBody` bug, run `gbrain sync --full` after upgrading to rebuild
|
|
`compiled_truth` from source markdown.
|