NumPy Vector Store

A fast, lightweight, zero-setup in-memory vector store powered by NumPy.

• Tiny local vector search for projects that do not need a vector database
• Fast exact vector search using vectorized NumPy operations
• Simple typed API returning VectorHit(index, value, metadata)
• Composable filtering by passing prefiltered row indexes with within_rows
• Portable persistence as trusted local .npz files with vectors + metadata
• No framework opinions: bring your own embeddings, chunking, async, and metadata model

Why?

This library is purpose-built for small to medium-scale vector search tasks and offers a simple alternative to heavyweight vector databases when you do not need network services, indexing infrastructure, ingestion pipelines, or domain-specific metadata filtering.

When/Where?

Below are benchmark results for cosine similarity search to help you assess its suitability for your use case.

Benchmarks performed on Apple M2 hardware.

Installation

uv add numpy-vector-store

Quick Start

import numpy as np
from numpy_vector_store import VectorStore

store = VectorStore[dict[str, str]](dimensions=3)

store.add(
    vectors=np.array([
        [1.0, 0.0, 0.0],
        [0.0, 1.0, 0.0],
        [0.0, 0.0, 1.0],
    ]),
    metadata=[
        {"title": "x-axis"},
        {"title": "y-axis"},
        {"title": "z-axis"},
    ],
)

hits = store.cosine_search(
    query=np.array([0.9, 0.1, 0.0]),
    top_k=2,
)

for hit in hits:
    print(f"{hit.metadata['title']}: {hit.value:.3f}")

metadata is an outer sequence with one opaque payload for each vector row. Each payload can be a dict, dataclass, tuple, list, string, integer row ID, or another Python object that fits your application. Tuple and list payloads remain single row values rather than being interpreted as additional array dimensions.

Normalization

VectorStore defaults to normalize=True, which scales each stored vector to length 1. Normalization preserves vector direction while discarding magnitude:

[3.0, 4.0] -> [0.6, 0.8]

This is the default because it makes cosine similarity fast and direction-only, which is the common case for semantic embeddings. Use normalize=False when vector length matters, such as when magnitude encodes strength, confidence, counts, scale, or raw geometry.

Zero vectors are rejected when normalize=True because they cannot be scaled to unit length. Raw stores accept zero vectors for dot-product and Euclidean search. Because cosine similarity is undefined for zero vectors, cosine_search raises an error when its selected rows include one; use within_rows to exclude zero rows when needed.

Numerical inputs

Stored vectors use float32 to keep the store compact. Vectors and queries must remain finite when converted to float32, and search thresholds must also be finite. Invalid values are rejected before they can affect stored state or ranking.

Norms and raw metric values use float64 accumulation where float32 intermediate calculations could overflow or underflow. This allows finite float32 vectors across the representable magnitude range to be normalized and compared reliably.

Search Methods

Use cosine_search for semantic embeddings and direction-only similarity:

hits = store.cosine_search(query, top_k=10, min_value=0.75)

Use dot_search with normalize=False when larger-magnitude vectors should rank higher:

store = VectorStore[dict[str, str]](dimensions=3, normalize=False)
store.add(vectors, metadata)
hits = store.dot_search(query, top_k=10, min_value=0.0)

Use euclidean_search with normalize=False for raw coordinate or feature-space nearest-neighbor search:

store = VectorStore[dict[str, str]](dimensions=3, normalize=False)
store.add(vectors, metadata)
hits = store.euclidean_search(query, top_k=10, max_value=1.5)

Prefiltering

The store does not implement a metadata query language. To filter by metadata, produce row indexes first, then pass them with within_rows.

rows = [
    i
    for i, metadata in enumerate(store.metadata)
    if metadata["title"].startswith("x")
]

hits = store.cosine_search(query, top_k=10, within_rows=rows)

Searches without within_rows compute directly against the stored vector matrix and do not make a full copy of it. A filtered search gathers the selected rows into a temporary matrix, so its additional memory use scales with the number of selected rows and the vector dimensions. Omit within_rows when every row should be searched; passing every row explicitly would create an unnecessary full-size temporary matrix.

For structured NumPy metadata, use NumPy to produce the row indexes:

metadata_table = np.array(
    [
        ("intro", "A", 2024),
        ("setup", "A", 2023),
        ("guide", "B", 2024),
    ],
    dtype=[("title", "U20"), ("product", "U10"), ("year", "i4")],
)

store = VectorStore[int](dimensions=3)
store.add(vectors, metadata=np.arange(len(metadata_table)))

mask = (metadata_table["product"] == "A") & (metadata_table["year"] >= 2024)
rows = np.flatnonzero(mask)

hits = store.cosine_search(query, within_rows=rows)

for hit in hits:
    row = metadata_table[hit.metadata]
    print(row["title"], hit.value)

Persistence

Pass a file_path and call save() / load() explicitly:

store = VectorStore[dict[str, str]](dimensions=1536, file_path="vectors.npz")
store.add(embeddings, metadata)
store.save()

loaded = VectorStore[dict[str, str]](dimensions=1536, file_path="vectors.npz")
loaded.load()

The .npz suffix may be omitted. An extensionless path such as "vectors" is resolved to "vectors.npz" for both saving and loading.

If you save with normalize=False, load with normalize=False too:

store = VectorStore[dict[str, str]](
    dimensions=1536,
    file_path="raw-vectors.npz",
    normalize=False,
)
store.add(raw_vectors, metadata)
store.save()

loaded = VectorStore[dict[str, str]](
    dimensions=1536,
    file_path="raw-vectors.npz",
    normalize=False,
)
loaded.load()

Context manager usage auto-saves on exit:

with VectorStore[dict[str, str]](dimensions=1536, file_path="vectors.npz") as store:
    store.add(embeddings, metadata)

Persistence uses a minimal NumPy .npz contract with vectors and metadata arrays. The .npz file does not encode the normalize setting; choose the same setting when loading that you used when saving. Loading validates shape, dimensions, row counts, and zero-norm vectors. A load() call made before the file exists can be retried after the file is created. Repeated calls after a successful load do nothing unless clear() resets the in-memory store. Opaque metadata values remain individual row payloads across save/load round trips. Persistence uses allow_pickle=True for flexible Python metadata payloads, so only load files generated by your own application or another trusted local process. Loading untrusted .npz files is not a supported security model.

Compatibility

This project is still pre-1.0, so occasional breaking changes are expected while the API stabilizes. Changes are documented in the changelog and GitHub release notes. Deprecated APIs will keep warning for at least one point release before removal.

Supported Python versions are listed in the package classifiers and exercised in CI. The project generally retains stable CPython versions until their upstream end-of-life, adds new versions after its dependencies and CI support them, and drops versions only in minor releases.

See the changelog for release history and the project roadmap for the planned path to stable API and persistence contracts.

Contributing

git clone https://github.com/tvanreenen/numpy-vector-store.git
cd numpy-vector-store
uv sync --frozen --group dev

Before submitting a pull request:

1. Run uv run ruff check
2. Run uv run ruff format --check
3. Run uv run mypy src/
4. Run uv run pytest

License

MIT License - see LICENSE file for details.