k-NN over the corpus by embedding
emem_find_similarFind 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}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | How many neighbours to return. | |
| key | Yes | cell64 (look up that cell's vector) or 'inline:[x,y,...]' literal vector | |
| band | No | vector band to scan (default: 128-D Tessera foundation embedding). For mode=hamming/hamming_then_rerank you can pass either the cosine band (e.g. 'geotessera') or its binary sibling ('geotessera.bin128'), the responder picks the right one. | geotessera |
| cell | No | Alias for `key`. | |
| mode | No | Scoring mode. cosine = fp32 over full vector (precise, ~256 B/cell scan). hamming = sign-bit popcount over the binary sibling band (~16 B/cell, ~1000× faster, ~65% recall@10). hamming_then_rerank = triage with Hamming on 4·k candidates then re-rank by cosine, matches cosine precision at ~16× less work. | cosine |
| scope | No | Multi-tenant scope `{user_id, agent_id, run_id, org_id}`. Setting it bypasses the ANN index entirely, because that index carries no scope column, and runs the brute-force scan instead: the tenant filter is honoured truthfully, and the call is slower. | |
| cell64 | No | Alias for `key`. | |
| filter | No | Claim-algebra predicate evaluated against every candidate before ranking. A cell with no fact for the filter's band is DROPPED rather than treated as false, so 'places like X where NDVI > 0.5' never silently includes cells with no NDVI. | |
| as_of_tslot | No | Bi-temporal valid-time bound. Applied to candidate cells BEFORE cosine scoring, a cell with no fact whose tslot ≤ as_of_tslot under the scoring band is dropped from the candidate pool (undecidable→drop). When set, the Lance ANN fast-path is bypassed (the index has no signed_at column); brute-force k-NN runs instead so as_of is honoured truthfully. | |
| as_of_signed_at | No | Bi-temporal transaction-time bound (RFC 3339). Also applied to candidates BEFORE cosine. Same Lance-bypass note as as_of_tslot. |