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

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

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

gbrain extract timeline --source db

Parses dated bullet entries from page content. Idempotent via the (page_id, date, summary) UNIQUE index.

Phase E — Verify

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:

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:

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:

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.

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

This applies all v2-v10 cleanly.