vortx-ai/emem/emem-field-tokens

emem-field-tokens

Network use. The commands in this skill send JSON to https://emem.dev and receive JSON or a raster file 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. The files under scripts/ read local files and make no network calls.

A world model reads a field over an area, often across time. This skill gets that field from emem as a signed artifact. Another party can fetch the same bytes again, or compute them again, and get the same hash.

Calls in this skill

Each route has an MCP tool that takes the same JSON body: emem_band_raster, emem_band_composite, emem_band_cube, emem_raster_bundle, emem_raster_resolve, emem_cube_resolve, emem_raster_bundle_resolve and emem_cells_in_bbox. These tools are not in the short tool list of the plugin. The MCP server runs them by name through tools/call. If your host calls only listed tools, or has no MCP, send the body to the REST route. The steps below use REST.

The receipt does not sign a pixel value. It signs a derivation: this responder made the artifact named artifact_cid from a pinned Sentinel-2 scene, over an area named aoi_cid, at one time slot.

When to use a different skill

Step 1: fetch one field

/v1/band_raster accepts these bands:

The band list and the caps come from crates/emem-api-rest/src/band_raster.rs. A larger window gets a refusal that gives the size and the cap. Split the area into smaller boxes. To ask for a capture date, add "observed_on": "YYYY-MM-DD". The responder pins the scene that it used in both cases.

Send this body to POST https://emem.dev/v1/band_raster:

{"bbox": {"min_lat": 32.5699, "min_lng": 77.0328, "max_lat": 32.5727, "max_lng": 77.0362}, "band": "s2.B04"}

Save the answer as raster.json. Then print a summary:

jq '{raster: .tokens.raster, artifact: .artifact.url, cid: .artifact.artifact_cid,
     grid: .grid, scene: .derivation.sources[0].id}' raster.json

On 7 November 2026 this call returned in 0.6 s at 00:56 UTC and in 1.3 s at 02:56 UTC:

Each call signs and stores a new derivation record. The record contains its signing time, so each call gives a new derivation_cid and a new token. The artifact_cid stays the same while the scene stays the same. Both tokens resolve. To compare two rasters, compare their artifact_cid values, not their tokens.

Without a date, the responder picks a recent usable scene. When a newer scene arrives, the artifact_cid changes too.

Step 2: download the bytes and hash them again

Download the file at artifact.url. No MCP tool returns the bytes. Send a GET to https://emem.dev/v1/artifacts/77zgrf4hiv4cnzqblgkttrg4jssvh5sghhvdqjjq3wnj77nmgpma and save the bytes as artifact.bin. Then hash them again:

python3 "${CLAUDE_SKILL_DIR}/scripts/rehash.py" 77zgrf4hiv4cnzqblgkttrg4jssvh5sghhvdqjjq3wnj77nmgpma artifact.bin

Use your own artifact_cid from step 1 in the URL and in the command. ${CLAUDE_SKILL_DIR} is the directory of this skill. Claude Code sets it.

On 7 November 2026 the file was 4160 bytes and rehash.py printed MATCH. With a different cid, it printed MISMATCH. rehash.py gets BLAKE3 from scripts/emem_crypto.py, which ships with this skill. It is plain Python with no third-party packages. rehash.py --self-test checks it against the official test vectors.

The file format is application/x.emem-grid-f32.v1. It has a 64-byte header, then a little-endian f32 array. The header starts with the magic EMEMGRD1, then width, height, epsg, nodata, the origin and the steps. NaN is nodata. A 32 x 32 grid is 64 + 32 x 32 x 4 = 4160 bytes.

Step 3 (optional): get a cloud-free composite

/v1/band_composite takes the median of one Sentinel-2 band over a date window. It removes cloud pixels by their scene class first.

Send this body to POST https://emem.dev/v1/band_composite:

{"bbox": {"min_lat": 32.5699, "min_lng": 77.0328, "max_lat": 32.5727, "max_lng": 77.0362},
 "band": "s2.B04", "start_date": "2026-06-01", "end_date": "2026-06-30", "max_scenes": 4}

