Vectors

Basis

Distributed vector store for approximate-nearest-neighbor search over high-dimensional embeddings, backed by an immutable Strand log.

What Basis is

Basis is a vector index that stores (uuid, Vec<f32>) entries and answers approximate-nearest-neighbor (ANN) queries using HNSW (Hierarchical Navigable Small World) graphs. Two Strand logs back every Basis instance:

A vector strand holds the canonical VectorEntry::Add / VectorEntry::Remove history. This is the source of truth.
An index strand is reserved for checkpoints; saving and restoring HNSW snapshots is not implemented.

The vector records can be transported through a separately configured Strand integration. The Basis graph itself is local and is not rebuilt automatically after restart or remote updates.

Current boundary: restart creates an empty index, snapshots are a stub, and present-id removal can deadlock. See recovery limitations.

When to use Basis

Workload	Basis fit
Semantic memory for an agent (`embed(text) → ANN`)	Strong
Recommendation by embedding similarity	Strong
Retrieval-augmented generation (RAG)	Strong
Exact-distance retrieval	Use a different index — Basis is approximate
Mutable embeddings with deletes	Present-id removal can deadlock; use only after runtime repair and verification

Index parameters

The current build pins two HNSW parameters at compile time:

Parameter	Value	Meaning
`M`	`12`	Max neighbors per node in the upper layers
`M0`	`24`	Max neighbors per node in the base layer
`ef` (search width)	`max(k, 24)`	Set per query in `search()`

Distance is L2 (Euclidean), encoded as a u32 bit pattern of an f32 so HNSW can order it.

At a glance

Field	Value
Crate/package	`weave-basis`
Version	`0.1.0`
Source	`models/basis`
Backing log	Two `strand::Strand` instances
Index	`hnsw::Hnsw<Point, StdRng, 12, 24>`
Distance metric	L2, `f32` → `u32` ordering
Async	`tokio`