vstash: A Local-First Hybrid Retrieval System for LLM Agents

Introducing vstash, a novel document memory system that integrates vector similarity search with keyword matching, enhancing retrieval for LLM agents.

3 min readTechnology

The vstash system represents a groundbreaking approach to document memory, prioritizing local data storage while effectively merging vector similarity searches with full-text keyword matching. Utilizing Reciprocal Rank Fusion (RRF) and adaptive IDF weighting tailored to individual queries, it operates on a single SQLite file, leveraging sqlite-vec for approximate nearest neighbor searches and FTS5 for keyword retrieval.

Key contributions include: (1) Self-supervised refinement of embeddings through hybrid retrieval disagreement, revealing that 74.5% of 753 BEIR queries exhibit top-10 discrepancies between vector-heavy and FTS-heavy searches. This offers a valuable training signal without needing human annotations. Fine-tuning the BGE-small model on 76K disagreement pairs enhances NDCG@10 across all datasets. (2) The introduction of adaptive RRF with per-query IDF weighting significantly boosts NDCG@10, achieving a score of 0.7263 on SciFact. (3) Attempts to improve post-RRF scoring through various methods yielded no positive results. (4) A robust production framework featuring integrity checks, schema versioning, and ranking diagnostics has been validated on over 50,000 relevance-judged queries. The system maintains a median search latency of 20.9 ms with consistent NDCG performance, and the fine-tuned model is available on HuggingFace.

Technology