emem, the verifiable memory protocol for the physical world

Answer a free-text question about a real-world location in one call. Signed satellite, elevation, water and built-up receipts support the answer. The tool sends the place and the question through the locate, recall and algorithm chain on the server, and returns one packaged envelope.

When to use: Call this when the question is about a specific place and the answer must carry its evidence. Send the question as q, with place, cell or lat+lng. Over MCP a point answer is a projection. It has answer, receipt (cite receipt.fact_cids), place_resolved, routed_to, facts_summary, algorithm_outcomes_summary, spatial_trace and scene_url. It has model_answer if you sent model, and _projection, which names what the projection removed. POST /v1/ask has more: caveats, topic_routing, reasoning, and inventory with include:["inventory"]. A routed_to other than answer comes back complete. The answer gives a current value. For how X changed, use emem_intent did_change or emem_diff.

Example arguments: {"q":"is this neighbourhood flood-prone for a flat purchase","place":"Ashok Nagar, Ranchi"}

Grade a value that you will emit against the signed fact that your citation cites. The tool returns matches. When the value does not match, it also returns the drift between your value and the value in emem. This step catches a transcription error that would otherwise be a silent wrong number. A model can resolve a fact correctly and still type 0.2411 for 0.241103. No other step in the loop sees this. Memory algebra: the verify operation (https://emem.dev/docs/model.html).

When to use: Call this immediately before you publish, log or pass on a value from an emem fact. Treat a false matches as a stop, not a warning. Use value_verbatim from resolve: quote that exact decimal string, then echo-verify the text you emitted. For a due-diligence or compliance record, this gives a signed check for each citation. Then you can state every cited value was echo-verified. The tool also accepts a bare cid, so a damaged citation still gets a grade.

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) one shared identity. Every agent resolves this identity the same way. The result is an entity_token (emem:entity:<entity_cid>) and a signed receipt that shows how the reference resolved. Two agents that name the same object get the SAME entity_cid. A stable external id (Overture GERS or OSM) decides identity when the responder knows one, so different labels for one object collapse to one id. This stops referential drift: 'the damaged bridge near the river' becomes one thing that every model reasons about.

