/brain-health — Knowledge Graph Health Report

Rubric-scored knowledge graph health report — checks theme attention, graph density, hub health, co-occurrence alignment, dedup pressure, stale queue, synthesis health, entity landscape, and cross-metric patterns via 12 MCP tool calls. Rubric-scored with cross-run memory (findings tracking, auto-downgrade, BASELINE.md overrides). Persists to research/brain-health/YYYY-MM-DD-brain-health.md. Scope: knowledge graph structure and quality. Calls MCP tools (analyze, thought_stats, dedup_review, review_stale, list_thoughts, list_entities, serendipity_digest) to assess graph health. NOT for: pipeline capture health — that's /pulse. NOT for: TRACKER.md document quality — that's /tracker-health. NOT for: deep research on recent thoughts — that's /discover. Use when the user says "brain health", "graph health", "how's my knowledge graph", "attention map", "theme check", or invokes /brain-health. Accepts optional days argument (default 7).

Items 13-14 have no dependencies on MCP tool calls — run them in parallel with everything else.

Record all results. These feed into every subsequent phase.

Deriving the prior period:

thought_stats(days=N*2) returns counts for the full 2N-day window. To get the prior period (the N days before the current period):

• prior_total = double_window_total - current_period_total
• Apply per-theme: prior_theme_X = double_theme_X - current_theme_X
• Delta percentage: ((current - prior) / prior) * 100 (use "N/A" if prior is 0)

Theme velocity note: Theme velocity comes directly from analyze(type="themes") — it's EMA-smoothed by the weekly dream-themes batch. Do not recompute velocity from thought_stats deltas.

Phase 2: Assemble Report Sections

Build each section from the Phase 1 data. Apply rubrics to assign status indicators.

Status indicators:

• [GREEN] — healthy, no action needed
• [YELLOW] — warning, worth monitoring
• [RED] — critical, action needed

Pre-Section: Findings Diff & Classification

Before assembling sections, prepare the cross-run context:

1. Parse prior_findings (from Phase 1, step 12) into a map keyed by key.
2. Parse BASELINE.md suppress and force lists (from Phase 1, step 13).
3. Initialize an empty current_findings list and an empty resolved_findings list.

As you assemble each section below, generate finding entries for every RED or YELLOW condition. Each finding gets:

• key: deterministic identifier (see Finding Key Reference below)
• section: which section produced it
• severity: RED or YELLOW
• value: the metric value as a string
• summary: human-readable one-liner

After generating each finding, classify it by diffing against prior_findings:

Value stability check: For stable findings, compare values numerically where possible. If the value changed by more than 5% relative, reset to label=new, occurrences=1 instead. This prevents a worsening metric from hiding behind a "stable" label.

After all sections are assembled, compute resolved_findings: any key in prior_findings that is not in current_findings. Record each with its prior severity.

Apply BASELINE overrides (in this order):

1. For each finding whose key is in the force list: mark as forced — it stays in Suggested Actions regardless of occurrences.
2. For each finding whose key is in the suppress list AND NOT in force: mark as known — it goes to Known Conditions regardless of occurrences.
3. For remaining findings: if occurrences >= 3, mark as known (auto-downgraded). Otherwise, it stays active.

Partition findings:

• Active findings (label is new, stable with occurrences < 3, worsened, improved, or forced) → feed into Suggested Actions.
• Known findings (label is known via suppress or auto-downgrade) → feed into Known Conditions section.

Finding Key Reference:

Section 1: Theme Attention Map

Data source: analyze(type="themes") result + thought_stats(days=N) derived delta.

Format as a table:

One row per theme from the themes data. Sort by thought_count descending. Velocity is thoughts/week (EMA-smoothed by dream batch). Period delta is derived from thought_stats current vs prior period for the by_theme breakdown.

Overall section rubric:

• [GREEN]: All themes are active, emerging, or mature
• [YELLOW]: 1-2 themes are declining
• [RED]: 3+ themes declining OR any theme dormant

Finding annotations: For each declining theme, generate a finding with key theme-declining-{name}. For each dormant theme, generate a finding with key theme-dormant-{name}. For each emerging theme, generate an informational finding (YELLOW) with key theme-emerging-{name} — this is a positive signal, not a warning; annotate it as "(informational)".

Annotate each finding in the output with its label: (new), (stable, Nth run), (worsened), (improved), or (known).

Section 2: Theme Drift

Data source: analyze(type="themes") — centroid_drift field.

List any themes with centroid_drift > 0, sorted descending. Show the drift value and a brief interpretation:

• < 0.03: stable meaning
• 0.03-0.05: meaning shifting

• 0.05: significant drift — theme may be splitting

