docs: fix drift in Health Monitoring

[jack-arturo]

Docs-accuracy audit of /docs/operations/health (never previously reviewed). This page had more provable drift than the 5-fix cap allows; the top 5 by severity are fixed, the rest are listed under Follow-ups.

Claim	Current state	Fix	Evidence
HEALTH_MONITOR_AUTO_RECOVER documented as an env var in 3 places (Railway service env block, "Enable via environment variable", Configuration Reference table, plus a troubleshooting step)	health_monitor.py never reads it. Auto-recovery comes only from --auto-recover, threaded through HealthMonitor(auto_recover=args.auto_recover). Setting the env var does nothing.	Removed the env var; documented --auto-recover as the only switch, including in the troubleshooting step	automem@8ff266e:scripts/health_monitor.py#L59, automem@8ff266e:scripts/health_monitor.py#L404
HEALTH_MONITOR_CHECK_INTERVAL documented as an env var (default 300) in 2 places	Also never read. The interval is --interval, argparse default 300.	Removed from both the Railway env block and the Configuration Reference; documented the flag	automem@8ff266e:scripts/health_monitor.py#L374
Webhook payload documented as {alert_type, drift_percent, falkordb_count, qdrant_count, timestamp, service_url}	send_alert() posts {level, title, message, details, timestamp, system}. None of the five documented keys other than timestamp exist; drift values live under details.	Replaced the example with a real payload (the manual-recovery critical alert) and documented the level values	automem@8ff266e:scripts/health_monitor.py#L173
/startup-recall: "Returns matching memories up to the configured limit", "Falls back to recent memories if tag-filtered results are insufficient", example jq '.memories | length'	Two fixed queries with hardcoded LIMIT 10 and LIMIT 5. No fallback exists. Response keys are critical_lessons and system_rules — there is no memories key, so the documented command prints null.	Documented both result sets and their hard limits, removed the fallback claim, fixed the jq path	automem@8ff266e:automem/api/recall.py#L2690, automem@8ff266e:automem/api/recall.py#L2728
/analyze: "executes 7 independent Cypher queries", each "wrapped in a try-except block"; components listed as total count / type distribution / entity frequency (top 20) / confidence in 0.1 buckets / activity by hour / tag frequency / relationship counts. Use-case table cites memories_by_type, top_entities, top_tags, relationships[...]	6 queries under one shared try/except — a failure returns HTTP 500, not a partial result. Real keys: memory_types, patterns, preferences, temporal_insights, entity_frequency (top 50, read from metadata entities/keywords/topics), confidence_distribution (low/medium/high, not 0.1 buckets). No total-count, tag-frequency, or relationship component exists.	Rewrote the component list, the Analytics Query Flow sequence diagram, and the use-case field names; pointed relationship counts at GET /graph/stats	automem@8ff266e:automem/api/recall.py#L2742, automem@8ff266e:automem/api/recall.py#L2865, automem@8ff266e:automem/api/graph.py#L438

Also surfaced the real-but-undocumented HEALTH_MONITOR_EMAIL (accepted, logged, but email sending is a TODO) and noted that --drift-threshold / --critical-threshold / --webhook override their env vars.

Verified correct and untouched: the /health response example and all field/status tables, vector_dimensions semantics, the 200/500 response-code table, the railway.json healthcheck block, HEALTH_MONITOR_DRIFT_THRESHOLD=5 and HEALTH_MONITOR_CRITICAL_THRESHOLD=50, the drift formula, and scripts/recover_from_qdrant.py.

This page has no source-note permalinks (its :::note is a provenance note about two merged source documents), so there was nothing to repin.

Verified against: automem@8ff266e62e65cb2e81719a765b05f64a2361a127

Questions

• The "Understanding Drift Thresholds" flowchart splits drift into < 1% / 1-5% / 5-50% / > 50%, but the Drift Thresholds table directly above it says Normal is < 5% and Warning is 5-50%. The code has exactly two thresholds (5 and 50), so the flowchart's 1% boundary has no basis — but I could not tell whether the sub-1% band is a deliberate operator heuristic, so I left it alone.
• Cost Analysis lists three configurations at "~$15/month" with different trade-offs. Not code-verifiable; untouched.

Unverified

• The GitHub Actions monitoring option references .github/workflows/backup.yml in the architecture diagram. I did not confirm what that workflow schedules, so the "Scheduled Checks" label is left as-is.

Follow-ups

Real drift found but beyond the 5-fix cap:

• enrichment.queue_depth is defined as "Total jobs in queue (pending + inflight)" — it is enrichment_queue.qsize(), which drops a job the moment the worker claims it, so inflight jobs are excluded.
• Health Check Flow diagram shows the memory probe as MATCH (m:Memory) RETURN count(m); the handler calls count_falkor_memories(), which excludes RECALL_EXCLUDED_TYPES. Same finding as PR docs: fix drift in Health & Analytics #270 on reference/api/health.
• Drift Detection Architecture diagram labels /health as feeding off the sync worker (HealthEndpoint --> SyncWorker); /health computes its own counts inline via automem/sync/accounting.py and does not consult the worker.
• Graceful Degradation says vector fields become null/unknown when Qdrant is down — accurate — but omits that status also becomes degraded on sync_status == "drift_detected" with both stores up.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying automem-website with    Cloudflare Pages

Latest commit:	100eb87
Status:	✅  Deploy successful!
Preview URL:	https://acc92f56.automem-website.pages.dev
Branch Preview URL:	https://docs-audit-operations-health-ncto.automem-website.pages.dev

View logs