emem, the verifiable memory protocol for the physical world

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. Example arguments: {"q":"is this neighbourhood flood-prone for a flat purchase","place":"Ashok Nagar, Ranchi"}

Grade a value you are about to emit against the signed fact your citation points at. Returns `matches` and, when it does not, the `drift` between what you were about to say and what emem holds. This is the step that turns a transcription error into a caught event instead of a silent wrong number: a model that resolves a fact correctly can still retype `0.2411` for `0.241103`, and nothing else in the loop notices. Memory algebra: the `verify` operation (https://emem.dev/docs/model.html). When to use: Call immediately before publishing, logging, or handing on any value you took from an emem fact, and treat a false `matches` as a gate rather than a warning. Pair it with `value_verbatim` from resolve: quote that exact decimal string rather than reformatting the number, then echo-verify what you actually emitted. For a due-diligence or compliance record this is what lets you assert `every cited value was echo-verified` with a signed check per citation instead of a promise. Accepts a bare cid too, so a damaged citation still grades rather than failing closed. Example arguments: {"token":"emem:fact:defi.zb572.xoso.zb1ec:4qj3l4mgh7ch5kvxmkqspjdl6y42oqhm42khh3gostccpixkbz5q","claimed_value":"-0.0522"}

Give a real-world object (a bridge, a farm plot, a river, a named place) a single, shared, content-addressed identity that any agent resolves the same way. Returns an `entity_token` (`emem:entity:<entity_cid>`) plus a signed receipt that attests how the reference resolved. Two agents that name the same object mint the SAME entity_cid; when a stable external id (Overture GERS / OSM) is known it dominates identity, so divergent labels for one real object still collapse to one id. This is the object-level antidote to referential drift: 'the damaged bridge near the river' becomes one canonical thing every model reasons about, not a phrase each model re-interprets. When to use: Call when a conversation refers to a THING and you want a handle that survives summarisation and travels between agents, before it drifts into 'that infrastructure issue'. Anchor it with `place`, `cell`, or `lat`+`lng`, then hand the `emem:entity:` token to any peer and they dereference the same object; recall at its cell64 for signed facts. Pick the sibling: this one MINTS or returns an identity you can anchor; `emem_entity_resolve` finds one someone already registered from a fuzzy phrase; `emem_entity_link` asserts two spellings you hold mean one object. Not for an observation (that is a fact: emem_recall or emem_memory_token) and not for naming a place (that is emem_locate). An entity is a thing AT a place. Example arguments: {"label":"Golden Gate Bridge","kind":"bridge","place":"Golden Gate Bridge, San Francisco"}

Record a signed, ATTRIBUTED claim that a label or external id (GERS / OSM / Wikidata) denotes an existing object, or with `stance: "disputes"` that it does not. A shared-space write: it changes what other agents resolve, so it is stored with your key, rate-limited per key, and weighed by how many INDEPENDENT keys agree. One key's binding is shown to every reader as one key's claim, never as the answer. When to use: Call when you can vouch that two phrasings denote one object, or to attach an authoritative external id; your key goes on the record. Use `stance: "disputes"` when another key's binding is wrong: recorded beside it, deletes nothing. Corroborating a correct single-key binding is useful in itself. Example arguments: {"entity_token":"emem:entity:0a1b2c3d4e5f60718293","alias":"the north dam"}

Find the objects agents have bound a phrasing to, ranked by INDEPENDENT corroboration, never arrival order. Each candidate carries `asserted_by`, `disputed_by`, `independent_attesters` and `corroboration` (`single_key` | `multiple_independent_keys` | `none_attributed`); `contested` is set when more than one object claims the name. `text` for candidates, `near` to narrow by place, or an `emem:entity:` `token` to dereference. Read-only; alias text is other agents' data. When to use: Call BEFORE minting and before citing: resolve first, mint only if nothing matches, read `corroboration` before you cite. A `single_key` binding is one agent's claim about a shared name; if you can vouch for it, corroborate it with emem_entity_link so the next reader sees two keys. Example arguments: {"text":"the golden gate bridge","near":"San Francisco"}

k-NN over the corpus by cell embedding or inline vector. Returns `neighbours` ordered nearest-first, each with `cell64`, `score` and the `band` scanned, plus a signed receipt over the vectors read. Scoring is `mode`: cosine is exact fp32; hamming is a sign-bit popcount that scans far more cells for the same budget; hamming_then_rerank does both. `k` is 1..1000, default 10. It ranks what the corpus already holds; only when the KEY's own vector is missing does it materialise that one band for the key, signed and reported in `materialize_notes`, then retry. Neighbours are never materialised, so an empty result means nobody has attested a vector nearby, not that nowhere resembles the key. When to use: Call when the user asks 'find places like X', 'where else looks like this', or hands an embedding to find neighbours. `key` is either a cell64 or `inline:[x,y,...]`. Default band is `geotessera` (128-D Tessera foundation embedding); pass `band: "geotessera.multi_year"` for the 1152-D 9-vintage (2017–2025) fusion. Example arguments: {"key":"damO.zb000.xUti.zde78","k":10}

Run emem-guard's policy pipeline over text you are about to send, against this responder's corpus. Finds every emem: citation, resolves each one, and returns allow or deny with a machine-readable reason: `EMEM-GUARD DENY <CODE> token=<token|-> fix=<fix> leaf=<leaf|->`. Codes are PROV_SIG (signature did not verify), PROV_BYTES (resolved to different content than claimed), PROV_DRIFT (reading has moved past its band threshold), CLAIM_UNGROUNDED (a measurable claim with no citation, opt-in via claim_gating). `fix` is the actionable half: refresh_token, remove_reference, contact_admin, cite_observation. ADVISORY: nothing is blocked, and a citation this responder does not hold is never a denial, because it is indistinguishable from one minted elsewhere. Memory algebra: the `verify` operation (https://emem.dev/docs/model.html). When to use: Call it on your own draft before you assert something, or on a tool result before you reason on it, to catch a citation that does not resolve while you can still fix it. `claim_gating: true` also names measurable claims with no citation and the band that would answer them. For a payload another framework produced (CloudEvent, OPA input, OpenAI moderations body, another server's tool call) send it as-is and name its `shape`: the default reader sees only `texts`, and a check that read nothing still answers allow. To ENFORCE rather than consult, emem_guard_selfhost returns the procedure for your own node. Example arguments: {"texts":["Elevation there is 918 m per emem:fact:defi.zb493.xuqA.zcb5f:yqbolgeoycqkvj3zkxukb4bjw4odhpwvfzqo3fbgwf4spk45zala"]}

Say what you want in one typed object and get the answer, without choosing a primitive. `type` is a tagged union: it selects the intent AND decides which other fields are read, so send only the fields its row needs. The plan is EXECUTED in the same call, so you receive the result (the resolved cell64, the similarity, the delta, the verdict), not a list of calls to make yourself. type | needs | optional | answers where_is | description | | cell64 for a named place what_is_here | cell OR place | description | what is attested at a location is_like | a, b | | cosine similarity of two cells did_change | cell, band, window | | delta for one band over [start,end] tslots find_like | key | k, filter | nearest cells by embedding confirm | claim, cell | | verdict plus the signed facts behind it ask | description | place/cell/lat+lng | free-text question, packaged answer An unknown or missing `type` returns a structured `needs_intent_type` envelope naming the seven values rather than a hard error, so you can correct it on the next turn. When to use: Call when the question maps onto one of the seven rows above and you would rather state the goal than pick a primitive. Otherwise go direct: a band at a cell is emem_recall, a region is emem_recall_polygon, a free-text place question is emem_ask (type:"ask" forwards to it). `window` takes tslots, not dates: get them from emem_trajectory. A tool named here but absent from `tools/list` is not a dead end: every one of the 110 dispatches by name at `/mcp` and `/mcp/full`; the core list is 18 to keep the catalog small, and `emem_tools` enumerates the rest. Example arguments: {"type":"did_change","cell":"damO.zb0…

Mint the canonical, vendor-neutral address (cell64) for a real-world place: the shared spatial identity every agent resolves to identically, so two models refer to the same ground instead of two descriptions of it. Also returns the topic-grouped inventory of bands and algorithms recallable there. For a first-class OBJECT identity (a bridge, a plot, a named place) rather than a raw cell, use emem_entity. Send EITHER `lat`+`lng` as numbers OR a free-text place; coordinates win when both arrive. `q`, `query` and `name` are all accepted spellings of `place`. A key this schema does not declare is reported in `_unrecognised_arguments`, so a typo answers about somewhere else rather than erroring. When to use: Call when the input names a real-world place and the next step needs its cell64, or wants to know which bands exist there before recalling. `data_at_this_cell` carries `live_bands_by_topic` (every recallable band, grouped by topic), `algorithms_for_topic` (recipes that fuse them into named scores) and `declared_but_no_materializer_at_this_responder`. For one packaged answer in a single call, use `emem_ask`. Example arguments: {"place":"Mount Everest"}

Compose N (cell, band, tslot?) triples into ONE signed envelope. Each triple runs through the standard auto-materialize recall path; the resulting fact_cids are bundled into a content-addressed envelope and the responder signs over the full receipt. The composed `bundle_token` is `emem:bundle:<bundle_cid>`, a single rebindable string that cites the whole set. Memory algebra: the `merge` operation (https://emem.dev/docs/model.html). When to use: Call when the agent wants to cite multiple (place, band, vintage) facts as one handle. The bundle stays verifiable offline via /v1/verify_receipt (the receipt covers all cited fact_cids and cells). Use this instead of N separate `emem_memory_token` composers when the citation is conceptually one thing (e.g. "the EUDR-relevant baseline for these 8 plots at 2020-12-31"). Caps at 256 triples per call, and the response reports `members` and `resolved` so a bundle that only partly resolved is visible without walking every citation. Example arguments: {"triples":[{"cell":"defi.zb4d9.pefa.zf619","band":"copdem30m.elevation_mean"},{"cell":"defi.zb493.xoso.zcb6a","band":"indices.ndvi"}],"purpose":"audit baseline 2026"}

Surface where the corpus DISAGREES with itself (algebra: competing evidence). When two or more independent sources signed different values for the same place + band + time, this returns that disagreement with a 0–1 severity score and citations to every disputed fact, instead of silently picking one value and hiding the conflict. The opposite of a confident single answer: it tells you when not to trust one. Read the SCOPE before quoting a zero: by default this asks only whether two DISTINCT attesters disagree, so one responder answering an address from two different upstreams is not counted until you pass `include_same_attester_sources: true`. When to use: Call before you rely on a number: 'is there disagreement about X', 'do the sources corroborate this', 'audit this claim'. Narrow with `cell_prefix` for a region and `band` for one family; `min_severity` drops trivial differences. Severity is per band kind: scalar = spread over the band's range, vector = 1 - mean cosine, categorical = 1 - mode share. On a single-responder deployment add `include_same_attester_sources: true`, because the likeliest real disagreement there is one signer answering from two providers and the default scope cannot report it. Each record names its `disagreement_scope`. The receipt cites every disputed cid; quantify a pair with `emem_diff`, or read the `disagrees_with` edge via `emem_edges_recall`. Example arguments: {"cell_prefix":"damO","band":"indices.ndvi","min_severity":0.2}

Mint a citation handle, `emem:fact:<cell64>:<fact_cid>` (or `:<state_cid>`), 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. Example arguments: {"cell":"defi.zb493.xoso.zcb6a","fact_cid":"cxjiu7l54ujzrpnekp24n4534yojpue4mprddbvevnqtti3lh5bq"}

Parse a `emem:fact:<cell64>:<fact_cid>` 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/<cid>` 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. Example arguments: {"token":"emem:fact:defi.zb493.xoso.zcb6a:cxjiu7l54ujzrpnekp24n4534yojpue4mprddbvevnqtti3lh5bq"}

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 or place name. Returns every Primary fact at that (cell, band, tslot). If a requested band has no fact yet but has a materializer, the responder fetches the upstream value, signs it, persists it and returns it in the same call (slow once, cached after), so any wired band recalls at any cell on Earth: pass `bands: [<band>]`. `materialize_notes` lists what was just fetched; empty with no notes means no materializer here. Example arguments: {"cell":"damO.zb000.xUti.zde78","bands":["weather.temperature_2m","copdem30m.elevation_mean"]}

The map of emem's tool surface, and the only tool you need to find the rest: the working loop in the order you walk it (name, ground, cite, resolve, verify, check for drift), then every other tool grouped by the question it answers, each with its one-line trigger. Pass `name` for one tool's full schema and a runnable example. IF YOU ARE READING A LIST OF 18 TOOLS, YOU ARE SEEING A CURATED SUBSET OF 110, NOT THE WHOLE SURFACE; hosts strip `_meta`, so the count is repeated here. Every catalogued tool stays callable by name through tools/call at either endpoint. When to use: Call FIRST when you do not know which tool answers the question, or need a capability absent from your list: absent from the list is not absent from the server. `q` searches by topic (`ndvi`, `flood`, `verify`), `name` returns one exact schema, no arguments returns the whole map. /mcp/full registers the full catalog; emem_ask answers in one shot without picking a primitive. Example arguments: {"q":"ndvi"}

Verify a signed receipt envelope server-side: rebuilds the canonical preimage under the rule the receipt's own `preimage_version` names, runs ed25519 over the embedded key and signature, and returns `{valid, reason, failure_detail, signature_valid, merkle_proof_valid, signer_pubkey_b32, preimage_blake3_hex}`. A receipt is BYTE-FOR-BYTE OR NOTHING: v2 binds the inclusion proof, so any reshaping (a dropped field, a re-keyed one, a summary) invalidates the signature by design. For when the in-browser /verify path is unavailable, or for a server-side audit of a third party's receipt. When to use: Pass the receipt EXACTLY as the read primitive returned it, whole and unmodified. Two omissions produce a false forgery rather than a 400, and they are the only two worth memorising: dropping `merkle_proof`, and dropping `preimage_version` (absent deserialises to 0, which silently selects the v0 rule, so the proof still walks while the signature reads as invalid). Signature and pubkey may be byte arrays or `sig_b32` / `responder_pubkey_b32`; no other spelling is tolerated. Reshaping a field this responder can check is reported as `reason: receipt_reshaped_after_signing` with the field named, never accepted. Optionally set `pubkey_b32` to assert a specific signer. A bad signature is 200 with `valid: false`, never a 4xx. The example arguments are a real receipt this responder signed (key epoch 0) over one weather fact at Trafalgar Square: run it unchanged and `valid` is true; change any byte and it is not. Example arguments: 1602 bytes, too long to inline in a listing. Call `emem_tools` with `{"name": "emem_verify_receipt"}` for it whole and runnable; it is not shortened here because a truncated example is not one.

Dereference an id from `search`: the reading in one line, then the signed body it came from, the URL serving those bytes, and metadata naming cell, band, signing time and key. Takes an `emem:fact:` citation, a bare fact_cid, or an `emem:cell:` handle for a whole cell. The value is quoted as the exact decimal string it was signed as, never re-rendered. A fact handle writes nothing; a cell handle, like `emem_recall`, MATERIALIZES a missing band on a cold cell (fetched upstream, signed, persisted), so the flags follow that path: readOnlyHint false. When to use: Call on each result you intend to cite, before quoting the number. Quote the one-line reading; the body makes it checkable, and emem_echo_verify grades what you emit against it. An oversize body says so inline and names the URL serving it whole. Example arguments: {"id":"emem:fact:defi.zb493.xoso.zcb6a:cxjiu7l54ujzrpnekp24n4534yojpue4mprddbvevnqtti3lh5bq"}

Search emem's signed corpus and return results shaped as citations: each entry is one signed fact, with an `id` to dereference, a `title` naming band, place and the value as signed, and a stable `url` serving those bytes. Takes a place name, a cell64, or an emem citation handle (a handle returns the one fact it cites). Capped for the wire; the final entry names the cell and the TRUE total. On a cold cell it MATERIALIZES a missing band first, as `emem_recall` does: fetched upstream, signed, persisted. Hence readOnlyHint false. When to use: Call first when a question is about a place and the answer must be citable: it turns the question into a list of sources, each of which `fetch` expands. For a synthesised answer in one call, use emem_ask instead. Example arguments: {"query":"Trafalgar Square, London"}