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 holds checkpoints of the in-memory HNSW graph so a cold start does not rebuild from scratch.

Because Basis writes through a Strand, every change is signed, sequenced, and replicable to peers using the standard weave-dht and weave-swarm paths.

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 frequent overwrites	Acceptable, but each remove forces an index rebuild

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`