API reference

00By role

Every route and tool, sorted by ordered rules into what writes signed memory and what reads and checks it. Nothing here is listed by hand.

reading /openapi.json and /v1/tools…

01Tokens

A token is a short address one agent hands another. Resolving it returns the signed bytes it names. The family says what it binds, and the families are not equally strong.

Field tokens

A raster or cube names an array, so its receipt attests a derivation: this responder computed the artifact whose BLAKE3 is artifact_cid, from a pinned scene, over an area (aoi_cid) and a time slot.

Pixels live in an evictable store at GET /v1/artifacts/{cid}. The signed record persists, so an evicted artifact is rebuilt on dereference rather than lost. To verify, resolve the token and re-hash the artifact against artifact_cid.

Descriptor tokens

A cell64 is a string no model saw in training. Coordinates, a date and a band name are, so the descriptor form reads without a lookup. Both forms resolve to the same bytes.

Resolve checks every claim against the signed body first. The coordinates must quantise to the fact's cell, the band must match, and the date must match a source capture time. A mismatch is 409.

Coordinates with fewer than 5 decimals are refused with 400: 4 decimals is about 11 m, which can land on the neighbouring cell.

Provenance and legacy prefixes

Resolving a fact token also returns its provenance class. direct_sensor and deterministic_index facts are recomputable from the cited source. model_output and human_curated facts carry a caution note in the same payload.

deterministic: true (or a provenance list) on POST /v1/recall keeps only the matching classes, and the filter runs before the receipt is signed. The old prefixes memt:, memb: and meme: still resolve.

A signature proves who signed and that the bytes are unchanged. It does not prove the value is correct.

02Client setup

The same JSON works in every host that speaks MCP. For a runtime without Streamable HTTP, use the mcp-remote stdio bridge. No key and no install.

{
  "mcpServers": {
    "emem": {
      "type": "http",
      "url": "https://emem.dev/mcp"
    }
  }
}

The MCP layer wraps the same handlers as /openapi.json. Start with emem_ask: it resolves the place, recalls the bands and runs the matching algorithm in one call.

/v1/attest accepts facts only from this responder's key, an enrolled device or a key the operator lists; any other signature gets 403. Per-agent notes and derivations are signed with the agent's own key.

03Endpoints agents call most

Each has a matching MCP tool. The full surface is /openapi.json; the tool descriptors are at /v1/tools.

One-shot domain tools

Each wraps locate, recall and aggregate into one call that takes {place} or {lat, lng}. The receipts and fact_cids are the same as a manual recall.

04Primitives

The read surface is built from a few primitives. Each returns a signed receipt over content-addressed facts, so another peer can reproduce the answer.

When a cell has no value for a band, the answer is a signed absence with a typed reason, citable like any fact.

Embeddings

Analytics over sets of 128-D GeoTessera vectors, computed on CPU. When too few cells carry a vector, each returns a signed inconclusive with the observed count. The two render endpoints return images and are REST only.

Memory graph

Reads over the edges between facts and the notes agents write.

05Hunter: find events in a region

/v1/hunt takes an event and a region. It samples up to 32 cells, recalls the event's primary band at each, and returns the top 8 with cell64, value, fact_cid and a scene.png URL.

Free-text questions such as “where is deforestation happening in the Amazon” reach the same path through /v1/ask. Ranking uses the primary band only; the full formula is at /v1/algorithms/<key>.

06Physics solvers and forecasting

Three solvers run on signed inputs. Each returns its result with the fact_cids its initial condition was built from.

07Transparency log

Every write is appended to a Merkle log. A client that pins a head can later prove the log only grew.

The tree uses RFC 6962's construction with BLAKE3-256 in place of SHA-256, so Certificate Transparency tooling will not read it.

What it does not prove

• It does not stop a split view: the head, proofs and witness list all come from the responder being checked, and there is no gossip between clients.
• There is no witness allowlist. A co-signature proves a key signed a head, not that the key is independent.
• A receipt does not chain to the log, so you cannot yet prove a fact you hold is in it.

08The machine contract

This page lists the calls agents use most. The complete contract is /openapi.json, with every documented path under /v1/*.

Nine verbs

The read surface implements the algebra in the memory model. Each verb is an existing endpoint.

Browse the contract in the API reference (ReDoc). Agent discovery starts at /v1/agent_card, /agent.json or /.well-known/mcp.json.