Frequently Asked Questions
General
What is VecLabs? VecLabs is a vector database for AI agents. It combines a Rust HNSW query engine with client-side AES-256-GCM encryption and on-chain Merkle proof via Solana. It is faster than Pinecone, cheaper than every major alternative, and the only vector database that gives you cryptographic proof of data integrity. Do I need to know anything about Solana or blockchain? No. VecLabs handles all Solana interactions automatically. You never need to install a wallet, fund an account, or understand how Solana works. The SDK manages everything on your behalf. The blockchain aspects are implementation details - the user-facing API is justupsert, query, and verify.
Is VecLabs production-ready?
Phases 1-5 are complete. @veclabs/solvec is stable and production-ready.
Disk persistence (Phase 4) and decentralized storage (Phase 5) are both live.
Memory Inspector (Phase 6) and @veclabs/recall (Phase 7) are in development.
What programming languages does VecLabs support?
TypeScript and Python are currently supported with official SDKs. A REST API and additional language SDKs (Go, Rust) are on the roadmap.
Privacy & Security
Can VecLabs read my vectors? No. Vectors are encrypted with AES-256-GCM client-side using a key derived from your wallet keypair before leaving the SDK. VecLabs stores only ciphertext. This is enforced by the architecture - it is not a policy that could change. Where is my data stored? Vectors are stored in three layers:- In-memory HNSW index - for fast querying
- Encrypted .db file on disk - survives server restarts (Phase 4)
- Decentralized storage - optional, automatic backup (Phase 5)
~/.config/solana/id.json or wherever you store it) the same way you’d back up any critical credential.
Performance
How fast is VecLabs? 4.7ms p99 at 100K vectors, 1536 dimensions (OpenAI ada-002 size), top-10 cosine similarity query, measured on Apple M3 with 1,000 samples. Methodology and reproduction steps:benchmarks/COMPARISON.md.
How does VecLabs achieve such low latency?
Three reasons: (1) The HNSW index is held in memory - no network round-trip on the query path. (2) The query engine is written in Rust with no garbage collector - no GC pause spikes at p99. (3) Zero serialization on the hot path - vectors stay as native f32 arrays in memory.
How does latency scale with dataset size?
HNSW query time is O(log n). Doubling the number of vectors increases query time by roughly 15-20%, not 2x. Going from 100K to 1M vectors takes p99 from ~5ms to ~10-15ms.
Does .verify() slow down queries?
No. .verify() makes a Solana RPC call and takes ~400ms. It is completely separate from the query path. Your queries run at full speed regardless of whether you call verify or how often you call it.
API & SDK
How do I get an API key? Sign up at app.veclabs.xyz. Your first API key is generated automatically on registration and sent to your email. The free tier includes 100K vectors at no cost. No credit card required. What’s the difference between hosted and self-hosted mode? Hosted mode (api.veclabs.xyz): use an API key and VecLabs manages your Solana wallet, Shadow Drive storage, and Merkle root posting. Just pass apiKey to the constructor.
Self-hosted mode: install the SDK, bring your own Solana wallet, and manage your own storage. Both modes use the same SDK - just swap the constructor options.
Where do I manage my account and billing?
app.veclabs.xyz - your developer dashboard. Manage API keys, view usage, and upgrade your plan.
What’s the difference between upsert and insert?
VecLabs only has upsert. If a vector with the same ID already exists, it is updated. If it doesn’t exist, it is inserted. There is no separate insert/update distinction.
Can I store multiple collections?
Yes. Create as many collections as you need. Each collection is independent with its own dimensions, metric, and on-chain Merkle root.
Can I delete vectors?
Yes. Use collection.delete(id) or collection.delete([id1, id2, ...]). Deletion updates the in-memory index and the Merkle root.
Can I filter by metadata at query time?
Not yet. Metadata filtering is on the roadmap. Currently, you retrieve top-K results by vector similarity and filter in application code.
Can I change the distance metric after creating a collection?
No. The metric is fixed at collection creation. To change it, create a new collection and re-index your vectors.