# Turbovec

> Local vector search with turbovec (Google TurboQuant, Rust+Python). Use for embeddings indexing, semantic search, local RAG, or filtered vector retrieval without external services like Pinecone.

- Skill: `s3yed/turbovec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add s3yed/turbovec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/s3yed/turbovec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: S3YED (https://skillmd.com/u/s3yed)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/s3yed/turbovec

---


# turbovec — local vector index

Rust vector index on Google's TurboQuant quantizer. 10M float32 docs (31GB) fit in ~4GB. Faster than FAISS. No train step: add vectors, they are indexed. Fully local — nothing leaves the machine.

## Where it is installed (v0.7.0, per host)

| Host | Python |
|---|---|
| Mac Mini (appie-1 / appie-3 / appie-4 / Opus) | `/Users/appie/clawd/external/.venv-turbovec/bin/python` |
| appie-2 (Hetzner) | `/root/venvs/turbovec/bin/python` |
| Spark Atlas | `~/venvs/turbovec/bin/python` |

Run scripts with that interpreter; do not pip-install elsewhere.

## API (v0.7.0 — differs from upstream README)

```python
import numpy as np
from turbovec import TurboQuantIndex

idx = TurboQuantIndex(dim=1536, bit_width=4)
idx.add(vecs)                      # 2D float32, C-contiguous: np.ascontiguousarray(x.astype(np.float32))

scores, ids = idx.search(q, k=10)  # q must be 2D (batch): vecs[7:8], not vecs[7]
                                   # returns 2D arrays (one row per query)

mask = np.zeros(len(idx), dtype=bool)   # filtered search: bool mask over slots
mask[allowed_slots] = True
scores, ids = idx.search(q, k=10, mask=mask)

idx.write("index.tq")              # persistence round-trips exactly
idx = TurboQuantIndex.load("index.tq")
```

Gotchas:
- Queries MUST be 2D; a 1D vector raises `TypeError: 'ndarray' object cannot be cast as 'ndarray'`.
- `mask` is a bool array of length `len(idx)` (slot-based), not an id allowlist. The README's `IdMapIndex.add_with_ids`/`allowlist=` API is newer than the 0.7.0 wheel.
- `bit_width=4` is the standard memory/recall tradeoff; pair with any local embedding model for an air-gapped RAG stack.

## When to use
- Semantic search over local corpora (memory, knowledge base, transcripts)
- RAG retrieval where privacy/latency matters (no Pinecone round-trip)
- Hybrid retrieval: narrow candidates with SQL/BM25 first, then dense rerank via `mask`