docs: fix drift in Health & Analytics

[jack-arturo]

Automated docs-accuracy audit of reference/api/health. First review of this page — no prior review state existed.

The headline problem: the page told operators to alert on HTTP 503 from /health. The endpoint never returns 503 — health() ends in a bare return jsonify(health_data), so every response is HTTP 200 regardless of state. Any monitor wired to the documented contract would report the service healthy while both databases were down.

claim	current state	fix	evidence
"HTTP 200 if healthy, HTTP 503 if degraded"; degradation table lists 503 for Qdrant/FalkorDB failure; mermaid says HTTP 200/503	health() returns jsonify(health_data) with no status code — always HTTP 200. The string 503 does not appear anywhere in health.py	Document HTTP 200 always; direct readers to the status field. Degradation table now shows 200 across the board	automem@42ba8b6:automem/api/health.py#L111
status is "degraded when Qdrant unavailable"	Also degraded when sync_status == "drift_detected", i.e. both stores reachable but Qdrant holds fewer points	Restate all three degraded conditions; add a drift row to the degradation table	automem@42ba8b6:automem/api/health.py#L69-L76
queue_depth is "Total jobs in queue (pending + inflight)"	queue_depth is state.enrichment_queue.qsize(); pending and inflight are lengths of two separate structures, computed independently	Describe queue_depth as the queue size reported independently of the other two	automem@42ba8b6:automem/api/health.py#L102
"Enable detailed logging via the AUTOMEM_LOG_LEVEL environment variable: AUTOMEM_LOG_LEVEL=DEBUG"	AUTOMEM_LOG_LEVEL has zero occurrences repo-wide (so does bare LOG_LEVEL). app.py calls configure_logging(level=logging.INFO) with a hardcoded literal	Replace the fabricated variable with the real setup, and state plainly that the level cannot be changed by env var	automem@42ba8b6:app.py#L97, automem/runtime_environment.py#L9-L14
Four source-note deep links pinned to 0720da2	Stale pin	Repinned all four to 42ba8b6; paths themselves all verified correct	—

Verified against: automem@42ba8b61b7d0b24ecaeb7feb4ceef59f09fc7cd0

Questions

None.

Unverified

• The "Health Monitoring Service" section describes polling every 5 minutes and alerting at >5% drift. These are recommendations for an operator-built monitor rather than claims about shipped code, so they were left alone.
• has_critical in the /startup-recall response is any(importance >= 0.9). The page never defines the field, so there was nothing to correct — noting it here since the example payload happens to use exactly 0.9.

Follow-ups

Beyond the 5-fix cap, left for a later pass:

• The vector_dimensions.mismatch boolean is computed as collection_vector_size != VECTOR_SIZE — it compares the collection against the configured size, not the effective provider-reported size shown alongside it in the same object. The field table describes the object's members but not this comparison, which is worth spelling out.
• /health is exempt from auth inside require_api_token() (auth_helpers.py L56-57), not via the before_request path list in app.py (which exempts only OPTIONS, /viewer*, and /backup). The page's source note is correct; the distinction may still be worth a sentence.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying automem-website with    Cloudflare Pages

Latest commit:	df43df0
Status:	✅  Deploy successful!
Preview URL:	https://e3d58036.automem-website.pages.dev
Branch Preview URL:	https://docs-audit-reference-api-hea-8rcv.automem-website.pages.dev

View logs