---
version: 0.19.0
feature_pitch:
  headline: "Your code is now first-class in the brain."
  one_liner: "gbrain code-refs BrainEngine --json returns every usage site in <100ms."
  user_action_required: true
---

# v0.19.0 — Code Indexing

This release makes code a first-class citizen in the brain. Tree-sitter parses 29 languages into semantic chunks. `gbrain code-def` and `gbrain code-refs` let agents find symbol definitions and references without grep. Incremental chunking drops daily autopilot embedding cost by ~95%. The chunker is a strict superset of Chonkie's CodeChunker plus a structured header Chonkie lacks.

## Schema migrations applied automatically

- **v25 — `pages.page_kind`** — distinguishes markdown vs code pages at the DB level. Existing rows backfill to `'markdown'`. Postgres uses `ADD CONSTRAINT ... NOT VALID` + `VALIDATE CONSTRAINT` so large tables don't block.
- **v26 — `content_chunks` code metadata** — adds `language`, `symbol_name`, `symbol_type`, `start_line`, `end_line`. All nullable. Partial indexes on `symbol_name` and `language` for fast symbol lookup.

These run as part of `gbrain upgrade` → `gbrain apply-migrations`. No manual DDL needed.

## What the agent should do after upgrading

1. **Confirm migrations landed:**
   ```bash
   gbrain doctor
   ```
   Look for `schema_version: 26`. If lower, run `gbrain apply-migrations --yes`.

2. **Register a code source** if the user wants their code indexed:
   ```bash
   gbrain sources add <id> --path <path-to-repo>
   ```
   Pick a short `<id>` (e.g. `wiki`, `gbrain`, `yc-media`). Shorter is better — it's used in citation keys.

3. **Sync the code source:**
   ```bash
   gbrain sync --source <id>
   ```
   First sync may run tens of minutes depending on repo size. Each TypeScript function becomes a chunk with a structured header like `[TypeScript] src/core/sync.ts:380-415 function performFullSync`.

4. **Verify code-def and code-refs work:**
   ```bash
   gbrain code-def BrainEngine       # prints the file + line of the definition
   gbrain code-refs BrainEngine --json  # JSON array of every usage site
   ```
   If both return non-empty arrays, code indexing is working end-to-end.

5. **Observe incremental chunking.** Edit one function in a 20-function file, re-run `sync --source <id>`. Embedding cost should be ~5% of the first sync because unchanged chunks reuse their existing embeddings.

## Migration from your OpenClaw's `repos` (if you used it)

v0.19.0 deletes `~/.gbrain/config.json`'s `repos` array in favor of the `sources` table. The CLI surface is preserved as a deprecated alias: `gbrain repos add` still works, but routes into `runSources` with a one-line deprecation notice on stderr. Existing scripts keep working; prefer `gbrain sources` going forward.

If you had repos configured in `~/.gbrain/config.json`, re-register them:
```bash
gbrain sources add <name> --path <path>
```
Per-repo sync bookmarks live in the `sources` table now (not config.json).

## Flag in `pending-host-work.jsonl`

Per the v0.11.0 convention, the migration orchestrator writes an entry to `~/.gbrain/migrations/pending-host-work.jsonl` flagging the new CLI surfaces so headless agents can walk the TODOs:

```json
{"version": "0.19.0", "action": "register_code_source", "status": "pending"}
```

Agents that handle pending-host-work should offer the user a `gbrain sources add ...` prompt.

## When NOT to run the migration

Never. v0.19.0 is fully backward-compatible. Existing markdown-only brains see zero behavior change until the user adds a code source.
