Health Diagnostics

Agent-First Health Reports

Loka's health endpoint produces structured text designed for AI agent consumption. Instead of dashboards with charts, it outputs context-rich text that an agent can read, reason about, and act on:

$ loka health --data my_graph.sdb

Overall: HEALTHY

HNSW Index: :hasEmbedding
  Status: HEALTHY
  Vectors: 435 (0 deleted, 0.0% tombstone ratio)
  Layers: 3 (L0: 435, L1: 28, L2: 3)
  Connectivity: avg 12.4, min 4, max 16
  Entry points: 3

Pseudo-Tables: 2 discovered
  Coverage: 78% of triples in pseudo-tables
  Cliff steepness: 8.2 (good schema consistency)

Storage:
  Triples: 16,234
  Terms: 4,891
  Predicates: 47

What Gets Measured

Category	Metrics	Why It Matters
HNSW Health	Tombstone ratio, layer distribution, avg/min/max connectivity, entry point diversity	High tombstone ratio degrades search quality. Low connectivity indicates graph fragmentation.
Pseudo-Table Coverage	Coverage ratio, cliff steepness, segment count, tail properties	Low coverage means most queries can't use columnar acceleration. Shallow cliff means messy data.
Storage	Triple count, term dictionary size, unique predicates	Baseline metrics for capacity planning and anomaly detection.

Actionable Recommendations

The health report suggests specific actions based on thresholds:

Tombstone ratio > 30%: "HNSW rebuild recommended" — too many deleted nodes degrading search paths
Cliff steepness < 3: "Data schema is inconsistent" — pseudo-tables provide diminished benefit
Entry point diversity low: "Consider adding more entry points" — searches may get stuck in local optima

An AI agent can read these recommendations and execute loka health --rebuild-hnsw without human intervention.

Three Severity Levels

Level	Meaning	Action
HEALTHY	All metrics within normal range	No action needed
WARNING	Some metrics approaching thresholds	Schedule maintenance during next low-usage period
CRITICAL	Metrics exceed thresholds, performance impacted	Immediate maintenance recommended