Client Integration Guide

Quick start (HTTP)

1. Send POST /api/v1/orchestration/render with render_request.v0
2. Respect budgets and privacy_mode in your UX flows
3. If error present, inspect error.options[] and choose a recovery action
4. Use kv_policy to manage your local cache (pin/compress/evict)

Minimal request

{
  "version": "v0",
  "id": "34b2c9e0-3a8b-4f3c-9c2a-7fd3e5e9b6d1",
  "intent": "understand_component",
  "budgets": { "tokens_max": 1200, "time_ms": 300 },
  "privacy_mode": "allow",
  "request_id": "req-client-001"
}

Quick start (MCP)

1. Call command mnemoverse/render with render_request.v0
2. Handle error + error.options[] similarly

Error handling patterns

• retry_with_reduced_scope: reduce top_k/increase deadline_ms and retry
• explicit_l1_expansion: request expansion into global knowledge (if allowed)
• return_l4_only: return experience (L4) only
• return_minimal: return minimal result with current fragments

Privacy

• allow: may return short snippets
• redact: redact sensitive fields
• block: do not return raw text; only IDs/metadata

Metrics

• used_tokens, planner_ms, coverage_entities — for client telemetry
• Measure latency on the client side; do not include PII in logs

Caching via kv_policy

• pin > compress > evict (on conflict, apply the stronger directive)
• avoid pin for large and irrelevant fragments

References

• Contracts: ../contracts/README.md
• Retry Actions: ../orchestration/retry-actions.md
• Metrics: ../orchestration/metrics.md