Brain health checks: back-link enforcement, citation audit, filing validation, stale info detection, orphan pages, and benchmarks. Use when asked to check brain health, run maintenance, or audit quality.
Periodic brain health checks and cleanup.
This skill guarantees:
Pages where compiled_truth is older than the latest timeline entry. The assessment hasn't been updated to reflect recent evidence.
Pages with zero inbound links. Nobody references them.
Links pointing to pages that don't exist.
Pages that mention entity names but don't have formal links.
If link_count is 0 or low relative to page_count, run batch extraction:
gbrain extract links --dir ~/brain
This scans all markdown files for entity references, See Also sections, and frontmatter fields, then creates typed links in the database.
If timeline_entry_count is 0, extract structured timeline from markdown:
gbrain extract timeline --dir ~/brain
Parses - **YYYY-MM-DD** | Source — Summary and ### YYYY-MM-DD — Title formats.
Note: extracted entries improve structured queries (gbrain timeline), not vector search.
Verify autopilot is running:
gbrain autopilot --status
If not running, install it:
gbrain autopilot --install --repo ~/brain
Autopilot runs sync, extract, and embed in a continuous loop with adaptive scheduling.
In v0.11.1+, autopilot dispatches each cycle as a single autopilot-cycle
Minion job and supervises the worker child — one install step gives you
sync + extract + embed + backlinks + durable job processing.
A v0.11.0 install where the migration skill never fired leaves Minions
partially set up: schema is applied, but ~/.gbrain/preferences.json
doesn't exist, autopilot runs inline, host manifests still reference
agentTurn. Repair:
# Check migration status
gbrain apply-migrations --list
# Apply pending migrations (idempotent; safe on healthy installs)
gbrain apply-migrations --yes
# If host-specific handlers are flagged in ~/.gbrain/migrations/pending-host-work.jsonl:
# walk them per skills/migrations/v0.11.0.md + docs/guides/plugin-handlers.md,
# ship handler registrations in the host repo, then re-run apply-migrations.
Full troubleshooting guide: docs/guides/minions-fix.md.
Check that the back-linking iron law is being followed:
- **YYYY-MM-DD** | Referenced in [page title](path) -- brief contextCheck for common misfiling patterns (see skills/_brain-filing-rules.md):
sources/ instead of the
appropriate directory (people/, companies/, concepts/, etc.)sources/ that reference specific
people, companies, or concepts -- these may be misfiledSpot-check pages for missing [Source: ...] citations:
Inconsistent tagging (e.g., "vc" vs "venture-capital", "ai" vs "artificial-intelligence").
The links and timeline_entries tables are the structured graph layer.
Populate them periodically or after major imports:
gbrain extract links --source db — backfill structured links by walking pages
from the engine. Reads [Name](people/slug) / [Name](companies/slug) references
and infers relationship types (attended, works_at, invested_in, founded,
advises, mentions, source). Idempotent. Use --source fs --dir <brain>
if you have a markdown checkout to walk instead.gbrain extract timeline --source db — backfill structured timeline entries.
Parses - **YYYY-MM-DD** | summary lines from page content. Idempotent (DB
UNIQUE constraint).gbrain extract all --source db — both in one run.gbrain graph-query <slug> --depth 2 — verify connectivity (use any well-known
entity slug as a probe).gbrain stats — verify link_count > 0 and timeline_entry_count > 0 after extraction.gbrain health — review link_coverage and timeline_coverage percentages
on entity pages (person/company). Below 50% means more extraction is needed.Available link types (use with gbrain graph-query --type):
attended, works_at, invested_in, founded, advises, mentions, source.
Going forward, every gbrain put call auto-creates and reconciles links via the
auto-link post-hook (default on; disable: gbrain config set auto_link false).
So link-extract is mostly a one-time backfill. timeline-extract should be re-run
after bulk imports or content edits that add new dated entries.
Chunks without embeddings, or chunks embedded with an old model.
nohup gbrain embed refresh > /tmp/gbrain-embed.log 2>&1 &tail -1 /tmp/gbrain-embed.logRun gbrain doctor --json and check the RLS status.
All tables should show RLS enabled. If not, run gbrain init again.
Check that the schema version is up to date. gbrain doctor --json reports
the current version vs expected. If behind, gbrain init runs migrations
automatically.
Check the integrity of stored files and redirect pointers:
gbrain files verify to check all DB records have valid datagbrain files status to see migration state (local, mirrored, redirected).redirect.yaml pointers that reference missing storage filesTimeline items older than 30 days with unresolved action items.
Periodically verify search quality hasn't regressed. Run a battery of test queries across difficulty tiers:
Compare results from gbrain search (keyword) vs gbrain query (hybrid).
Quality matters more than speed (2.5s right > 200ms wrong).
When to run benchmarks:
For production agents running on a schedule, integrate gbrain health checks into your operational heartbeat.
Run gbrain doctor --json and check for degradation. Report any failing checks
to the user. Key signals: connection health, schema version, RLS status, embedding
staleness.
Run gbrain embed --stale to refresh embeddings for pages that have changed since
their last embedding. For large brains (>5000 pages), run this with nohup:
nohup gbrain embed --stale > /tmp/gbrain-embed.log 2>&1 &
Verify sync is running: check gbrain stats and confirm last_sync is within
the last 24 hours. If sync has stopped, the brain is drifting from the repo.
Flag pages where compiled truth is >30 days old but the timeline has recent entries. This means new evidence exists that hasn't been synthesized. These pages need a compiled truth rewrite (see the maintain workflow above).
After maintenance runs, save a report:
This creates an audit trail for brain health over time.
The maintenance report follows this structure:
## Brain Health Report — YYYY-MM-DD
| Dimension | Issues Found | Fixed | Remaining |
|----------------------|-------------|-------|-----------|
| Stale pages | N | N | N |
| Orphan pages | N | N | N |
| Dead links | N | N | N |
| Missing cross-refs | N | N | N |
| Back-link violations | N | N | N |
| Citation gaps | N | N | N |
| Filing violations | N | N | N |
| Tag inconsistencies | N | N | N |
| Embedding staleness | N | N | N |
| Security (RLS) | N | N | N |
| Schema health | N | N | N |
| File storage | N | N | N |
| Open threads | N | N | N |
### Details
[Per-dimension breakdown with specific pages and actions taken]
### Benchmark Results (if run)
[Tier 1-4 query results with pass/fail]
### Outstanding Issues
[Items requiring user attention or confirmation]