Recall facts at a cell (auto-materializes on miss)
emem_recallRetrieve signed, citeable facts at a canonical cell address, automatically fetching and signing missing values for bands with materializers. Return exact bytes for re-verification, not paraphrases.
Instructions
Read the signed facts at a canonical address (cell64); auto-materializes on a miss for any band with a registered materializer. A fact_cid names one signed attestation, so a recalled fact is citeable and re-verifiable rather than a paraphrase: resolving it anywhere returns those exact bytes. It is NOT a fingerprint of the observation. The digest covers the responder's key and the moment it signed, so two responders that measure the same thing mint different fact_cids and a cid resolves only at the responder that signed it; use emem_entity for identity that crosses responders. Pass deterministic:true (or a provenance class list) to keep only facts recomputable from the cited raw source, with no model or human in the loop. In the memory algebra this is ensure(cell, bands), not get: state what must exist and the responder reuses or materializes.
When to use: Call after emem_locate (or with a known cell64). Returns every Primary fact stored at that (cell, band, tslot). IMPORTANT: if the cell has no fact yet for a requested band AND that band has has_materializer=true (per emem_coverage_matrix / emem_materializers), the responder fetches the upstream value, signs it under its identity, persists it, and returns it in the same response (slower on the first call while the upstream is fetched; fast once cached). So for any wired band you can recall ANY cell on Earth without seeding, just pass bands: [<band>]. The response carries materialize_notes listing what was just fetched. Empty result with no notes means the band has no materializer at this responder.
Example arguments: {"cell":"damO.zb000.xUti.zde78","bands":["weather.temperature_2m","copdem30m.elevation_mean"]}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Explicit latitude, an alternative to `cell`; paired with `lng`. | |
| lng | No | Explicit longitude, paired with `lat`. | |
| band | No | optional single band key, convenience alias for bands:[band]. Use when you want exactly one band (e.g. 'geotessera.2020', 'modis.ndvi_mean') and would otherwise have to wrap it in an array. Both `band` and `bands` are accepted; if both are given they are merged. | |
| cell | Yes | cell64 string, e.g. 'damO.zb000.xUti.zde78' | |
| bands | No | optional band keys to filter, e.g. ['indices.ndvi','geotessera'] | |
| place | No | Free-text place name, an alternative to `cell`. | |
| scope | No | Optional multi-tenant scope {user_id, agent_id, run_id, org_id}. When at least one field is set, the recall is FILTERED to facts written under the same four-tuple (a recall scoped to {user_id:'u1'} sees only u1's facts, never another tenant's and never globally-written facts) AND the signed receipt binds the scope. Omit (or send {}) for the global, pre-v0.0.8 recall. | |
| tslot | No | optional time slot (band-tempo-relative integer offset from emem epoch) | |
| cell64 | No | Alias for `cell`. | |
| include | No | Opt-in response expansion. include:['provenance'] attaches each fact's tamper-provenance class, which is what `deterministic` and the `provenance` filter select ON: without it you can filter by class and never be told which class a returned fact is. include:['freshness'] attaches an advisory per-fact freshness block: a Q(Δt) staleness score from the band's physics decay kernel (the same one /v1/temporal_route ranks bands with), so an agent learns how stale each reading is in the call that returns it. Advisory only; it does NOT enter the receipt. include:['edges'] attaches each fact's typed temporal edges and threads their CIDs into the receipt. Absent leaves the response byte-identical to the pre-v0.0.9 recall. | |
| provenance | No | Tamper-provenance filter: return only facts whose band's provenance class is in this list. `attested_execution` is a device reading trusted through its verified OS execution trace and platform attestation (not recomputable). Applied BEFORE the receipt is signed, so the receipt covers exactly the returned facts; `bands_already_attested_at_cell` stays unfiltered so you still see what else exists at the cell. | |
| as_of_tslot | No | Bi-temporal valid-time bound. Returns the latest fact per (cell,band) whose tslot ≤ as_of_tslot, answers `what did this place look like AS OF date X`. Conflicts with an explicit `tslot` when as_of_tslot < tslot (rejected with code:`invalid_temporal_bound`). | |
| deterministic | No | Sugar over `provenance`: true keeps only facts any third party can recompute from the cited raw source (direct_sensor + deterministic_index); false keeps the rest (attested_execution + model_output + human_curated + unclassified). Composable with `provenance` (intersection). | |
| as_of_signed_at | No | Bi-temporal transaction-time bound. RFC 3339 string. Returns only facts whose `signed_at` ≤ as_of_signed_at, answers `what did emem KNOW as of system-date Y`. Malformed strings are rejected with code:`invalid_signed_at_format`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| facts | Yes | Signed facts at the cell, ordered per fact_order. | |
| receipt | Yes | ed25519 receipt over the returned fact_cids. Verify offline; select the rule from its preimage_version. Store and forward it byte-for-byte: preimage_version 2 binds every field it covers, including merkle_proof, so a reshaped receipt reports signature_valid:false on data nobody tampered with. | |
| fact_order | Yes | The ordering contract for facts, e.g. tslot_ascending. Stated rather than implied so nothing depends on position by accident. | |
| current_by_band | No | Per band, the fact_cid with the highest tslot: the current reading. Unslotted facts are excluded, since tslot 0 means undated rather than oldest. | |
| materialize_notes | No | ||
| bands_already_attested_at_cell | No | What else is readable here without materialising, so an empty result can be told apart from a wrong band name. |