Save the answer as composite.json. Then print a summary:

jq '{raster: .tokens.raster, members: .member_count, window, grid}' composite.json

max_scenes is 2 to 16, and the default is 12. min_valid_count (default 1) sets how many clear samples a pixel needs. On 7 November 2026 this call used 4 scenes and returned in 1.4 s. The result has the same shape as a band_raster result. Check it with steps 2 and 5.

Step 4 (optional): fetch the field at several dates

Send this body to POST https://emem.dev/v1/band_cube:

{"bbox": {"min_lat": 32.5699, "min_lng": 77.0328, "max_lat": 32.5727, "max_lng": 77.0362},
 "band": "s2.B08", "observed_on": ["2026-05-15", "2026-06-15", "2026-07-15"]}

Save the answer as cube.json. Then print the members:

jq '{cube: .tokens.cube, count: .member_count,
     members: [.derivation.members[] | {tslot, scene: .scene_id, requested_dates,
               distance: .requested_date_distance_days, raster: .raster_token}]}' cube.json

A cube contains no new pixels. It is a signed list of member_count raster slices, one for each scene. You can resolve each slice alone. If two dates map to the same scene, they become one member. Each member gives its requested_dates and the distance in days to its scene. cube_cid is the BLAKE3 of the ordered member derivation cids.

On 7 November 2026 this call returned three members:

A cube member is not a reading on the requested day. When you report a member, give the requested date and the distance.

Step 5: check a token that you received

For a raster token, send it with spot_check to POST https://emem.dev/v1/raster/resolve:

{"token": "emem:raster:tllufj6jxg3cpuucznj4h75ng3lelg2ki3yb5whw6ggdkzt2gocq:s2.B04:20761:2w5daw7ir2r53u7to6rrz7pcuwa2aj6g2n2ujmkkmw4iwihkj5bq", "spot_check": true}

Read resolved, artifact.url, receipt.field, spot_check.passed and spot_check.anchors in the answer.

On 7 November 2026 this returned resolved: true, passed: true and anchors: 5.

For a cube token, send {"token": "emem:cube:..."} to /v1/cube/resolve. Read resolved and member_tokens. On 7 November 2026 the cube from step 4 resolved with 3 member tokens.

The responder checks each part of the token against the signed record before it reads the artifact. If the area, band or date does not match, you get HTTP 409. For example, a raster token with s2.B08 in place of s2.B04 returned:

{"code":"invalid_argument","message":"token band `s2.B08` contradicts the signed record's `s2.B04`; refusing to dereference a forged or corrupt handle","schema":"emem.error.v1"}

To check the receipt signature offline, use `emem-verify-receipt` on raster.json. On 7 November 2026 it printed VALID, primitive emem.band_raster, with the FIELD segment bound.

Step 6 (optional): put several rasters in one set

Send 2 to 64 raster tokens to POST /v1/raster_bundle:

{"tokens": ["emem:raster:<aoi>:s2.B04:<tslot>:<cid>", "emem:raster:<aoi>:s2.B08:<tslot>:<cid>"],
 "purpose": "NDVI inputs"}

The result has an emem:rasterset: token. Check it with /v1/raster_bundle/resolve. This call stores a new bundle record on the responder, so this page does not show a live run.

List the cells in an area

Send this body to POST https://emem.dev/v1/cells_in_bbox:

{"bbox": {"min_lat": 32.5699, "min_lng": 77.0328, "max_lat": 32.5727, "max_lng": 77.0362}, "page_size": 1024}

Read total, count, next_cursor and the first entry of cells[] in the answer.

On 7 November 2026 this box had total: 1394 cells. The first page had 1024 cells and next_cursor: 1024. Send "cursor": <next_cursor> to get the next page. Stop when next_cursor is null. You can send each page to POST /v1/recall_many with a budget_ms. This call reads no facts and returns no receipt.

Limits and failures