When to use: Call this when a conversation refers to a THING and you need a handle that travels between agents. Anchor it with place, cell or lat+lng. Give the emem:entity: token to a peer, and the peer gets the same object. Recall at its cell64 to read signed facts. Choose the correct sibling: this tool MINTS or returns an identity. emem_entity_resolve finds an identity that an agent registered before, from a fuzzy phrase. emem_entity_link records that two names mean one object. Do not use it for an observation (use emem_recall or emem_memory_token) or for a place (use 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 an external id (GERS, OSM, Wikidata) names an existing object. With stance: "disputes", record that it does not. This is a write to the shared space: it changes what other agents resolve. The responder stores it with your key, limits the rate for each key, and weighs it by how many INDEPENDENT keys agree. Every reader sees the binding of one key as the claim of one key, never as the answer.

When to use: Call this when you can confirm that two names mean one object, or to attach an authoritative external id. Your key goes on the record. Use stance: "disputes" when the binding of another key is wrong. The dispute goes beside it and deletes nothing. A second key on a correct single-key binding is useful by itself.

Example arguments: {"entity_token":"emem:entity:0a1b2c3d4e5f60718293","alias":"the north dam"}

Find the objects that agents connected to a phrase. The tool ranks them by INDEPENDENT corroboration, never by arrival order. Each candidate has asserted_by, disputed_by, independent_attesters and corroboration (single_key | multiple_independent_keys | none_attributed). contested is true when more than one object claims the name. Send text for candidates, near to narrow by place, or an emem:entity: token to dereference. The tool only reads. Alias text is data from other agents.

When to use: Call this BEFORE you mint and before you cite. Resolve first, and mint only if nothing matches. Read corroboration before you cite. A single_key binding is the claim of one agent about a shared name. If you can confirm it, corroborate it with emem_entity_link, so the next reader sees two keys.

Example arguments: {"text":"the golden gate bridge","near":"San Francisco"}

Find the k nearest cells in the corpus by cell embedding or by an inline vector. The answer has neighbors, nearest first, each with cell, score, lat/lng and band_used, and a signed receipt over the vectors it read. mode sets the scoring. cosine is exact fp32. hamming counts sign bits and scans many more cells for the same budget. hamming_then_rerank does both. k is 1 to 1000, default 10. The tool ranks only what the corpus holds. When the KEY has no vector, it materializes that one band for the key, signs it, reports it in materialize_notes, and tries again. It never materializes neighbours. Thus an empty result means that no attested vector is near, not that no place is similar.

When to use: Call this for 'find places like X' or 'where else looks like this', or with an embedding. key is a cell64 or inline:[x,y,...]. The default band is geotessera (the 128-D Tessera foundation embedding). For the 1152-D fusion of 9 years (2017 to 2025), send band: "geotessera.multi_year".

Example arguments: {"key":"defi.zb64a.cAzU.zfa27","k":10}

Run the emem-guard policy checks on text before you send it. The checks use this responder's corpus. The tool finds every emem: citation, resolves each one, and returns allow or deny with a reason that a machine can read: EMEM-GUARD DENY <CODE> token=<token|-> fix=<fix> leaf=<leaf|->. The codes are: PROV_SIG (the signature did not verify). PROV_BYTES (the citation resolved to different content). PROV_DRIFT (the reading moved past its band threshold). PROV_VALUE (a stated value does not agree with the cited fact). CLAIM_UNGROUNDED (a measurable claim has no citation; turn it on with claim_gating). fix tells you what to do: refresh_token, remove_reference, contact_admin, cite_observation, correct_value. Only a self-hosted guard returns GEO_ZONE and redact_and_retry. This tool is ADVISORY: it blocks nothing. A citation that this responder does not hold is never a denial, because it can be a citation from another responder. Memory algebra: the verify operation (https://emem.dev/docs/model.html).

When to use: Call it on your draft before you assert something, or on a tool result before you reason on it. Then you can fix a citation that does not resolve. With claim_gating: true, it also names measurable claims with no citation, and the band that answers each. For a payload from another framework (CloudEvent, OPA input, OpenAI moderations body, a tool call from another server), send it unchanged and name its shape. The default reader reads only texts, and a check that read nothing answers allow. To ENFORCE the policy, use emem_guard_selfhost. It returns the procedure for your own node.

Example arguments: {"texts":["Lusail ground sits at 2.6 m per emem:fact:defi.zb521.jawI.gOze:f3yr3urkrfwamlemwadulgth2qpw645vi6l6fhtuu4dy5o7onahq"]}

State what you want in one typed object and get the answer. You do not choose a primitive. type selects the intent AND the other fields that the tool reads. Send only the fields in its row. The plan runs in the same call: you get results, not a list of calls.

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 and the signed facts behind it ask | description | place/cell/lat+lng | free-text question, packaged answer area_over_time | geometry, bbox OR areas; start_date, end_date | index, max_scenes | index of an area for each overpass, with spread and anomaly

An unknown or missing type returns a needs_intent_type envelope with the valid values. It is not a hard error.

When to use: Call this when the question matches one of the eight rows and you prefer to state the goal. Otherwise call the primitive. A band at a cell is emem_recall. A region is emem_recall_polygon. A free-text question about a place is emem_ask (type:"ask" sends it there). window takes tslots, not dates: get them from emem_trajectory. areas puts up to 6 areas on one chart. You can call a tool that this text names but your list does not show, by name, through tools/call.

Example arguments: {"type":"did_change","cell":"defi.zb64a.cAzU.zfa27","band":"indices.ndvi","window":[20245,20620]}

Get the canonical address (cell64) of a real-world place. Every agent resolves a place to the same cell64, so two models refer to the same ground. The answer also lists, by topic, the bands and algorithms that you can recall there. For an OBJECT identity (a bridge, a plot) instead of a cell, use emem_entity. Send lat+lng as numbers, or a free-text place. When both arrive, the coordinates win. q, query and name are other names for place. The answer lists keys that this schema does not declare in _unrecognised_arguments, so a typo is visible.

When to use: Call this when the next step needs the cell64 of a named place, or the bands that exist there. data_at_this_cell lists every band you can recall, by topic (live_bands_by_topic), the recipes that use them (algorithms_for_topic), and the bands with no materializer here. For one packaged answer in one call, use emem_ask.

Example arguments: {"place":"Mount Everest"}

Combine N (cell, band, tslot?) triples into ONE signed envelope. Each triple goes through the standard recall path, which materializes on a miss. The tool puts the resulting fact_cids in a content-addressed envelope, and the responder signs the full receipt. The bundle_token is emem:bundle:<bundle_cid>: one string that cites the full set. Memory algebra: the merge operation (https://emem.dev/docs/model.html).

When to use: Call this when you must cite several (place, band, date) facts as one handle. You can verify the bundle offline with /v1/verify_receipt. The receipt covers all the cited fact_cids and cells. Use this instead of N calls to emem_memory_token when the citation is one thing. An example is "the EUDR baseline for these 8 plots at 2020-12-31". The limit is 256 triples for each call. The answer gives members and resolved, so you can see a bundle that resolved only in part.

Example arguments: {"triples":[{"cell":"defi.zb4d9.pefa.zf619","band":"copdem30m.elevation_mean"},{"cell":"defi.zb493.xoso.zcb6a","band":"indices.ndvi"}],"purpose":"audit baseline 2026"}

Find where the corpus DISAGREES with itself (algebra: competing evidence). Two or more independent sources can sign different values for the same place, band and time. This tool returns that disagreement with a severity from 0 to 1 and a citation for each disputed fact. It does not pick one value and hide the conflict. It tells you when not to trust a single answer. Read the SCOPE before you quote a zero. By default the tool counts only disagreement between two DIFFERENT attesters. One responder that answers from two upstreams counts only with include_same_attester_sources: true.

When to use: Call this before you rely on a number: 'do the sources agree on X', 'audit this claim'. Use cell_prefix for a region and band for one band family. min_severity removes small differences. Severity depends on the band kind: for a scalar, the spread over the band's range. For a vector, 1 minus the mean cosine. For a category, 1 minus the share of the mode. On a single-responder node, add include_same_attester_sources: true. There, the most likely disagreement is one signer that answers from two providers. Each record names its disagreement_scope. The receipt cites every disputed cid. To measure a pair, use emem_diff. To read the disagrees_with edge, use emem_edges_recall.

Example arguments: {"cell_prefix":"damO","band":"indices.ndvi","min_severity":0.2}

Make a citation handle, emem:fact:<cell64>:<fact_cid> (or :<state_cid>). Any agent or LLM resolves it to the same signed object, byte for byte. Give this one string to another agent instead of a new description of the fact. The tool checks that both parts are not empty and do not contain the : separator. Memory algebra: the cite operation (https://emem.dev/docs/model.html).

When to use: Call this when you need one string that cites a place and an attested fact across messages, agents or tools. Use emem_echo_verify before you publish the value. FOR MANY FACTS, USE emem_memory_bundle. This is a measured result. A token is 83 to 84 characters and 51 LLM tokens. The value it cites is 11 characters and 5.4 tokens on average. Thus N tokens use about 9.5 times the context of the N numbers. A bundle is 38 characters for any N up to 256, and it resolves in one round trip. It costs less than tokens from N=1, and less than the plain values from N=5. Use one token to cite ONE fact that you must verify later.

Example arguments: {"cell":"defi.zb493.xoso.zcb6a","fact_cid":"cxjiu7l54ujzrpnekp24n4534yojpue4mprddbvevnqtti3lh5bq"}

Read a emem:fact:<cell64>:<fact_cid> citation handle and return the reading that it cites. value, unit, band and kind are at the TOP level of the answer, beside the full signed fact body. You do not split the token or call GET /v1/facts/<cid> yourself. Memory algebra: the resolve operation (https://emem.dev/docs/model.html).

When to use: Call this when you have a memory_token from another agent or an earlier turn and need the value. For a scalar, quote value_verbatim, the exact decimal string that the responder signed. A null value or unit means the fact has none (an absence, or an index with no unit). It does not mean a missing field. A cid that this responder does not hold returns a typed 404. Then 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). When a band has no fact yet but has a registered materializer, the responder fetches it. A fact_cid names one signed attestation, so you can cite a fact and verify it again. Resolve the cid anywhere and you get the same bytes. A fact_cid is NOT a fingerprint of the observation. The digest includes the responder's key and the time it signed. Thus two responders that measure the same thing make different fact_cids, and a cid resolves only at the responder that signed it. For identity across responders, use emem_entity. Send deterministic:true (or a provenance class list) to keep only facts that you can compute from the cited raw source. In the memory algebra this is ensure(cell, bands), not get: you state what must exist.

When to use: Call this after emem_locate, or with a cell64 or a place name. It returns every Primary fact at that (cell, band, tslot). A band can have no fact but have a materializer. Then the responder fetches the upstream value, signs it, stores it and returns it in the same call. The first call is slow; later calls use the cache. Thus any wired band recalls at any cell on Earth: send bands: [<band>]. materialize_notes lists what the call fetched. Empty notes mean no materializer here.

Example arguments: {"cell":"defi.zb64a.cAzU.zfa27","bands":["weather.temperature_2m","copdem30m.elevation_mean"]}

The map of emem's tools, and the one tool that finds all the others. It gives the working loop in order (name, ground, cite, resolve, verify, check for drift). Then it groups every other tool by the question it answers, each with a one-line trigger. Send name for the full schema of one tool and an example that runs. IF YOU SEE A LIST OF 18 TOOLS, IT IS A CURATED SUBSET OF 115, NOT THE FULL SURFACE. Hosts remove _meta, so this text repeats the count. You can call every catalogued tool by name through tools/call at either endpoint.

When to use: Call this FIRST when you do not know which tool answers the question. Also call it when your list does not have a capability. A tool that is not in your list can still be on the server. q searches by topic (ndvi, flood, verify). name returns one exact schema. With no arguments, you get the full map. /mcp/full registers the full catalog. emem_ask answers in one call without a choice of primitive.

Example arguments: {"q":"ndvi"}

Verify a signed receipt on the server. The tool builds the canonical preimage again, under the rule that the receipt's preimage_version names. It checks the ed25519 signature with the embedded key. It returns {valid, reason, failure_detail, signature_valid, merkle_proof_valid, signer_pubkey_b32, preimage_blake3_hex}. A receipt verifies BYTE FOR BYTE OR NOT AT ALL. Version 2 binds the inclusion proof, so a change of any kind makes the signature fail: a dropped field, a renamed field, a summary. Use this tool when the browser page /verify is not available. Also use it to audit a receipt from a third party.

When to use: Send the receipt EXACTLY as the read tool returned it, complete and unchanged. Two omissions cause a false forgery, not a 400. Do not drop merkle_proof. Do not drop preimage_version. Without it the value is 0, which selects the v0 rule, and the signature reads as invalid. The signature and the key can be byte arrays, or sig_b32 and responder_pubkey_b32. The tool accepts no other names. When a field changed after signing, the answer is reason: receipt_reshaped_after_signing and names the field. To require a specific signer, set pubkey_b32. A bad signature returns 200 with valid: false, never a 4xx. The example (from emem_tools) is a real receipt over two Trafalgar Square facts. Unchanged, it is valid. Change one 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. You get the reading in one line, then the signed body, the URL that serves those bytes, and metadata: cell, band, signing time and key. The id can be an emem:fact: citation, a bare fact_cid, or an emem:cell: handle for a full cell. The value is the exact decimal string that the responder signed, never a new format. A fact handle writes nothing. A cell handle, like emem_recall, MATERIALIZES a missing band on a cold cell: it fetches, signs and stores it. The flags follow that path: readOnlyHint false.

When to use: Call this on each result that you will cite, before you quote the number. Quote the one-line reading. The body lets a reader check it, and emem_echo_verify grades what you emit against it. When a body is too large, the answer says so and gives the URL that serves it complete.

Example arguments: {"id":"emem:fact:defi.zb493.xoso.zcb6a:cxjiu7l54ujzrpnekp24n4534yojpue4mprddbvevnqtti3lh5bq"}

Search emem's signed corpus and get results as citations. Each entry is one signed fact. It has an id to dereference, a title with band, place and signed value, and a stable url that serves those bytes. The query can be a place or a question about one. ('NDVI near Mount Fuji': a topic word narrows the results and never removes all of them.) It can also be a cell64, an emem:cell: handle, or an emem citation, which returns the one fact it cites. The list has a cap for the wire. The first entry (index 0) names the cell and the TRUE total. On a cold cell, the tool MATERIALIZES a missing band first, as emem_recall does: it fetches, signs and stores it. Thus readOnlyHint false.

When to use: Call this first when a question is about a place and the answer must have citations. It changes the question into a list of sources, and fetch expands each source. For one combined answer in one call, use emem_ask.

Example arguments: {"query":"Trafalgar Square, London"}