module Memo::USearchIndex

Overview

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 stored alongside the SQLite database, prefixed with the DB filename stem: memo.openai--text-embedding-3-small--1536.usearch

Extended Modules

Defined in:

memo/usearch_index.cr

Instance Method Summary

Instance Method Detail

def add(index : USearch::Index, key : UInt64, embedding : Array(Float64)) #

Add a vector to the index.

Key is the SQLite rowid from the embeddings table. Embedding is converted from Float64 to Float32 at this boundary.


[View source]
def close(index : USearch::Index, db_path : String, format : String, model : String, dimensions : Int32) #

Save and close the index, freeing resources.


[View source]
def delete_file(db_path : String, format : String, model : String, dimensions : Int32) #

Delete the index file from disk.


[View source]
def filtered_search(index : USearch::Index, query : Array(Float64), k : Int32, &filter : UInt64 -> Bool) : Array(USearch::SearchResult) #

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.


[View source]
def get_vector(index : USearch::Index, key : UInt64) : Array(Float64) | Nil #

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.


[View source]
def index_path(db_path : String, format : String, model : String, dimensions : Int32) : String #

Build the index file path for a service.

Path: {db_dir}/{db_stem}.{format}--{model}--{dimensions}.usearch Path-unsafe characters in format/model are replaced with hyphens.


[View source]
def open(db_path : String, format : String, model : String, dimensions : Int32) : USearch::Index #

Open or create a USearch index for a service.

If the index file exists on disk, loads it. Otherwise creates a new empty index with cosine metric and f16 quantization.


[View source]
def remove(index : USearch::Index, key : UInt64) #

Remove a vector from the index by key.


[View source]
def save(index : USearch::Index, db_path : String, format : String, model : String, dimensions : Int32) #

Save the index to disk.


[View source]
def search(index : USearch::Index, query : Array(Float64), k : Int32) : Array(USearch::SearchResult) #

Search for k nearest neighbors (unfiltered).

Returns USearch::SearchResult array with keys and distances. Cosine distance = 1 - similarity, so similarity = 1 - distance.


[View source]
def to_f32(embedding : Array(Float64)) : Array(Float32) #

Convert Float64 array to Float32 array for USearch.


[View source]