DEV Community

Cover image for Why We Built Bitweave: Sub-Millisecond Hybrid Retrieval in <1.1 MB RSS Memory
cteague2018
cteague2018

Posted on

Why We Built Bitweave: Sub-Millisecond Hybrid Retrieval in <1.1 MB RSS Memory

#ai #performance #python #rust

When building local RAG (Retrieval-Augmented Generation) applications, edge agents, or serverless AI pipelines, developers usually hit a wall with standard vector stores: memory overhead.

Running a dedicated vector database locally often demands hundreds of megabytes—or gigabytes—of RAM just to keep indices warm. On the flip side, lightweight local options like scanning raw JSON files or querying SQLite don't scale well when vector dimensions climb into the thousands (1536d+).

We built Bitweave to solve this exact trade-off: a zero-copy, SIMD-accelerated hybrid retrieval engine in Rust (with Python bindings) that handles categorical filtering and vector search while locking its active heap footprint under 1.1 MB RSS.

The Architecture: How Bitweave Achieves Sub-Millisecond Speed at <1.1 MB RAM
Bitweave relies on a 3-part design to maximize search speed while keeping memory consumption negligible:
[ Categorical Filters ] ---> Bit-Sliced Bitmaps
│
▼
[ Query Vector (1536d) ] --> 1-Bit SIMD Pre-Filtering (Hamming Distance)
│ (Top K Candidates)
▼
[ Raw Embeddings Buffer ] -> Zero-Copy Float32 Rescoring (exact_rescore=True)
│
▼
Top-K Results Array (NumPy)

  1. Zero-Copy Memory Mapping (memmap2)
    Instead of deserializing index files into Python RAM or Rust heap space, Bitweave uses memory-mapped files (.bweave). The operating system's page cache handles lazy loading of index segments directly from disk into virtual address space. As a result, the active RSS memory footprint remains static around 1.1 MB, whether your index holds 5,000 or 200,000 records.

  2. 1-Bit Vector Quantization & SIMD Hamming Distance
    High-dimensional float32 vectors (1536d) are quantized down to 1-bit sign masks (where values > 0 map to 1 and <= 0 map to 0). During pre-ranking, Bitweave uses SIMD bitwise XOR and POPCNT operations to compute Hamming distances across candidate vectors in microseconds.

  3. Zero-Copy 2-Pass Float32 Rescoring (exact_rescore=True)
    Quantization speeds up initial candidate selection, but full precision is critical for RAG accuracy. Bitweave solves this by taking the top N pre-ranked candidates and dereferencing their raw Float32 embeddings via direct offset pointers into a binary buffer. You get the speed of 1-bit SIMD filtering paired with exact float32 distance rescoring.

Quick Benchmarks: 200,000 Records
We benchmarked Bitweave against standard local retrieval approaches on a single machine processing 200,000 dense records:

Python JSON Scan: ~450 MB RAM | > 120 ms latency | ❌ No zero-copy

SQLite (Indexed): ~45 MB RAM | ~18 ms latency | ❌ No zero-copy

Bitweave (.bweave): ~1.1 MB RAM | < 1.0 ms latency | ✅ Zero-copy

Getting Started with Python
Bitweave is published on PyPI with pre-compiled wheels for Linux, macOS (x86_64 & Apple Silicon), and Windows.

Installation

pip install bitweave
Enter fullscreen mode Exit fullscreen mode

Basic Usage

import numpy as np
from bitweave import HybridIndex

# 1. Define schema and build index (1536-dimensional vectors)
schema = ["category", "access"]
index = HybridIndex.builder(schema, vector_dim=1536)

# Add records (doc_id, metadata, embedding, external_offset)
index.add_record(
    doc_id=101,
    metadata={"category": "finance", "access": "public"},
    embedding=[0.05] * 1536,
    external_offset=0
)
index.save("my_index.bweave")

# 2. Load index with zero-copy memory mapping
loaded = HybridIndex.load("my_index.bweave")

# 3. Perform 2-pass hybrid retrieval
raw_embeddings_data = np.array([[0.05] * 1536], dtype=np.float32).tobytes()

results = loaded.search(
    filters={"category": "finance", "access": "public"},
    query_vector=[0.05] * 1536,
    top_k=5,
    exact_rescore=True,
    embeddings_data=raw_embeddings_data
)

# Output is a zero-copy 2D NumPy array: [[doc_id, score], ...]
print(results)
Enter fullscreen mode Exit fullscreen mode

Reproduce the Benchmarks Yourself
We believe performance claims should always be independently verifiable. You can run the entire 200k benchmark suite and generate an interactive HTML report locally:

git clone [https://github.com/cteague2018/bitweave.git](https://github.com/cteague2018/bitweave.git)
cd bitweave

# Setup environment & build Rust bindings
python -m venv .venv
source .venv/bin/activate  # Or .venv\Scripts\activate on Windows
pip install maturin pytest numpy psutil
maturin develop

# Run benchmark suite
python benchmarks/run_all.py
Enter fullscreen mode Exit fullscreen mode

Open report.html in your browser to inspect the latency distribution and RSS memory usage graphs.

Top comments (0)