Bootstrap gate: If the latest_snapshot_date field shows only one snapshot exists (all themes have the same date and it matches the first backfill), output: "Insufficient snapshots for drift analysis — drift requires 2+ weekly dream batch runs." Score as [GREEN] and skip finding generation.

Rubric (when sufficient data):

• [GREEN]: All centroid_drift < 0.03
• [YELLOW]: Any drift 0.03-0.05
• [RED]: Any drift > 0.05

Finding key: theme-drift-{name} for each theme exceeding 0.03.

Section 3: Graph Density

Data source: analyze(type="density") result.

Format as a table:

One row per threshold from the density data (typically 0.70, 0.75, 0.80, 0.85).

Compute orphan ratio from the 0.70 threshold row: orphan_ratio = zero_link_count / (zero_link_count + non_zero_count)

If orphan ratio is not directly available, compute from total thoughts (from thought_stats) minus non-orphan count.

Rubric:

• [GREEN]: Orphan ratio <15% at 0.70 AND avg connections >= 2.0 at 0.70
• [YELLOW]: Orphans 15-30% OR avg connections 1.0-2.0
• [RED]: Orphans >30% OR avg connections < 1.0

Finding keys:

• graph-orphan-ratio if orphan ratio >= 15%
• graph-sparse if avg connections < 2.0 at 0.70

Section 4: Hub Health

Data source: analyze(type="hubs", min_connections=5) result.

Count total hubs returned. Show the top 5 hubs with:

Rubric:

• [GREEN]: 5+ hubs
• [YELLOW]: 2-4 hubs
• [RED]: 0-1 hubs

Finding key: graph-low-hubs if hub count < 5.

Section 5: Co-occurrence Alignment

Data source: analyze(type="co_occurrence") result.

Report:

• Total co-occurrence edges
• Recent retrieval sessions (count in last 7 days)
• Decay stats (if available): edges decayed, edges removed
• Top 3 co-occurring pairs by weight (if any)

Bootstrap gate: If total edges < 20, output: "Co-occurrence layer is bootstrapping ([N] edges). Shipped 2026-04-06 — building up from retrieval sessions." Score as [GREEN] and skip finding generation.

Rubric (when sufficient data):

• [GREEN]: Edges exist and sessions recorded in last 7 days
• [YELLOW]: Low edge count (<10 after bootstrap) OR no sessions in 3+ days
• [RED]: Zero edges (after bootstrap period) OR no sessions in 7+ days

Finding keys:

• cooccurrence-no-edges if zero edges after bootstrap
• cooccurrence-stale-sessions if no sessions in 3+ days

Section 6: Dedup Pressure

Data source: dedup_review(limit=30) result.

Format the zone histogram:

Below the histogram, show the top 3 candidate pairs from the 0.95+ zone (if any) with similarity score and content previews.

Rubric:

• [GREEN]: 0.95+ zone has < 3 pairs
• [YELLOW]: 0.95+ zone has 3-10 pairs
• [RED]: 0.95+ zone has > 10 pairs (auto-merge may be broken)

Finding keys:

• dedup-zone-95plus if 0.95+ zone >= 3 pairs
• dedup-high-pressure if total candidates across all zones > 20

Section 7: Stale Queue

Data source: review_stale(action="list") result.

Report:

• Count of pending Tier 3 thoughts awaiting review
• Top 3 candidates with content preview and staleness score

Rubric:

• [GREEN]: 0 pending
• [YELLOW]: 1-5 pending
• [RED]: 6+ pending

Finding key: stale-queue-backlog if pending > 0.

Section 8: Synthesis Health

Data source: list_thoughts(type="synthesis", days=N*2, min_quality=0) result

• thought_stats(days=N) and thought_stats(days=N*2) type breakdowns.

Derive counts from thought_stats by_type field:

• current_syntheses = by_type.synthesis from thought_stats(days=N) (0 if absent)
• double_syntheses = by_type.synthesis from thought_stats(days=N*2) (0 if absent)
• prior_syntheses = double_syntheses - current_syntheses

From list_thoughts result, compute:

• avg_coverage = mean of metadata.coverage_score across returned thoughts
• avg_cluster_size = mean of metadata.cluster_size across returned thoughts
• total_syntheses = count of returned thoughts (all syntheses in 2N window)

Format as a table:

If syntheses exist in the period, show the top 3 most recent with:

Bootstrap gate: If total_syntheses = 0, output: "Dream Phase C has not produced insights yet — first results expected after the next weekly run (Sunday 09:00 UTC)." Score as [GREEN] and skip finding generation.

Rubric (when data exists):

