io.github.Vortx-AI/emem

Tools

• emem_ask

  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: Use when the question concerns a specific real-world place and a packaged, citation-bearing answer is preferable to manual primitive composition. Forward the user's question verbatim as `q` plus the location as `place` (free text), `cell` (cell64), or `lat`+`lng`. The server resolves the location, classifies the question to a topic, recalls every relevant band (auto-materializing Sentinel-2 / Sentinel-1 / Cop-DEM / JRC GSW / Overture / weather on miss), surfaces the algorithm recipes that compose those bands into named scores, and returns a single envelope with `topic_routing`, `facts`, `algorithms_for_question`, an optional Sentinel-2 RGB scene URL, and a `caveats` block (grid resolution, revisit cadence). All facts are signed by the responder; the signed `receipt` (and its content-addressed `fact_cids`) is surfaced at the envelope ROOT, `response.receipt` / `response.fact_cids`, exactly like every other primitive, and is also mirrored under `facts_summary.receipt` for back-compat. Set `include_image: true` to bundle the latest cloud-free Sentinel-2 thumbnail. Out-of-scope questions return `topic_routing.matched_topic: null` plus the full inventory so the caller can route elsewhere. Example arguments: {"q":"is this neighbourhood flood-prone for a flat purchase","place":"Ashok Nagar, Ranchi"}

  shallow
• emem_echo_verify

  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:2p6sz3pv45ndkyqstir4nd6bjnzx63rrcb4pnhgahsnb2oczh5aq","claimed_value":"-0.0558"}

  shallow
• emem_entity

  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 stable handle to it that survives summarization and travels between agents/turns/LLMs, before it drifts into 'that infrastructure issue'. Anchor it with `place`, a `cell`, or `lat`+`lng`. Hand the returned `emem:entity:` token to any other agent; they dereference the identical object. Recall/ask at the entity's `cell64` for signed facts about it. Pick the right sibling: `emem_entity` MINTS or returns the identity for a thing you can anchor to a place; `emem_entity_resolve` takes a fuzzy phrase and finds an identity someone ALREADY registered, so reach for it when you suspect the thing is known and you only have words for it; `emem_entity_link` asserts that two spellings you already hold mean one object. Do NOT call this for an observation, which is a fact and belongs in emem_recall or emem_memory_token, and do not call it to name a place itself, which is emem_locate: an entity is a THING AT a place, not the place. Example arguments: {"label":"Golden Gate Bridge","kind":"bridge","place":"Golden Gate Bridge, San Francisco"}

  shallow
• emem_entity_link

  Record a signed equivalence: bind an alternate label or a stable external id (GERS / OSM / Wikidata) to an existing canonical object so future `emem_entity_resolve` calls on that phrasing converge to the same entity_cid. Builds the shared reference graph that keeps different agents' vocabularies pointing at one identity. When to use: Call when you learn that two phrasings denote the same object ('the north dam' == an existing entity), or to attach an authoritative external id to an object minted from free text. Example arguments: {"entity_token":"emem:entity:0a1b2c3d4e5f60718293","alias":"the north dam"}

  shallow
• emem_entity_resolve

  Converge a fuzzy phrasing onto the canonical object other agents already minted, so everyone co-refers to the same identity instead of re-minting divergent ones. Pass `text` (e.g. "the collapsed span at the ford") to get ranked existing candidates; pass `near` to narrow to a place; or pass an `emem:entity:` `token` to dereference it directly to the signed entity body. Read-only. When to use: Call BEFORE minting when another agent may already have registered the object, or when you receive a `emem:entity:` token and want the object behind it. This is how two agents avoid referential drift: resolve first, mint only if nothing matches. Example arguments: {"text":"the golden gate bridge","near":"San Francisco"}

  shallow
• emem_find_similar

  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 and materialises nothing, 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}

  shallow
