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)
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 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.
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.
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
Basic Usage
import numpy as np
from bitweave import HybridIndex
schema = ["category", "access"]
index = HybridIndex.builder(schema, vector_dim=1536)
index.add_record(
doc_id=101,
metadata={"category": "finance", "access": "public"},
embedding=[0.05] * 1536,
external_offset=0
)
index.save("my_index.bweave")
loaded = HybridIndex.load("my_index.bweave")
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
)
print(results)
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
python -m venv .venv
source .venv/bin/activate # Or .venv\Scripts\activate on Windows
pip install maturin pytest numpy psutil
maturin develop
python benchmarks/run_all.py
Open report.html in your browser to inspect the latency distribution and RSS memory usage graphs.