• [GREEN]: current_syntheses >= 1 AND avg_coverage >= 0.75
• [YELLOW]: current_syntheses = 0 (no new clusters processed this period) OR avg_coverage between 0.70 and 0.75
• [RED]: current_syntheses = 0 AND prior_syntheses = 0 (no synthesis output for 2× the reporting period — Phase C may be broken) OR avg_coverage < 0.70

Finding keys:

• synthesis-inactive if current_syntheses = 0 but total_syntheses > 0 (Phase C didn't produce output this period)
• synthesis-stale if current_syntheses = 0 AND prior_syntheses = 0 AND total_syntheses > 0 (no output for 2× period — RED)
• synthesis-low-coverage if avg_coverage < 0.75

Section 9: Cross-Metric Patterns

Detect patterns only when conditions are met. Only include patterns where the detection condition fires — omit the rest entirely.

Finding keys: pattern-attention-narrowing, pattern-capture-connection-gap, pattern-velocity-quality-divergence, pattern-stale-theme-accumulation, pattern-entity-concentration-{name}

For each detected pattern, generate a YELLOW finding. Annotate with cross-run label as usual.

Section 10: Entity Landscape

Data source: list_entities(entity_type="tool") + list_entities(entity_type="person") results.

Format as two tables:

Top Tools:

Top People:

Show top 5 of each. Compute % of total from thought_stats total count. Flag any entity exceeding 15% (feeds into cross-metric pattern detection).

This section is informational — no rubric scoring.

Serendipity Pick

Data source: serendipity_digest() result.

Show 1-2 forgotten high-quality thoughts with:

• Content preview (first 100 chars)
• Created date
• Theme
• Quality score

No rubric — this is a "you might want to revisit" nudge at the end of the report. Frame it as: "Forgotten gems — high-quality thoughts that haven't been accessed recently."

Known Conditions

List all findings classified as known (via BASELINE.md suppress or auto-downgrade at 3+ occurrences). For each:

• Finding key and summary
• Reason (from BASELINE.md if suppressed, or "auto-downgraded, stable N runs" if auto)
• Last severity

Only include this section if known findings exist.

Suggested Actions

Generate concrete, data-backed actions from active RED and YELLOW findings only. Findings classified as Known Conditions are excluded — they appear in the Known Conditions section instead.

Action generation rules:

For each RED rubric in Sections 1-8, generate a specific action:

• Theme attention RED → "Review dormant themes — [themes] have zero velocity for [N] weeks"
• Theme drift RED → "Investigate [theme] drift ([X]) — meaning may be splitting, consider new theme"
• Graph density RED → "Run connection backfill — [N] orphaned thoughts ([X]%)"
• Hub health RED → "No cluster nuclei — graph may need denser connection thresholds"
• Co-occurrence RED → "Check retrieval session logging — zero co-occurrence edges"
• Dedup RED → "Verify Dream Phase A is running — [N] pairs in 0.95+ zone"
• Stale queue RED → "Review [N] stale candidates via review_stale(action='list')"
• Synthesis RED (stale) → "Check Dream Phase C workflow — no synthesis output for [2N] days. Verify run-dream-synthesis GitHub Action is running (Sunday 09:00 UTC)"
• Synthesis RED (low coverage) → "Synthesis quality degraded — avg coverage [X] below 0.70. Review source cluster quality or probe evaluation prompts"

For each YELLOW rubric, generate a monitoring note:

• "Monitor [theme] — declining, velocity [X]"
• "Watch orphan ratio — [X]% at 0.70 threshold"
• "Review [N] dedup candidates in 0.95+ zone"
• "Dream Phase C produced no syntheses this period — may be no eligible clusters, or schedule hasn't fired yet"

For each detected cross-metric pattern, generate a follow-up:

• Attention narrowing → "Consider diversifying captures beyond [theme]"
• Entity concentration → "Review [entity] dominance — [X]% may indicate capture bias"

Always include if applicable:

• If dedup_review 0.95+ zone > 0: "Review [N] dedup candidates in 0.95+ zone via dedup_review()"
• If stale queue > 0: "Process [N] stale review candidates via review_stale()"

Phase 3: Assemble and Persist Report

Terminal Output

Render the full report inline to the user with all sections. Use markdown formatting — the terminal renders it.

Start with a one-line summary: Brain Health: [X] GREEN, [Y] YELLOW, [Z] RED — [top finding summary or "all clear"]

If resolved_findings is non-empty, add immediately after the summary:

"Resolved since last brain-health: {key1} (was {severity1}), {key2} (was {severity2}), ..."

Omit if nothing resolved.

End with: "Report saved to research/brain-health/[TODAY]-brain-health.md."

File Output

Write the report to research/brain-health/YYYY-MM-DD-brain-health.md using the Write tool. If a file already exists for today, overwrite it (latest run wins).

File structure:

Frontmatter:

---