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 Memory Token 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: Memory Token
paths:
  /v1/memory_token:
    post:
      description: 'Mint a citation handle, `emem:fact::` (or `:`), that any agent or LLM resolves to the byte-identical signed object. The antidote to referential drift on the value side: hand this one string to another agent instead of re-describing the fact. Validates both components are non-empty and free of the `:` separator. Memory algebra: the `cite` operation (https://emem.dev/docs/model.html).


        When to use: Call when you want one rebindable string to cite a place plus an attested fact across messages, threads, agents or tools. Pair it with `emem_echo_verify` before you publish the value. FOR MANY FACTS USE emem_memory_bundle INSTEAD, and this is measured rather than stylistic: a token is 83 to 84 characters and 51 LLM tokens while the value it points at averages 11 characters and 5.4, so N tokens cost about 9.5x the context of pasting the N numbers and hit the window sooner. A bundle is 38 characters at any N up to 256 and resolves in one round trip: it wins from N=1 against tokens and from N=5 against the plain values. Individual tokens are for citing ONE fact you must verify later.'
      operationId: emem_memory_token
      requestBody:
        content:
          application/json:
            schema:
              properties:
                band:
                  description: Optional band key; when set the response (not the token string) carries the band's provenance block (class, deterministic, tamper_evidence, trust_rank). Required (with observed_on) to mint descriptor_token.
                  type: string
                cell:
                  type: string
                fact_cid:
                  type: string
                observed_on:
                  description: Optional source capture date YYYY-MM-DD, as returned by /v1/recall in sources[].captured_at. With `band`, mints descriptor_token. This is valid time (when the sensor observed), never signed_at.
                  type: string
              required:
              - cell
              - fact_cid
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        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: 'compose an emem:fact:: citation handle.'
      tags:
      - Memory Token
  /v1/memory_token/resolve:
    post:
      description: 'Parse a `emem:fact::` citation handle and return the reading it cites. `value`, `unit`, `band` and `kind` are on the response at the TOP level, alongside the full signed `fact` body they were lifted from. Saves the agent from string-splitting the token and chaining `GET /v1/facts/` manually. Memory algebra: the `resolve` operation (https://emem.dev/docs/model.html).


        When to use: Call when you hold a memory_token from another agent or an earlier turn and want the value behind it. For a scalar quote `value_verbatim`, the exact decimal string the fact was signed as: re-typing the JSON number is where measured precision is lost. `value` and `unit` are always present, and an explicit null means the fact genuinely has none (an `absence` has no value; most index bands are dimensionless) rather than a missing field. The response also carries the parsed cell, the fact_cid, the full signed `fact` and a stable `fact_url` to hand on. A cid this responder does not hold is a typed 404: try /v1/fetch, or resolve at a mirror.'
      operationId: emem_memory_token_resolve
      requestBody:
        content:
          application/json:
            schema:
              properties:
                token:
                  description: 'emem:fact:<cell64>:<fact_cid>, or emem:fact:<lat>,<lng>@<date>@<band~render>:<fact_cid> (legacy memt: accepted)'
                  type: string
              required:
              - token
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryTokenResolveResp'
          description: ok
        '400':
          content:
            application/json:
              schema:
                properties:
                  details:
                    type: object
                  error:
                    type: string
                type: object
          description: invalid argument; `details.code` names which rule refused
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: not found
        '409':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: conflict (the request contradicts a signed fact, e.g. a token whose cell does not match the fact's own cell)
        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 round-trip dereference of a fact token.
      tags:
      - Memory Token
  /v1/memory_token/resolve_many:
    post:
      description: 'batch dereference: up to 256 fact tokens in one call, resolved independently through the same pipeline as the single resolve. Partial by design: a bad or unheld token yields a typed per-item error ({ok:false, status, error}) and never fails the batch. One batch receipt binds the union of resolved (cell, fact_cid) pairs; each item carries its own receipt so any single resolution forwards on its own. Fully-resolved responses carry Cache-Control: immutable (content-addressed bodies never change and receipts never expire); a batch with failures is not cached, since a 404 can become resolvable when the fact arrives.'
      operationId: emem_memory_token_resolve_many
      requestBody:
        content:
          application/json:
            schema:
              properties:
                tokens:
                  description: 'emem:fact: tokens (legacy memt: accepted), 1 to 256 per call'
                  items:
                    type: string
                  maxItems: 256
                  type: array
              required:
              - tokens
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        '400':
          content:
            application/json:
              schema:
                properties:
                  details:
                    type: object
                  error:
                    type: string
                type: object
          description: invalid argument; `details.code` names which rule refused
        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: 'batch dereference: up to 256 fact tokens in one call, resolved independently…'
      tags:
      - Memory Token
components:
  schemas:
    MemoryTokenResolveResp:
      description: 'Response of /v1/memory_token/resolve (and of the emem_memory_token_resolve MCP tool, which shares the implementation, so the two cannot disagree). The dereference at the centre of the citation loop: a token in, the signed reading it cites out. `value` / `unit` / `band` / `kind` are the reading itself, lifted to the top level; `fact` is the full signed body they were lifted from, and `value` is the same JSON node as `fact.value` by construction, never a re-render. `value_verbatim` is the scalar as the exact decimal string it was signed as, and is the field a model should quote: re-typing `fact.value` from a JSON number is where measured precision loss comes from. Nothing here is taken from the token: the token carries only cell + fact_cid, and any further claim a descriptor token makes (band, capture date, coordinates) is bound against this body before the dereference is permitted, so a mismatch is a 409 rather than a field in this response.'
      properties:
        band:
          description: Band key the value is a reading of, from the signed body.
          example: copdem30m.elevation_mean
          type: string
        canonical_token:
          description: 'The same citation in canonical grammar, `emem:fact:<cell64>:<fact_cid>`. Cite this one onward: a legacy `memt:` prefix, a descriptor anchor and a bare cid all normalise here.'
          type: string
        cell:
          $ref: '#/components/schemas/Cell64'
        cell_matches:
          description: 'Whether the cell the token asserted was CHECKED against the signed fact''s own cell, and agreed. `false` means NOT CHECKED, never checked-and-mismatched: a token whose cell contradicts the fact is refused with 409 before this response exists. The only route to a 200 with `false` is a degraded resolve, where a bare or recovered cid asserted no cell to compare and `cell` below is adopted from the signed body. Gate provenance on this field and you get the address check; read `degraded` for whether the citation itself was well-formed.'
          type: boolean
        degraded:
          description: True when a BARE fact_cid was accepted, i.e. the `emem:fact:<descriptor>:` head was missing or the cid was recovered from surrounding text. The bytes and the receipt are as authoritative as any resolve; only the citation was lossy, and a bare cid is responder-scoped so it is ambiguous elsewhere. Re-cite `canonical_token`.
          type: boolean
        degraded_reason:
          description: Present only when `degraded`. Names the recovery class and what to do about it.
          type: string
        fact:
          $ref: '#/components/schemas/Fact'
        fact_cid:
          $ref: '#/components/schemas/FactCid'
        fact_url:
          description: Stable URL serving bytes identical to `fact`.
          format: uri
          type: string
        kind:
          description: 'Which kind of fact this token resolved to. Read it to interpret a null `value`. There is deliberately no top-level `tslot`: primary and absence carry a scalar `tslot` and a derivative carries a `tslot_window` pair, so time stays inside `fact` where it is typed honestly rather than flattened into one field that would be wrong for one of the three.'
          enum:
          - primary
          - derivative
          - absence
          type: string
        offline_verify_at:
          description: Where to re-check the receipt without trusting this responder.
          type: string
        provenance:
          description: Tamper-provenance, attached by THIS responder from its own registry at resolve time rather than carried in the token. For a primary fact it describes the band (`class`, `deterministic`, `tamper_evidence`, `trust_rank`); for a derivative it describes the derivation, and `responder_recomputed` is the field that separates what this responder verified from what the attester merely declared. Omitted when the band is unknown here.
          type: object
        receipt:
          $ref: '#/components/schemas/Receipt'
        resolved:
          description: 'Always true on a 200; the responder holds these bytes. A cid it does not hold is a 404, not a `resolved: false` body.'
          type: boolean
        signer_b32:
          $ref: '#/components/schemas/PubKey'
        token:
          description: The citation exactly as sent, echoed back.
          type: string
        unit:
          description: The band's declared unit (`m`, `degC`, `mm`). Always present, explicitly `null` when the band is dimensionless (most indices, including NDVI) or when the fact is a derivative or an absence.
          type:
          - string
          - 'null'
        value:
          description: 'The cited reading: a number, an array of numbers for a vector band, or a class id. Always present, explicitly `null` when there is no reading, which happens only for `kind: "absence"`. Identical to `fact.value`.'
        value_verbatim:
          description: The scalar value as the exact decimal string it was signed as. Absent for non-scalar values (vectors, class ids, absences). Quote this rather than reformatting the number.
          type: string
      required:
      - token
      - canonical_token
      - cell
      - fact_cid
      - value
      - unit
      - band
      - kind
      - fact
      - resolved
      - cell_matches
      - fact_url
      - signer_b32
      - receipt
      - degraded
      type: object
    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
    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
    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
    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
    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.<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