Memo::USearchIndex
USearch HNSW index management for fast approximate nearest neighbor search.
Wraps USearch index lifecycle: file naming, open/save/close, type conversion, and vector operations. All Float64↔Float32 conversion happens here.
One index per service (isolated vector spaces). Index files are named by service format, model, and dimensions: memo.openai--text-embedding-3-small--1536.usearch
Constants
Default directory for index files when no db_path is available (e.g., PostgreSQL backend). Follows XDG Base Directory spec, with fallback to /var/lib/memo/indices for system users.
Instance methods
Add a vector to the index.
Key is the embedding rowid (SQLite rowid or PostgreSQL eid). Embedding is converted from Float64 to Float32 at this boundary.
Path of the journal checkpoint saved beside an index file.
Delete the index file (and its journal checkpoint and lock) from disk.
Exact nearest neighbors among keys, comparing the query with each.
Faster than filtered_search when the keys are few: HNSW explores much of its graph to find matches that sparse.
Search with a filter predicate on keys.
Only results where the filter block returns true are included. Use this with a Set of valid rowids from SQL pre-filtering.
Retrieve a vector from the index by key.
Returns Float64 array for compatibility with the rest of Memo, or nil if the key doesn't exist.
Build the index file path from a database path.
Path: {db_dir}/{db_stem}.{format}--{model}--{dimensions}.usearch Path-unsafe characters in format/model are replaced with hyphens.
Build the index file path from an explicit directory.
Path: {dir}/{stem}.{format}--{model}--{dimensions}.usearch If no stem is provided, uses "memo" as default.
Load the index at path, or create an empty one when the file is
missing or can't be loaded (corrupt, wrong dimensions). Returns the
index and whether it was loaded from the file.
Lock the index at path for this process, or raise InUse. Two holders
of one index would each keep their own copy in memory and overwrite
each other's saves, so a second open fails instead. The lock lasts
until the returned file is closed or the process exits (a crash
included).
Open or create a USearch index at a specific path.
If the index file exists on disk, loads it. Otherwise creates a new empty index with cosine metric and f16 quantization.
Save the index to disk.
Writes a temporary file and renames it over path, so a crash
mid-save leaves the previous file intact.
Save on a separate system thread, suspending only the calling fiber.
Writing a large index takes seconds (it's one blocking call), and on a single-threaded runtime that would freeze every other fiber. Searches can run meanwhile (they only read the index); the caller must keep writers out until this returns.
Search for k nearest neighbors (unfiltered).
Returns USearch::SearchResult array with keys and distances. Cosine distance = 1 - similarity, so similarity = 1 - distance.