Module doctor 

ai-memory doctor (Phase P7 / R7) — operator-visible health dashboard.

The doctor reads three v0.6.3.1 surfaces — Capabilities v2 (P1), data integrity (P2), and recall observability (P3) — plus the v0.6.3 stats / governance / subscription tables, and produces a human-readable health report with severity tagging. It also has a --json mode for CI usage and a --remote <url> mode that becomes the fleet doctor at T3+.

Exit codes:

• 0 — healthy (no warnings or critical findings).
• 1 — at least one warning (and --fail-on-warn was passed; without the flag, warnings still keep exit 0).
• 2 — at least one critical finding.

Severity rules (initial)

• Critical: dim_violations > 0; pending_actions older than 24h; sync skew > 600s; HNSW evictions > 0.
• Warning: silent-degrade flag from Capabilities v2 (recall_mode != “hybrid” on capable tiers); subscription delivery success < 95% over the lifetime of the subscription.
• Info: anything else worth reporting.

What is stubbed pending P1/P2/P3

• dim_violations (P2): pre-P2 schemas have no embedding_dim column. db::doctor_dim_violations returns Ok(None) and the doctor renders “not yet observed (pre-P2 schema)”.
• HNSW evictions (P3): the eviction counter has no SQL surface today. The doctor reports the value as 0 from a NOT_AVAILABLE-tagged section until P3 lands the in-memory counter.
• recall_mode / reranker_used distribution (P3): no rolling window has been wired yet. The doctor consults the Capabilities response for the active mode at this instant and reports it as the only data point.
• Sync mesh (T3+): we report last_pulled_at skew across sync_state rows when present, otherwise NOT_AVAILABLE.

Anti-goals (per spec)

• Do NOT add new monitoring infrastructure (no Prometheus, OTel exporters).
• Do NOT make doctor write to the DB. Read-only.
• Do NOT make doctor block the database. Indexed COUNT(*) queries only.

Structs

DoctorArgs

Args from the CLI clap struct. Kept separate so cli::doctor::run can be called directly from tests without going through clap.

HooksReportArgs

v0.7-G3 — Args for ai-memory doctor --hooks (standalone). Routes to run_hooks.

Report

The full doctor report.

ReportSection

One section of the report. facts is a list of human-readable (key, value) lines so the JSON output stays structured and the text output stays scannable.

TokensArgs

v0.6.4-004 — Args for ai-memory doctor --tokens. Routes to run_tokens instead of the regular health pass.

Enums

Severity

Severity bucket attached to every doctor finding.

Functions

run

Entry point. Returns the process exit code as a i32 (0/1/2). The caller (daemon_runtime) must std::process::exit(code) after the WAL checkpoint has been skipped (doctor never writes).

run_hooks

v0.7-G3 — ai-memory doctor --hooks entry point. Renders the loaded hooks.toml shape plus zeroed metric placeholders.

run_tokens

v0.6.4-004 — token-cost report.