k-NN over the corpus by embedding
emem_find_similark-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}
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. |