• emem_guard_verdict

  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. Set claim_gating:true to also be told which measurable claims carry no citation at all and which emem band would answer them. Checking a payload some other framework produced (a CloudEvent, an OPA input, an OpenAI moderations body, another server's tool call)? Send it as-is and name its `shape`, because the default reader only sees `texts`/`messages` and a check that read nothing still answers allow. To ENFORCE this rather than consult it, run your own node: emem_guard_selfhost returns the procedure, and it works across Anthropic Inference hooks, Claude Code hooks, MCP tool calls, OpenAI-shaped clients, CloudEvents and OPA-style policy clients. Example arguments: {"texts":["Elevation there is 918 m per emem:fact:defi.zb493.xuqA.zcb5f:yqbolgeoycqkvj3zkxukb4bjw4odhpwvfzqo3fbgwf4spk45zala"]}

  shallow
• emem_intent

  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 user's question maps cleanly onto one of the seven rows above and you would rather state the goal than pick a primitive. Reach past it for anything else: a specific band at a cell is emem_recall, a region is emem_recall_polygon, and a free-text place question with no obvious primitive is emem_ask directly (type:"ask" here just forwards to it). `window` takes tslots, not dates: get valid ones from emem_trajectory first. A tool this router names but `tools/list` does not show is NOT a dead end: every one of the 107 dispatches by name at `/mcp` and `/mcp/full`, so call `emem_trajectory` or `emem_recall_polygon` directly. The core list is 16 to keep the per-request catalog small, not to fence the rest off; `emem_tools` enumerates them. Example arguments: {"type":"did_change","cell":"damO.zb000.xUti.zde78","band":"indices.ndvi","window":[20245,20620]}

  shallow
• emem_locate

  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: Use whenever the input refers to a real-world location and the next step needs the cell64 identifier or wants to know which bands are available before recalling. The response carries `data_at_this_cell` with three sub-fields: `live_bands_by_topic` (every band recallable here, grouped by topic such as flood_water_event_window, vegetation_condition, built_up_human_geography), `algorithms_for_topic` (composition recipes that fuse those bands into named scores), and `declared_but_no_materializer_at_this_responder` (cube slots reserved without a live connector). For the single-shot path that runs the full chain server-side and returns one packaged answer, use `emem_ask` instead. Example arguments: {"place":"Mount Everest"}

  shallow
• emem_memory_bundle

  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"}

  shallow
• emem_memory_contradictions

  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 this when trust matters before you rely on a number, 'is there disagreement about X', 'do the sources corroborate this', 'audit this claim', or 'find contradictory observations in region Y'. Use it to decide whether a fact is well-corroborated or contested. Narrow with `cell_prefix` (e.g. "defi.zb5") for a region and `band` for one family; `min_severity` filters out 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`: the likeliest real disagreement there is one signer answering from two different providers, and the default scope cannot report it. Each record names its `disagreement_scope` — `multi_attester` is two witnesses, `same_attester_provider_substitution` is one witness that changed instruments. The receipt cites every disputed CID, follow up with `emem_diff` to quantify a pair, or (with the refinement loop on) read the emitted `disagrees_with` edge via `emem_edges_recall`. Example arguments: {"cell_prefix":"damO","band":"indices.ndvi","min_severity":0.2}

  shallow
• emem_memory_token

  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 the agent wants a single rebindable string to cite a place plus an attested fact across messages, threads, agents, or tools, without re-fetching or re-describing it. Pair with `emem_verify_receipt` on the receiving end to check the signed payload. To cite an OBJECT rather than a single reading, use emem_entity's `emem:entity:` token. FOR MANY FACTS, USE emem_memory_bundle INSTEAD, and this is a measured cost rather than a style preference. Measured over 131 scalar facts at 12 places across 57 bands: a token is 84 characters and 51 LLM tokens, while the signed value it points at averages 10.9 characters and 5.4 LLM tokens. So N individual tokens cost roughly 9.5x the CONTEXT of simply pasting the N numbers (7.7x by characters; the gap is BPE fragmenting a base32 cid, and LLM tokens are the unit that bills a window), and an N-token prompt hits the context wall SOONER than the plain values would. A bundle is 38 characters and 23 LLM tokens at ANY N up to 256 and resolves in one round trip: it beats individual tokens from N=1 and beats pasting the plain values from N>=5. Individual tokens are for citing ONE fact you must be able to verify later; they are the wrong tool for carrying a set. Example arguments: {"cell":"defi.zb493.xoso.zcb6a","fact_cid":"cxjiu7l54ujzrpnekp24n4534yojpue4mprddbvevnqtti3lh5bq"}

  shallow
• emem_memory_token_resolve

  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 an agent receives a memory_token from another agent (or out of a previous turn) and wants the value behind it. Read `value` for the reading and `unit` for what it is measured in; both are always present, and an explicit null means the fact genuinely has none (`kind: "absence"` has no value, and most index bands including NDVI are dimensionless) rather than that the field is missing. For a scalar, quote `value_verbatim` instead: it is the same number as the exact decimal string it was signed as, and re-typing a JSON number is where measured precision loss comes from. The response also carries the parsed cell + fact_cid, the full `fact` body, and the stable `fact_url` an agent can hand to any other peer. 404 with a typed code if the responder doesn't hold the cid; try /v1/fetch with the cid then, or paste the token at a mirror. Example arguments: {"token":"emem:fact:defi.zb493.xoso.zcb6a:cxjiu7l54ujzrpnekp24n4534yojpue4mprddbvevnqtti3lh5bq"}

  shallow
• emem_recall

  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). Returns every Primary fact stored at that (cell, band, tslot). IMPORTANT: if the cell has no fact yet for a requested band AND that band has `has_materializer=true` (per `emem_coverage_matrix` / `emem_materializers`), the responder fetches the upstream value, signs it under its identity, persists it, and returns it in the same response (slower on the first call while the upstream is fetched; fast once cached). So for any wired band you can recall ANY cell on Earth without seeding, just pass `bands: [<band>]`. The response carries `materialize_notes` listing what was just fetched. Empty result with no notes means the band has no materializer at this responder. Example arguments: {"cell":"damO.zb000.xUti.zde78","bands":["weather.temperature_2m","copdem30m.elevation_mean"]}

  shallow
• emem_tools

  The map of emem's tool surface, and the only tool you need to find the rest. Returns the working loop in the order you walk it (name a thing, ground it, cite it, resolve it, verify it, check for drift), then every other tool grouped by the question it answers, each with its one-line trigger. Pass `name` to get one tool's full input schema and a runnable example, so you can use a tool without loading all of the descriptors into context. This endpoint advertises the core loop only; the Earth-observation, search, embedding and log tools are catalogued here and remain callable by name. When to use: Call this FIRST when you do not know which emem tool answers the question, or when you need a capability you cannot see in your tool list. This responder advertises a small core loop by default rather than its full catalog, so a tool being absent from your list does not mean it is absent from the server. Pass `q` to search by topic (`ndvi`, `cloud`, `flood`, `verify`), `name` for one tool's exact schema, or no arguments for the whole map. If you want the full catalog registered as callable tools instead, reconnect to the /mcp/full endpoint; for a one-shot answer without picking a primitive at all, use emem_ask. Example arguments: {"q":"ndvi"}

  shallow
• emem_verify_receipt

  Verify a signed receipt envelope server-side: rebuilds the canonical preimage under the rule the receipt's OWN `preimage_version` names (v2, current: tagged length-prefixed segments plus a segment binding the inclusion proof; v1: the same without that segment; absent/0: the legacy `request_id | served_at | primitive | cells, | fact_cids,` concatenation), runs ed25519 over the embedded pubkey + 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 proof so it cannot be stripped in transit, and the cost of that is that any reshaping — dropping a field, re-keying it, summarising it — invalidates the signature by design and looks exactly like tampering. Use when the in-browser /verify path is blocked (CDN offline, agent runtime has no crypto) or when you want a server-side audit of a third-party receipt. Memory algebra: the `verify` operation (https://emem.dev/docs/model.html). When to use: Pass a receipt object EXACTLY as returned by the read primitive, whole and unmodified (signature can be byte[] or sig_b32; pubkey can be byte[] or responder_pubkey_b32, the verifier tolerates those two spellings and nothing else). Do not omit `merkle_proof`, and do not reshape any field: under preimage_version 2 that returns `signature_valid: false` on data nobody tampered with. Exactly two omissions reach this failure rather than a 400: `merkle_proof` and `preimage_version` (whose absence deserialises to 0 and silently selects the v0 rule, so the inclusion proof still walks while the signature reads as forged). When this responder holds the cited fact it can tell reshaping from tampering and says so — `reason: receipt_reshaped_after_signing` with a `failure_detail` naming the field, instead of `signature_invalid` — but it never accepts such a receipt, and an offline verifier has no way to make that distinction at all. Optionally override `pubkey_b32` to assert verification against a specific signer. Returns 200 with `valid: false` when the signature fails, never 4xx for a structurally-well-formed bad signature. Example arguments: {"receipt":{"primitive":"recall","served_at":"2026-05-14T12:00:00Z","request_id":"req-1","cells":["damO.zb000.xUti.zde78"],"fact_cids":["qbq2dy7adyuvozs7s3gqg5jnpkcwq2duegltjyhbxsivuqbpjofq"],"signature":[1,2,3],"responder_pubkey":[4,5,6]}}

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/cfce5a95-5c28-4069-84fb-511347e7fb4a/badge.svg)](https://vouch.tools/servers/cfce5a95-5c28-4069-84fb-511347e7fb4a)