Struct HnswIndex 

pub struct HnswIndex { /* private fields */ }

HNSW vector index backed by hnsw_rs.

Each collective gets its own HnswIndex instance, providing complete data isolation between collectives.

Persistence Strategy

Metadata (ID mappings, deleted set) is persisted to a JSON .hnsw.meta file. The graph itself is rebuilt from redb embeddings on open, because hnsw_rs::HnswIo::load_hnsw has lifetime constraints that create self-referential struct issues. The graph dump files (via file_dump) are saved for future optimization but not currently loaded.

Implementations

impl HnswIndex

pub fn new(dimension: usize, config: &HnswConfig) -> Self

Creates a new empty HNSW index.

Arguments

• dimension - Expected embedding dimension (validated on insert)
• config - HNSW tuning parameters

pub fn insert_experience( &self, exp_id: ExperienceId, embedding: &[f32], ) -> Result<()>

Inserts an experience embedding into the index.

Assigns a new internal usize ID and records the mapping. If the ExperienceId is already present, this is a no-op.

pub fn delete_experience(&self, exp_id: ExperienceId) -> Result<()>

Marks an experience as deleted in the index.

The vector remains in the graph but is excluded from search results via filtered search. Returns Ok even if the experience is not in the index (idempotent).

pub fn search_experiences( &self, query: &[f32], k: usize, ef_search: usize, ) -> Result<Vec<(ExperienceId, f32)>>

Searches for the k nearest experiences, excluding deleted ones.

Returns (ExperienceId, distance) pairs sorted by distance ascending (closest first). Distance is cosine distance: 0.0 = identical, 2.0 = opposite.

pub fn contains(&self, exp_id: ExperienceId) -> bool

Returns true if the given experience is in the index (and not deleted).

pub fn active_count(&self) -> usize

Returns the number of active (non-deleted) vectors.

pub fn total_count(&self) -> usize

Returns the total number of vectors (including deleted).

pub fn restore_deleted_set(&self, deleted_exp_ids: &[String]) -> Result<()>

Restores the deleted set from persisted metadata.

Called during PulseDB::open() after rebuilding the graph from redb. Accepts ExperienceId UUID strings and maps them to the current internal IDs (which may differ from the previous session’s IDs after a rebuild).

pub fn save_to_dir(&self, dir: &Path, name: &str) -> Result<()>

Saves index metadata to a JSON file.

Creates {dir}/{name}.hnsw.meta with ID mappings and deleted set. Also attempts to save the HNSW graph via file_dump for future optimization (graph loading is not yet implemented due to lifetime constraints in hnsw_rs).

pub fn rebuild_from_embeddings( dimension: usize, config: &HnswConfig, embeddings: Vec<(ExperienceId, Vec<f32>)>, ) -> Result<Self>

Rebuilds an index from a set of embeddings.

Used during PulseDB::open() to reconstruct the HNSW graph from embeddings stored in redb (the source of truth).

pub fn remove_files(dir: &Path, name: &str) -> Result<()>

Removes HNSW files for a collective from disk.

Trait Implementations

impl VectorIndex for HnswIndex

fn insert(&self, id: usize, embedding: &[f32]) -> Result<()>

Inserts a single vector with the given ID.

fn insert_batch(&self, items: &[(&Vec<f32>, usize)]) -> Result<()>

Inserts a batch of vectors.

fn search( &self, query: &[f32], k: usize, ef_search: usize, ) -> Result<Vec<(usize, f32)>>

Searches for the k nearest neighbors to the query vector.

fn search_filtered( &self, query: &[f32], k: usize, ef_search: usize, filter: &(dyn Fn(&usize) -> bool + Sync), ) -> Result<Vec<(usize, f32)>>

Searches with a filter predicate applied during traversal.

fn delete(&self, id: usize) -> Result<()>

Marks an ID as deleted (soft-delete).

fn is_deleted(&self, id: usize) -> bool

Returns true if the given ID is marked as deleted.

fn len(&self) -> usize

Returns the number of active (non-deleted) vectors.

fn save(&self, dir: &Path, name: &str) -> Result<()>

Persists index metadata to disk.

fn is_empty(&self) -> bool

Returns true if the index has no active vectors.