openapi: 3.2.0 info: description: emem is shared memory for AI agents working together in the real world. license: name: Apache-2.0 title: emem Ask API version: 2.4.0 x-emem-surface-asymmetry: memory_notes: MCP only reach_them_at: POST /mcp, method tools/call read_side_is_here: - /v1/memory/search - /v1/memory/sse - /memories/{path} tools: - emem_memory_create - emem_memory_view - emem_memory_delete - emem_memory_rename - emem_memory_str_replace - emem_memory_supersede why_not_here: These write the agent correspondence plane, which is prose and untrusted-by-declaration. It is deliberately not part of the REST fact surface, and the two planes are kept apart rather than merged for convenience. servers: - description: Hosted instance (HTTPS-only) url: https://emem.dev tags: - name: Ask paths: /v1/ask: post: description: 'Single-shot free-text answer about a real-world location, backed by signed satellite/elevation/water/built-up receipts. Forwards a place mention plus a question; runs the locate → recall → algorithm chain server-side; returns one packaged envelope. When to use: Call when the question is about a specific place and the answer should carry its own evidence. Send the user''s question verbatim as `q` plus a location as `place` (free text), `cell` (cell64), or `lat`+`lng`. One envelope comes back: `answer`, `spatial_trace` (the readings as primitives, each point indexing `fact_cids`), `facts_summary`, `receipt` and `fact_cids` at the ROOT, and `caveats` naming grid resolution and revisit cadence. Missing bands are materialised on demand. `include: ["reasoning"]` adds the ordered stages with their detail; `include_image: true` bundles a Sentinel-2 thumbnail. A question outside the corpus answers `topic_routing.matched_topic: null` with the inventory, so you can route elsewhere rather than guess.' operationId: emem_ask requestBody: content: application/json: schema: $ref: '#/components/schemas/AskReq' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AskResp' description: 'application/json envelope by default; text/event-stream of emem.ask_stage.v1 events when the request sends Accept: text/event-stream' default: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.' summary: single-shot free-text answer with signed evidence. tags: - Ask components: schemas: Cost: description: 'Self-declared cost block on every receipt. Honest accounting: latencies are observed, freshness is the age of the stalest source cited (null when undatable, never 0 as a stand-in), `was_cached` is true when the hot cache served the read.' properties: credits: description: Conceptual cost units; 0 for L0/L1 read endpoints on the hosted responder. type: number latency_p50_ms: type: number latency_p99_ms: type: number source_freshness_s: description: 'Age of the STALEST source this response cites: now minus the earliest captured_at across the returned facts'' sources. null when nothing in the response carries a dated source, which is the honest answer for a primitive that reads no observation. Was a hardcoded 0 until 2026-08-05, so a 2021 DEM tile reported as 0 s old; a null here means unknown, never fresh.' type: - integer - 'null' was_cached: type: boolean type: object Fact: description: A primary attestation at (cell, band, tslot). `value` is the band's typed reading (number, array of numbers for vector bands, or a categorical class id). `unit` is the band's declared unit (e.g. `m_msl`, `degC`, `mm`). properties: absence_reason: description: Present only when kind=`absence`. enum: - unavailable_capability - outside_coverage - archetype_seed_unavailable - gpu_unavailable - upstream_error - upstream_timeout type: string band: type: string cell: $ref: '#/components/schemas/Cell64' fact_cid: $ref: '#/components/schemas/FactCid' kind: description: '`primary` = signed measurement; `absence` = signed "we don''t have this here" with a typed reason.' enum: - primary - absence type: string provenance: description: Upstream source key (e.g. `copdem30m`, `s2_l2a`, `cams_eu`). type: string receipt: $ref: '#/components/schemas/Receipt' tslot: $ref: '#/components/schemas/Tslot' unit: type: string value: description: Number, array of numbers, or class id depending on band type. required: - kind - cell - band - tslot - value - fact_cid - receipt type: object MaterializeNote: description: 'One entry in the response''s `materialize_notes[]`, recording what the lazy materializer did during this call. status:"materialized" means a signed fact was minted and persisted (a Primary observation OR a confirmed, evidence-backed Absence - both are signed and citeable by fact_cid). status:"skipped" means nothing was signed: `reason_class` says why (transient `timeout`/`upstream_error`, retryable; or structural `unknown_band`/`no_materializer`/`capability_unavailable`, not retryable here) and `absence` is always false, because a skip is ''unknown'', never a confirmed absence.' properties: absence: description: Always false on a skip; a confirmed absence is a signed fact with status:materialized, not a skip. type: boolean band: type: string cell: $ref: '#/components/schemas/Cell64' fact_cid: type: string latency_ms: type: number ok: type: boolean reason: type: string reason_class: enum: - timeout - upstream_error - unknown_band - no_materializer - capability_unavailable type: string retryable: type: boolean status: enum: - materialized - skipped type: string type: object ErrorEnvelope: description: The `emem.error.v1` failure envelope returned by every endpoint on a 4xx/5xx. Branch on the stable `code` (not the human `message`). See GET /v1/errors for the full code catalog. properties: code: description: Stable machine-readable error code. One of the codes in GET /v1/errors. example: invalid_argument type: string details: description: Optional structured recovery hints; present on errors that ship machine-readable next-steps. type: object message: description: Human-readable detail. For invalid_argument this names the offending field (e.g. "missing field `q`"). type: string path: description: Request path that produced the error. example: /v1/ask type: string schema: const: emem.error.v1 type: string required: - code - message - schema type: object AskResp: description: Response of /v1/ask. Single envelope combining (a) place resolution, (b) topic-router classification, (c) recalled facts under those topics, (d) applicable algorithm recipes that compose those bands into named scores, (e) optional Sentinel-2 RGB thumbnail URL, and (f) caveats. All facts are signed and content-addressed. properties: algorithms_for_question: items: properties: formula: type: string key: type: string topic: type: string type: object type: array answer: description: Short natural-language summary of what the responder found, synthesised deterministically from the structured fields (every cited value traces to a fact_cid in the receipt). On a cold cell whose bands are not yet materialized it states that plainly and points at `next_steps`; never an LLM call. type: string answer_md: description: Markdown variant of `answer`. type: string caveats: items: type: string type: array facts: properties: bands_already_attested_at_cell: items: type: string type: array facts: items: $ref: '#/components/schemas/Fact' type: array type: object foundation_embeddings: description: Per-encoder neighbour lists and consensus voting. Populated when the intent matches `find places like` / `what changed`. type: object materialize_notes: items: $ref: '#/components/schemas/MaterializeNote' type: array next_steps: description: Present when the routed algorithms could not evaluate because their input bands are not materialized at this cell. Each item is a literal follow-up call (e.g. POST /v1/recall with the exact missing bands) the agent can issue, then re-ask. items: properties: action: type: string body: type: object method: type: string path: type: string url: type: string why: type: string type: object type: array place_resolved: $ref: '#/components/schemas/LocateResp' receipt: $ref: '#/components/schemas/Receipt' topic_routing: properties: matched_keywords: items: type: object type: array matched_topics: items: type: string type: array out_of_scope: type: boolean routing: type: object type: object required: - topic_routing - facts - receipt type: object PubKey: description: Ed25519 32-byte public key, base32-nopad-lowercase encoded (52 chars). Returned in receipts and `/.well-known/emem.json`. example: 777er3yihgifqmv5hmc2wwmyszgddzderzhsx6rex4yoakwomvka type: string Cell64: description: 'cell64 wire form: four base-65,536 bigrams separated by dots, e.g. `defi.zb4d9.pefa.zf619`. Encoded resolution is ~9.55 m at the equator. Each bigram is either a CVCV quad, consonant `[bcdfghjklmnpqrstvwxyz]` followed by vowel `[aeiouAEIOU]` repeated twice, OR a synthetic 5-char `z[0-9a-f]{4}` slot used for the unused pad cells in the 65,536-entry alphabet. The regex pin matches `pattern` below byte-for-byte and is also surfaced under `Cell64Pattern` so agents can validate before sending.' example: defi.zb4d9.pefa.zf619 maxLength: 23 minLength: 19 pattern: ^(?:(?:[bcdfghjklmnpqrstvwxyz][aeiouAEIOU]){2}|z[0-9a-f]{4})(?:\.(?:(?:[bcdfghjklmnpqrstvwxyz][aeiouAEIOU]){2}|z[0-9a-f]{4})){3}$ type: string LocateResp: description: Response of /v1/locate. `cell64` is the canonical handle for the resolved place; `polygon_bbox` is present when the geocoder found an extent (city / park / lake / country / region), absent for point features. `via` declares which layer of the seven-tier embedded cascade answered, falling back to network (Photon → Nominatim) only when no embedded layer matched. properties: cell64: $ref: '#/components/schemas/Cell64' data_at_this_cell: description: Topic-grouped inventory of recallable bands and applicable algorithms at this cell. Lets the caller chain into /v1/recall without a second introspection round-trip. type: object label: description: Reader-friendly place label. type: string lat: type: number lng: type: number localized_names: additionalProperties: type: string description: Map of ISO 639 language tag (`en`, `bn`, `zh-Hans`, `ar`, …) to localized name, when the resolved entity is in Overture and carries `names.common`. Lets an agent surface the user's-language label without a second geocoder call. type: object neighborhood_cells: description: Eight neighbouring cell64s of the resolved centre cell. items: $ref: '#/components/schemas/Cell64' type: array overture_division: description: Overture-divisions provenance, present when the cascade pulled an authoritative admin polygon. `division_id` is the GERS ID (globally stable, citable in receipts). `subtype` declares the admin level (country/region/county/locality/etc). `country` is the ISO 3166-1 alpha-2 owner. properties: country: description: ISO 3166-1 alpha-2 (e.g. `BD`, `US`). type: string division_id: type: string schema_url: type: string subtype: enum: - country - region - county - localadmin - locality - borough - macrohood - neighborhood - microhood - dependency type: string type: object polygon_bbox: description: Present when the place has spatial extent. properties: max_lat: type: number max_lng: type: number min_lat: type: number min_lng: type: number source: description: '`overture_division_area` is authoritative (conflated OSM+Esri+Meta+TomTom polygon), preferred whenever Overture has a row for the entity. `country_table` / `admin1_table` / `admin2_table` / `admin3_table` are cities1000-aggregated approximations used when Overture is unreachable. `wide_bbox_table` is the curated wide-feature override for Sahara/Amazon/Himalayas etc.' enum: - wide_bbox_table - country_table - admin1_table - admin2_table - admin3_table - nominatim_boundingbox - overture_division_area - centre_cell_bbox type: string type: object polygon_geojson: description: True OSM/Overture boundary as GeoJSON `Polygon` or `MultiPolygon` when an admin tier resolved. Pass back to /v1/recall_polygon to mask the cell grid against the boundary. type: object polygon_sample_cells: description: Up to 64 representative cells covering the polygon, pass to /v1/recall_many or /v1/recall_polygon. items: $ref: '#/components/schemas/Cell64' type: array via: description: Layer of the seven-tier locate cascade that answered. `country`/`admin1`/`admin2`/`admin3` = GeoNames hierarchical-admin tables (in-process); `embedded` = cities1000 populated places (in-process); `pois` = curated GeoNames well-known landmarks (peaks/lakes/parks/airports/monuments, in-process); `wide_bbox_table` = curated wide regions (in-process); `cache` = sled hot cache; `photon`/`nominatim` = network fallback. enum: - direct_latlng - wide_bbox_table - country - admin1 - admin2 - admin3 - embedded - pois - cache - photon - nominatim type: string required: - cell64 - via type: object FactCid: description: 'Content id of a fact: base32-nopad-lowercase encoding of `blake3(canonical_cbor(fact))`, the FULL 32-byte digest with no truncation. Always 52 characters, alphabet `[a-z2-7]`. A cid of any other length is a damaged citation, not a shorter address: /v1/memory_token/resolve rejects it as `fact_cid_malformed_length` rather than guessing. Note that `entity_cid` and `bundle_cid` are NOT this shape; both truncate to 16 bytes (26 characters) and hash an identity anchor or a citation list rather than a complete body.' example: qtv2bco56qw4pmlohk56dotoxyl3atmnjpmzrijj2kazw2mj57oq maxLength: 52 minLength: 52 pattern: ^[a-z2-7]{52}$ type: string AskReq: properties: cell: type: string include_image: default: false type: boolean lat: type: number lng: type: number model: description: Optional. Compose an extra prose answer with a named model, returned as `model_answer` BESIDE the deterministic `answer` rather than instead of it. `answer` never calls a model, so every number in it traces to a fact_cid; `model_answer` carries provenance.class = model_output. Name by base_model (nvidia/Cosmos3-Edge), by family (cosmos3_edge, gemma), or by any fragment that picks out exactly one of them (cosmos). A fragment matching several is refused and names them; an unroutable name is refused with the routable list; a routable model whose service is not answering is refused as busy or down, never substituted. type: string place: type: string q: type: string verbose: default: false description: When false (default), trim per-algorithm formulas + per-fact band_metadata + long _explanation prose so the response fits MCP's 25 KB cap. The signed receipt stays intact in either mode. type: boolean required: - q type: object Tslot: description: Band-tempo-relative integer offset from the emem epoch. Each band declares its tempo (`fast` / `medium` / `slow` / `static`); tslot is the rounded count of that tempo's unit since the epoch. minimum: 0 type: integer Receipt: description: 'Ed25519-signed receipt. The browser-side verifier at /verify reconstructs the preimage from the receipt fields alone, no callback to the issuer. **A receipt is byte-for-byte or nothing.** Current receipts carry `preimage_version: 2`, whose preimage binds request_id, served_at, primitive, cells, fact_cids AND, when present, the scope / as_of / edges / source_versions / field digests and the `merkle_proof` segment. Reshaping a receipt — dropping a field an SDK considers redundant, re-keying it, summarising it, round-tripping it through a lossy model — invalidates the signature BY DESIGN, and the result is indistinguishable on the wire from tampering. Store and forward the responder''s exact bytes. POST /v1/verify_receipt names which of the two it is where it can prove the difference (`reason: receipt_reshaped_after_signing` with a `failure_detail`). What is NOT signed: the caller''s `place`/`q` string, raw `lat`/`lng`, requested `bands[]`, requested `tslot`, and `intent` — a wrong-place geocode produces a valid signature for the wrong cell. Branch on /v1/locate `selected.is_high_confidence` before trusting place-anchored answers. Also: `fact_cid` is per-replica (signed_at differs across responders even for byte-identical upstream pixels); cross-replica join key is the tuple (cell, band, tslot). /v1/recall_polygon emits one independently signed receipt per cell under `by_cell..receipt`, `merged_facts[]` is convenience flattening and is NOT covered by an aggregate signature.' properties: cells: items: $ref: '#/components/schemas/Cell64' type: array cost: $ref: '#/components/schemas/Cost' fact_cids: items: $ref: '#/components/schemas/FactCid' type: array intent: description: Optional natural-language hint. Populated when served via /v1/intent. type: string merkle_proof: description: 'Inclusion proof for `fact_cids[0]` when persisted. Omitted from JSON when the cited facts pre-date the proof tree; under preimage_version 2 that absence is itself signed (an explicit ABSENT marker), so it is a statement rather than a gap. Do not strip this field: v2 binds it into the signature and removing it makes an authentic receipt report `signature_valid: false`.' properties: leaf_index: description: u32 leaf index in the canonical-sorted batch. type: integer path: description: Sibling hashes leaf→root. items: description: 32-byte sibling hash as a byte array items: type: integer type: array type: array root: description: The expected 32-byte batch root as a byte array. items: type: integer type: array version: description: 'Merkle hashing rule: 0 (omitted) = legacy unprefixed, 1 = RFC 6962-style prefixed.' type: integer required: - leaf_index - path - root type: object primitive: description: 'Namespaced wire form: `emem.recall`, `emem.find_similar`, `emem.verify`, …' type: string registry_cid: description: CID of the function registry version in force. type: string request_id: description: ULID generated per request. type: string responder: $ref: '#/components/schemas/PubKey' responder_key_epoch: description: u32 rotation counter; bumps when the operator rotates keys. type: integer responder_pubkey_b32: $ref: '#/components/schemas/PubKey' schema_cid: description: CID of the active CDDL profile. type: string served_at: description: ISO 8601 UTC, second precision. type: string signature: description: Ed25519 signature, 64 bytes base32-nopad-lowercase encoded. type: string source_versions: additionalProperties: type: string description: Per-source freshness map. type: object required: - request_id - served_at - primitive - cells - fact_cids - schema_cid - responder - responder_key_epoch - responder_pubkey_b32 - signature - registry_cid type: object