docs: fix drift in Health & Analytics

[jack-arturo]

Automated docs-accuracy audit of reference/api/health. Every fix below is anchored to current source in verygoodplugins/automem.

Claim	Current state	Fix	Evidence
"Always returns JSON. HTTP 200 if healthy, HTTP 503 if degraded."	health() ends in a bare return jsonify(health_data) — Flask's default 200. There is no 503 anywhere in health.py.	Documented that /health always returns 200 and that monitors must read the status field.	automem@8ff266e:automem/api/health.py#L111
Degradation table gave HTTP 503 for Qdrant/FalkorDB failure; mermaid ended HTTP 200/503	Same as above — no code path returns 503.	Both HTTP-code cells set to 200; mermaid terminal message corrected; added a note that a non-200 means the service is unreachable, not degraded.	automem@8ff266e:automem/api/health.py#L111
status field: "degraded when Qdrant unavailable"	status is also "degraded" when sync_status == "drift_detected" (i.e. vector_count < memory_count), with both databases connected.	Field description lists all three triggers; added a drift row to the degradation table and a note to the mermaid flow.	automem@8ff266e:automem/api/health.py#L71-L76
/analyze response schema (no elapsed_ms)	Handler returns {"status": ..., "analytics": ..., "elapsed_ms": 0} — a third top-level key, hardcoded to 0.	Added elapsed_ms to the example plus a one-line note that it is not a real measurement.	automem@8ff266e:automem/api/recall.py#L2881
"Enable detailed logging via the AUTOMEM_LOG_LEVEL environment variable" with a AUTOMEM_LOG_LEVEL=DEBUG snippet	LOG_LEVEL/AUTOMEM_LOG_LEVEL are read nowhere in the Python service. app.py calls configure_logging(level=logging.INFO) with a hardcoded level. AUTOMEM_LOG_LEVEL exists only in the mcp-automem client.	Replaced the fabricated instruction with the actual behavior and noted where the variable really applies.	automem@8ff266e:app.py#L97, mcp-automem@946f9e5:src/index.ts#L92

Source-note permalinks for health.py and recall.py were also repinned from 0720da2 to 8ff266e — both files changed content since that commit (health.py switched to count_falkor_memories/count_qdrant_points). The app.py and auth_helpers.py links were left as-is; those files are unchanged since 0720da2.

Verified against: automem@8ff266e62e65cb2e81719a765b05f64a2361a127
Verified against: mcp-automem@946f9e5ed1385b632efd2e5b250d064bcc4295e8

Questions

• The vector_dimensions.mismatch flag compares the Qdrant collection size against VECTOR_SIZE (the configured value), not against effective — while being gated on effective having been set. The page documents the four sub-fields without stating which pair is compared. Intentional simplification, or worth spelling out?
• The alert-thresholds table still recommends paging on status: "degraded" as "FalkorDB or Qdrant unavailable". With drift now also producing degraded, that alert will fire on drift too. Left unchanged because the right remediation is a product decision, not a docs fact.

Unverified

• The "Health Monitoring Service (Python script)" polling loop, its 5-minute interval, and the 5% drift alert threshold. No such monitor script was located in the automem checkout; these read as recommended practice rather than shipped behavior, so the prose was left alone.
• recover_from_qdrant.py was not located during this pass and its reference was left untouched.

Follow-ups

• The Health Check Flow mermaid shows the FalkorDB probe as MATCH (m:Memory) RETURN count(m). The real query now runs through count_falkor_memories(), which appends a WHERE clause excluding RECALL_EXCLUDED_TYPES (accounting.py#L28-L41). The field table already documents the exclusion, so the diagram is a simplification rather than an error — dropped for the 5-fix cap.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying automem-website with    Cloudflare Pages

Latest commit:	24c53dc
Status:	✅  Deploy successful!
Preview URL:	https://008856f5.automem-website.pages.dev
Branch Preview URL:	https://docs-audit-reference-api-hea-a6bu.automem-website.pages.dev

View logs