vortx-ai/emem/emem-find-similar

emem-find-similar

Network use. The commands in this skill send JSON to https://emem.dev and receive JSON from it. https://emem.dev is the service that the MCP server of the plugin connects to. The commands do not execute what they download. This skill ships no scripts. Its commands read no environment variable, key or credential. The only local files that they read are files that an earlier step saved from https://emem.dev.

The skill runs a nearest-neighbour search over a stored 128-D embedding of surface texture. The embedding comes from Sentinel-1 SAR and Sentinel-2 optical data, one vector for each year. Two cells with a cosine above about 0.85 usually show the same type of surface.

Read this before you promise an answer

emem.dev retired the embedding band (geotessera). The responder serves the vectors that it stored before. It computes no new vectors.

Coverage is what the responder stored before the retirement. It is dense near places that people asked about, and empty in other areas.

"No analogue found" and "this place has no vector" are different answers. Report only the answer that you got.

When to use a different tool

Step 1: get the seed cell

Call emem_locate with:

{"q": "Bengaluru, India"}

Without MCP, send the same body to POST https://emem.dev/v1/locate. Read cell64 and via in the answer.

Keep the cell64. On 7 November 2026 this call returned defi.zb493.zezo.zcb35. For a coordinate, send {"lat": -44.123, "lng": -120.456} in place of q.

Step 2: run the search

Call emem_find_similar. Put the seed cell in key. The tool also accepts cell as another name for key.

{"key": "defi.zb493.zezo.zcb35", "k": 5}

Without MCP, send the same body to POST https://emem.dev/v1/find_similar. Save the answer as sim.json, also when it is an error. Here a refusal is an answer.

Over MCP, save the JSON text of the tool result as sim.json. A refusal comes back as a tool error, and its message names the code, for example cid_not_found.

Do not use recall to test for a vector first. On 28 September 2026, a Timbuktu seed got no geotessera fact from /v1/recall, only a retired-band note. But /v1/find_similar answered from its stored vector. Thus recall is not a reliable test. cid_not_found from find_similar is.

Step 3: read the answer

Print the error, or the neighbours:

jq 'if .code then {code, message}
    else [.neighbors[] | {cell, score, place: .place_label_cached, lat, lng}] end' sim.json

Recorded runs

At 02:50 UTC on 7 November 2026, both runs gave the same results again. The Bengaluru call answered in 0.13 s. To check the receipt without a local verifier, send it to the server:

jq -c '{receipt}' sim.json > verify_req.json

Send verify_req.json as the body of POST https://emem.dev/v1/verify_receipt and read valid in the answer.

That call returned "valid": true. The cid_not_found message also names geotessera in its list of bands for the cell. That list does not mean that a vector exists. The 404 is the answer.

Options

A hamming score is 1 - 2 * distance / 128, with the distance in bits (crates/emem-primitives/src/find_similar.rs). It is not on the cosine scale. Do not apply the 0.85 rule to it. On 7 November 2026 the Bengaluru seed got a top hamming score of 0.625.

Do not pass band: "geotessera.bin128". On 28 September 2026 it returned an internal error.

The year and hamming options can be slow. On 7 November 2026, the first call with geotessera.2018 and the first call with hamming both returned HTTP 504 compute_timeout after 40 s. The same calls then answered in 5 s and 9 s. The multi_year call took 38 s. After a compute_timeout, send the same call one more time. If it fails again, run it as a task, as the error message tells you.

Pitfalls

• Near is not similar. The top neighbours of a city cell are often

other cells of the same city. Ask for a larger k. Then remove neighbours that are near the seed if the user wants other places.

• The match is about the surface. A "similar" city has the same

density, vegetation and water as seen from space. It can be very different in other ways.

• The cosine thresholds are approximate. Above 0.85 means the same

type of surface, 0.7 to 0.85 means related, and below 0.7 means weak. The correct cutoff changes with the seed.

Before you report the neighbours

A similarity is a rank over a frozen index. It is not a measurement. Give each neighbour with its cell64 and score. Tell the user that the responder adds no new vectors. For each claim about a neighbour, recall that cell and cite the band facts. See `emem-referential-drift` and `emem-verify-before-publish`.