---
version: 0.12.0
feature_pitch:
  headline: "Knowledge Graph wires itself — every page write extracts typed links automatically"
  description: |
    Every gbrain put_page now extracts entity references and creates typed links
    (attended, works_at, invested_in, founded, advises) with zero LLM calls.
    Hybrid search. Self-wiring graph. Backlink-boosted ranking. Ask "who works
    at Acme?" or "what did Bob invest in?" — answers vector search alone can't reach.
    Benchmarked end-to-end on a 240-page rich-prose corpus: Recall@5 83% → 95%,
    Precision@5 39% → 45%, +30 more correct answers in the agent's top-5.
    Graph-only F1: 86.6% vs grep's 57.8% (+28.8 pts).
  recipe: null
---

# v0.12.0 Migration: Knowledge Graph Auto-Wire

This release ships the v0.12.0 graph layer (originally tracked as PR #188 v0.10.3,
merged on top of v0.11.1 Minions). The migration is **automatic** — `gbrain
post-upgrade` calls `gbrain apply-migrations --yes` which invokes the v0.12.0
orchestrator at `src/commands/migrations/v0_12_0.ts`. You normally don't need to
do anything; this doc is the reference for what happens under the hood.

## What ships

- **Auto-link on every page write.** `put_page` extracts entity references from
  content and creates typed links (`attended`, `works_at`, `invested_in`,
  `founded`, `advises`, `mentions`) with deterministic regex inference. Zero LLM
  calls. Stale links reconciled on edits.
- **Schema migrations v8/v9/v10**: multi-type link constraint, timeline dedup
  index, drop legacy timeline search trigger.
- **`gbrain extract --source db`** for batch backfill on existing brains.
- **`gbrain graph-query <slug>`** for typed-edge relationship traversal with
  cycle prevention.
- **Backlink-boosted hybrid search**: well-connected entities rank higher
  (`score *= 1 + 0.05 * log(1 + n)`).
- **Graph health metrics in `gbrain health`**: `link_coverage`,
  `timeline_coverage`, `most_connected`.

## What the orchestrator does (automatic, idempotent)

The v0_12_0 migration runs these phases in order. All are idempotent — safe to
re-run. Failure in any one phase records `partial` status; re-running picks up
where it left off.

### Phase A — Schema
```bash
gbrain init --migrate-only
```
Applies migrations v8/v9/v10 if not already applied. Idempotent.

### Phase B — Config check
Reads `auto_link` config. If user set it to `false`, skips the backfill phases
(don't override user intent). Default is enabled; unset = enabled.

### Phase C — Backfill links
```bash
gbrain extract links --source db
```
Walks every page from the engine (mutation-immune snapshot iteration), extracts
entity refs from content, creates typed links. Idempotent via the
`(from_page_id, to_page_id, link_type)` UNIQUE constraint.

### Phase D — Backfill timeline
```bash
gbrain extract timeline --source db
```
Parses dated bullet entries from page content. Idempotent via the
`(page_id, date, summary)` UNIQUE index.

### Phase E — Verify
```bash
gbrain stats
```
Confirms `link_count` and `timeline_entry_count`. Expected outcomes:
- **Empty brain (0 pages)**: success, message "auto-link will wire entities as you write pages"
- **Pages but 0 links**: success, message "no entity refs in content"  (the brain
  works fine; just no extractable references)
- **Pages and links**: success, message "Graph layer wired up"
- **`auto_link` disabled**: success, message "auto_link_disabled_by_user"

### Phase F — Record
Appends to `~/.gbrain/migrations/completed.jsonl` so future `gbrain
apply-migrations` runs know this version is done.

## Manual recovery (if you ever need it)

If the orchestrator fails or you want to re-wire a brain manually:

```bash
gbrain init --migrate-only        # Phase A
gbrain extract links --source db  # Phase C
gbrain extract timeline --source db  # Phase D
gbrain stats                      # Phase E (look for link_count > 0)
gbrain graph-query <some-person-slug> --depth 2  # smoke test
```

## Available link types

After backfill, you can query the graph with:

```bash
gbrain graph-query people/<slug> --type attended --depth 2
gbrain graph-query companies/<slug> --type works_at --direction in
```

Types in this version: `attended`, `works_at`, `invested_in`, `founded`,
`advises`, `source`, `mentions`.

## Disable auto-link

If you don't want auto-link populating the graph on every write:

```bash
gbrain config set auto_link false
```

Re-enable with `gbrain config set auto_link true`.

## Branch-install recovery (very rare)

If you ran the `garrytan/link-timeline-extract` branch BEFORE this merge (so
your local PGLite db has migration v7 = `drop_timeline_search_trigger` from
the pre-renumber world), you're missing master's v5/v6/v7 (`minion_jobs_table`
etc.). Recovery: drop your PGLite db and re-init.

```bash
rm ~/.gbrain/brain.pglite
gbrain init --pglite
```

This applies all v2-v10 cleanly.
