# ANNex

> Fast hybrid vector search, built in Rust. Rust-native vector search engine with hybrid dense-sparse retrieval, multivector support, and a recall-latency frontier that outpaces hnswlib up to 96% recall.

ANNex is an embeddable vector search engine written in Rust. It implements HNSW for approximate nearest neighbor search with payload filtering, BM25/sparse retrieval, hybrid dense-sparse fusion (RRF), multivector / ColBERT-style late interaction, snapshots and a write-ahead log. Embeddings are supplied by the caller.

- Version: 0.3.0 (latest release; history: https://annexsearch.dev/changelog.md)
- License: Apache-2.0 OR MIT
- Source: https://github.com/rosharma719/ANNex
- Docs: https://docs.rs/annex
- Canonical: https://annexsearch.dev/

```sh
cargo add annex      # Rust (crate: annex v0.3.0)
pip install ANNexDB  # Python bindings
```

## Headline benchmark

0.18 ms p50 latency at 0.836 recall, 5,424 QPS (m16+rcm+sq8, ef=32, single thread; NYT256, 290K docs, 256-D angular, EC2, 2026-10-01). Hybrid retrieval quality: macro nDCG@10 0.440 on 5 BEIR corpora, parity with Qdrant and LanceDB (not a proven advantage). Full tables, methodology and downloadable data: https://annexsearch.dev/benchmarks.md

## Capabilities

| Capability | ANNex | Qdrant | FAISS | hnswlib |
|---|---|---|---|---|
| Dense vector search | yes | yes | yes | yes |
| Sparse / BM25 | yes | yes | no | no |
| Hybrid RRF fusion | yes | yes | no | no |
| Multivector / ColBERT | yes | yes | no | no |
| Payload filters | yes | yes | no | no |
| Embedded (no server) | yes | no | yes | yes |
| HTTP server | yes | yes | no | no |
| Rust-native library | yes | no | no | no |
| Python bindings | yes | yes | yes | yes |
| Snapshots + WAL | yes | yes | no | no |

## When to choose ANNex

- You want an embeddable library: no server process, no network hop, integrated directly into your Rust binary.
- You need dense and sparse retrieval in one index, with hybrid fusion (RRF), payload filters, or multivector / ColBERT-style late interaction.
- You want snapshots and a write-ahead log built in, with Python bindings (NumPy batch search) for the read path.

## When to look elsewhere

- You need a managed cloud service, SLAs or vendor support. ANNex is self-hosted only.
- You need distributed or sharded search across several nodes. ANNex is single-node.
- You need GPU acceleration, or a system hardened for production at scale. ANNex v0.3.0 is for development, evaluation and early-stage applications.

## Quickstart

Bring your own embeddings: ANNex stores and searches the vectors you give it. These three steps run as written against the published packages.

Requirements:
- Python 3.9+ and NumPy, for step 1
- Rust 1.98 or newer (the annex crates require it), for steps 2 and 3

### 1. Build and search from Python

Build an index from a NumPy array, search it, and save it. No Rust needed.

Install:

```sh
python -m pip install ANNexDB numpy
```

build_search.py:

```python
import annexdb
import numpy as np

# One row per item: your embeddings, float32.
vectors = np.array(
    [
        [0.9, 0.1, 0.0, 0.0],
        [0.8, 0.2, 0.1, 0.0],
        [0.0, 0.1, 0.9, 0.2],
        [0.1, 0.0, 0.8, 0.3],
    ],
    dtype=np.float32,
)

index = annexdb.Index.build(vectors, metric="cosine")  # row i gets id i

query = np.array([0.85, 0.15, 0.05, 0.0], dtype=np.float32)
ids, scores = index.search(query, k=3)
for i, s in zip(ids, scores):
    print(f"id={i} score={s:.4f}")

index.save("segment.bin")  # a snapshot Rust can load too
```

Output:

```
id=0 score=0.0037
id=1 score=0.0044
id=3 score=0.8319
```

- For cosine, the score is a distance (1 − cosine similarity), so lower is closer. `dot` is a similarity (higher is closer) and `euclidean` is squared distance (lower is closer).
- The Python package does dense vector search: build, search, save and load. For hybrid search, payload filters and multivector search, use the Rust library (step 2) or the HTTP server (step 3).

### 2. Search and filter from Rust

Build a small cosine index, search it, filter on a payload field, and save a snapshot.

Cargo.toml:

```toml
[dependencies]
annex = "0.3.0"
```

src/main.rs:

```rust
use std::collections::HashMap;

use annex::{DistanceMetric, Filter, Payload, PayloadValue, Segment};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // A tiny 4-dimensional cosine index: M=16, ef=64 (the build width, also the default search width), level cap 16.
    let mut seg = Segment::with_config(DistanceMetric::Cosine, 16, 64, 16, 4);

    // (id, vector, topic): you bring the embeddings, ANNex stores and searches them.
    let docs = [
        (1, [0.9, 0.1, 0.0, 0.0], "pets"),
        (2, [0.8, 0.2, 0.1, 0.0], "pets"),
        (3, [0.0, 0.1, 0.9, 0.2], "cars"),
        (4, [0.1, 0.0, 0.8, 0.3], "cars"),
    ];
    for (id, vector, topic) in docs {
        let mut payload = Payload(HashMap::new());
        payload.set("topic", PayloadValue::Str(topic.into()));
        seg.insert_with_id(id, vector.to_vec(), Some(payload))?;
    }

    // Nearest neighbours of a query that looks like the "pets" documents.
    let query = vec![0.85, 0.15, 0.05, 0.0];
    for hit in seg.search(&query, 3)? {
        println!("id={} score={:.4}", hit.id, hit.raw_score);
    }

    // The same search, restricted by a payload filter.
    let cars = Filter::Match { key: "topic".into(), value: PayloadValue::Str("cars".into()) };
    println!("-- topic = cars");
    for hit in seg.search_with_filter(&query, 2, Some(&cars))? {
        println!("id={} score={:.4}", hit.id, hit.raw_score);
    }

    // Persist it. The Python bindings load this file.
    seg.save_to_path("segment.bin")?;
    println!("saved segment.bin");
    Ok(())
}
```

Output:

```
id=1 score=0.0037
id=2 score=0.0044
id=4 score=0.8319
-- topic = cars
id=4 score=0.8319
id=3 score=0.9252
saved segment.bin
```

- For cosine, the score is a distance (1 − cosine similarity), so lower is closer. Ids 1 and 2 are the near neighbours of this query.
- Cargo.toml: `annex = "0.3.0"` also accepts later 0.3.x releases. The snapshot is the same format the Python package writes: `Segment::load_from_path("segment.bin")` opens the file from step 1.

### 3. Hybrid search over HTTP

Combine keyword (BM25) and vector search with a metadata filter in one request. Start the server, add three documents, query.

Start the server:

```sh
# Install and start the HTTP server (compiles from source, so the first install takes a few minutes)
cargo install annex-multivector
annex-multivector --dimension 2 --centroids 2 --path ./data --listen 127.0.0.1:8080
```

Add documents (text, metadata and a dense vector each):

```sh
curl localhost:8080/v1/vectors/upsert -H 'content-type: application/json' -d '{"documents":[
  {"id":"runbook-e123","text":"E123 recovery procedure for the payments service",
   "metadata":{"team":"support"},"representations":{"semantic":{"kind":"dense","vector":[1,0]}}},
  {"id":"backup-restore","text":"How to restore a database from a backup",
   "metadata":{"team":"support"},"representations":{"semantic":{"kind":"dense","vector":[0.9,0.1]}}},
  {"id":"holiday-policy","text":"Office holiday schedule and leave policy",
   "metadata":{"team":"hr"},"representations":{"semantic":{"kind":"dense","vector":[0,1]}}}
]}'
```

Query: BM25 + dense, only team = support:

```sh
curl localhost:8080/v1/retrieve -H 'content-type: application/json' -d '{
  "prefetch": [
    {"kind":"bm25","text":"E123 recovery"},
    {"kind":"dense","field":"semantic","vector":[0.95,0.05]}
  ],
  "filter": {"op":"eq","field":"team","value":"support"},
  "limit": 3
}'
```

Response (trimmed to id, score and sources):

```json
{"matches": [
  {"id": "runbook-e123",   "score": 0.18181819,  "sources": [0, 1]},
  {"id": "backup-restore", "score": 0.083333336, "sources": [1]}
]}
```

- `runbook-e123` matches both the exact term "E123" and the vector, so both channels return it and it ranks first. `backup-restore` is found by the vector alone. `holiday-policy` is excluded by the filter.
- `sources` lists which `prefetch` entries found each document (0 = BM25, 1 = dense). Scores are fused with reciprocal rank fusion (RRF). The full response also includes each document's text, metadata and a timing trace.

API docs: https://docs.rs/annex. HTTP API reference: https://github.com/rosharma719/ANNex/blob/master/crates/annex-multivector/README.md

## Errata and known gaps

These are real constraints, not caveats.

- **No managed cloud.** ANNex is self-hosted only. There is no hosted offering or managed service. You run and operate it.
- **Single-node.** No distributed or sharded mode. All data lives on one machine. Horizontal scaling is not supported in v0.3.0.
- **Production hardening in progress.** ANNex is well-suited for development, evaluation, and early-stage applications. The benchmark policy and RESULTS.md are explicit about what has and has not been established.
