POST /v1/recall

curl -X POST "https://example.com/v1/recall" \  -H "Content-Type: application/json" \  -d '{    "scope": "string"  }'

{  "pack_id": "string",  "scope": "string",  "context_block": "string",  "layers": {    "events": [],    "facts": [],    "beliefs": [],    "episodes": [],    "understanding": []  },  "provenance": {}}

Views

Behavior notes (v0.9.9)

• Filters take exactly one field, metadata, with attributes observed_actor, caller, modality, labels, intent (ANDed; values ORed). Unknown attributes → 422. No confidence filter.
• exclude_content: true nulls large content/summary strings.
• budgets.per_layer_limits hard-caps each layer (events: 0 drops the layer).
• diagnostics = none / summary / full; full returns { policy, time_ms, knapsack_evictions } (phase-named time_ms keys, e.g. coordinator_recall, wal_hydrate, recall_total).
• provenance.trail entries are { phase, elapsed_ms } (+ a context_contributors list).
• A body field easy to miss: prefer_exhaustive (exhaustive candidate sweep). The order field has its own section below.
• Streaming: POST /v1/recall/stream emits plan → layer(×N) → context_block → provenance → diagnostics → done (the done event carries pack_id).
• pack_id can be reused by POST /v1/answer via use_pack_id (same-scope only; cross-scope → 404).

Ordering: relevance vs recency

The order field switches how the events layer is selected and rendered:

recency replaces ranked retrieval for the events layer with a timeline tail: the newest eligible events by observed_at, capped by budgets.per_layer_limits.events (else CORTEX_RECENCY_TAIL_EVENTS, default 100). Eligibility (scope/tenant, filters, temporal) is identical to ranked mode — only selection changes. It's built for "recent/latest X" questions, where relevance ranking surfaces the most-repeated items and can drop the newest ones. An unknown order value → 422.

/v1/answer forwards order and auto-infers recency for recency-shaped questions — see POST /v1/answer. The tuning knobs (CORTEX_RECENCY_TAIL_EVENTS / _ORDER / _INFERENCE) live in Recall Tuning.