vstash

Local document memory with hybrid retrieval. Single SQLite file. Zero cloud dependencies for search. Beats ColBERTv2 on 5/5 BEIR datasets with the tuned bge-small-rrf-v3 model. ~50 ms p50 at 50K chunks on Apple Silicon with the optional snapvec backend (~73 ms on the default sqlite-vec for dense corpora).

pip install vstash
vstash add paper.pdf notes.md https://example.com/article
vstash search "what's the main argument?"

Retrieval Quality

Absolute NDCG@10 on BEIR via the full production retrieval pipeline (RRF hybrid + adaptive weights + MMR dedup + IDF, 2026-04-19). Tuned model: Stffens/bge-small-rrf-v3 (33M params, 384d). v3 beats ColBERTv2 on 5/5 BEIR datasets and improves macro NDCG@10 by +0.016 absolute over bge-small-rrf-v2 (0.6405 vs 0.6246). Training-time eval uses a batched path that skips MMR/IDF for speed; absolute NDCG@10 differs by a few percent vs the production numbers above, but baseline-vs-final deltas are preserved. See experiments/results/v2_v3_head_to_head.json for the full table (reproduce via python -m experiments.v2_v3_head_to_head) and the methodological note in experiments/hypotheses.md for the pipeline-shift caveat.

How It Works

Query --> Embed --+--> Vector ANN (sqlite-vec) --+
                  |                               +--> Adaptive RRF --> MMR Dedup --> Results
                  +--> FTS5 BM25 ----------------+

• Hybrid search: vector + keyword, fused via Reciprocal Rank Fusion.
• Adaptive RRF: IDF-based per-query weights. Rare terms boost keywords, common terms boost vectors.
• MMR dedup: diverse sections from long documents, not redundant chunks from one.
• Self-tuned, gated: vstash retrain fine-tunes embeddings from your own disagreement signal; the eval gate refuses regressions.

Install

pip install vstash                    # SDK + search
pip install 'vstash[ingest]'          # + PDF, DOCX, PPTX parsing
pip install 'vstash[serve]'           # + web UI (vstash serve)
pip install 'vstash[all]'             # everything

Usage

# Ingest: files, folders, URLs
vstash add report.pdf ~/notes/ https://arxiv.org/abs/2310.06825

# Search: local, no API key
vstash search "what is the proposed method?"

# Ask: needs a local LLM, auto-detects Ollama / LM Studio
vstash ask "summarize the key findings"
vstash chat                           # interactive

# Fine-tune on your own corpus (eval-gated, refuses regressions)
vstash retrain
vstash reindex --model ~/.vstash/models/retrained

Python SDK

from vstash import Memory

mem = Memory(project="my_agent")
mem.add("docs/spec.pdf")
mem.remember("OAuth uses PKCE for public clients", title="auth-notes")

results = mem.search("deployment strategy", top_k=5)
for r in results:
    print(r.text, r.score, r.collection, r.tags, r.added_at)

answer = mem.ask("What are the system requirements?")

Commands

vstash add <file/dir/url>    Add documents to memory
vstash remember "<text>"     Ingest text directly
vstash search "<query>"      Semantic search (free, local)
vstash ask "<question>"      Answer from your documents (needs LLM)
vstash chat                  Interactive Q&A
vstash list                  Show all documents
vstash stats                 Memory statistics
vstash forget <file>         Remove a document
vstash retrain               Fine-tune embeddings on your data
vstash reindex               Re-embed with a new model
vstash watch <dir>           Auto-ingest on file changes
vstash serve                 Web UI on localhost
vstash check [--repair]      Integrity check and repair
vstash config                Show configuration
vstash profile <cmd>         Manage named profiles
vstash journal <cmd>         Cross-session agent memory

MCP Server

16 tools for Claude Desktop, Claude Code, Cursor, or any MCP client:

vstash-mcp                            # start MCP server

{
  "mcpServers": {
    "vstash": {
      "command": "vstash-mcp"
    }
  }
}

Self-Supervised Embedding Refinement

vstash can tune its own embedding model to your corpus, without any human labels.

vstash retrain                        # generate training pairs + fine-tune
vstash reindex --model ~/.vstash/models/retrained

How it works, in one paragraph. When you search your corpus, the vector and keyword halves of the pipeline sometimes rank different documents at the top. Those disagreements are a free signal: the document each half picked is probably relevant, the one only one half picked might not be. vstash turns this into training pairs and fine-tunes the embedding model on them. The run is eval-gated: it evaluates the candidate against the base model on a held-out slice of your corpus and refuses to save a model that performs worse.

The feature is maturing fast. Each release tightens the recipe, lifts the measured numbers, and adds infrastructure that keeps the next iteration honest:

Both v2 and v3 beat ColBERTv2 on 5/5 BEIR datasets under the current pipeline. v3 improves macro by +0.016 over v2 (+2.6% relative), with the largest per-dataset gain on FiQA (+0.097 absolute). It is a trade, not a strict upgrade: v3 gives up ~0.040 NDCG@10 on NFCorpus vs v2 in exchange for the FiQA and SciFact wins. v2 remains the better pick for keyword-heavy / biomedical corpora where NFCorpus-style retrieval dominates; v3 is the recommended default for everything else. The eval gate also catches losers: hypothesis H-R3 (hard-negative margin filter) regressed macro -2.49pp, the candidate was refused, the branch was closed without merging. The pipeline's job is to refuse bad models, and it does.

See the Retrieval Quality table, docs/retrain.md for the full recipe and per-version breakdown, and experiments/results/v2_v3_head_to_head.json for reproducible numbers.

Requires sentence-transformers, torch, and accelerate:

pip install 'sentence-transformers>=3' torch 'accelerate>=1.1.0'

Privacy

Search is always private. Use a local LLM for fully private answers.

Paper

vstash: Local-First Hybrid Retrieval with Adaptive Fusion for LLM Agents

Adaptive RRF, self-supervised embedding refinement, a negative result on post-RRF scoring, and the production substrate all in one place. PDF build at paper/arxiv/vstash.pdf.

Documentation

Experiments

What's New in v0.39

• Cross-document near-duplicate collapse (v0.39) -- MMR only penalises chunks of the same document, so a corpus holding many near-identical documents (audit logs, mirrored notes, a file ingested repeatedly) could fill every result slot with restatements of one answer. dedup_threshold=0.95 drops a chunk whose cosine similarity to an already-kept, higher-ranked chunk is at or above the threshold, regardless of document. Opt-in: the default leaves ranking untouched. Available on VstashStore.search, Memory.search, MCP vstash_search, and CLI vstash search --dedup 0.95 (#509).
• Query cache correctness fix (v0.39) -- with [cache] query_cache_size > 0, a filtered search (filters={"not": {...}}) could be served the cached results of the unfiltered query, because the filter tree was missing from the cache key entirely (#509).
• Tier-0 content-hash dedup on remember (v0.39) -- re-ingesting byte-identical content is now a NOOP instead of a re-chunk plus re-embed (#429).
• Atomic content updates + autocommit connection (v0.39) -- Memory.update(text=...) replaces every chunk through add_documents_batch, and the SQLite connection runs in autocommit with explicit BEGIN IMMEDIATE so a write lock is never held open across a read (#423, #424, #430).
• Frozen result models (v0.39) -- the query LRU cache hands out shared objects, so every result model is now immutable; one caller can no longer corrupt another's cached entry (#427).
• Python 3.13 in CI (v0.39) -- tested on 3.10 through 3.13, matching the classifiers (#431).

What's New in v0.37

• Memory.update() — in-place document mutation (v0.37) -- update a stored doc without re-adding it. Memory.update(path, title=..., tags=...) runs a single atomic metadata UPDATE (no re-chunking, no embedding); Memory.update(path, text=...) re-chunks + re-embeds and replaces every chunk while preserving all other metadata. CLI vstash update <path> [--text|--title|--tags] (--text - for stdin); MCP vstash_update (#365).
• Memory.prune() + Memory.compact() (v0.37) -- housekeeping. Memory.prune(before="30d", collection=..., tags=...) deletes filter-scoped documents (an unfiltered call raises rather than wiping everything); Memory.compact(before=...) runs prune + VACUUM + FTS optimize in one pass. before accepts "30d" / "2w" / "24h" or an ISO date. CLI vstash compact; MCP vstash_compact (#366).
• Tag filters in search (v0.37) -- pass tags="alpha" or tags=["alpha", "beta"] (OR semantics, comma-anchored so alpha never matches alphabet) to Memory.search, VstashStore.search, MCP vstash_search, and VstashRetriever. Memory.journal_recall also gains --after / --before date filters. CLI vstash search --tag alpha --tag beta (#106, #364).
• MMR dedup speedup (v0.37) -- the dedup hot path now uses swap-pop removal + pre-grouped same-doc siblings, a measured 1.15x–1.19x end-to-end on store.search() with real BGE-small embeddings. Ranking output is unchanged (#363).
• Services-layer architecture (v0.37) -- web / MCP / CLI / SDK now route search and ask through one shared validate -> embed -> search -> expand path (vstash/services/), backed by a VstashError domain error tree, a VectorBackend Protocol, and a built-in embed-model registry (#326, #327, #328, #330, #334–#336).

What's New in v0.36

• chat.ask_full() returning AskResult (v0.36) -- new public API surfaces the reasoning trace and token usage that ask() previously discarded. Cerebras gpt-oss-120b populates result.reasoning; Ollama qwen3 thinking-mode uses message.thinking; OpenAI-compat servers (vLLM, DeepSeek, Together, xAI Grok, OpenAI o1/o3) read reasoning_content. ask() keeps its -> str contract via a thin wrapper -- zero call-site change for existing code. Also exposed as Memory.ask_full(). Drives Merken Phase 2 distillation pipeline.
• Centralized store construction (v0.36) -- open_store_for_config(cfg) is the single entry point used by CLI, MCP, web, SDK, journal, and federated search. Previously each surface duplicated the StorageConfig -> VstashStore wiring and silently dropped IVFPQ tuning fields on some paths (#297).
• vec_only long-query distance cutoff fix (v0.36) -- retrieval_mode="vec_only" now applies the same long-query relaxation as hybrid; ArguAna vec_only jumped from NDCG@10 = 0.0013 (1403/1406 zero) to 0.4250. Hybrid mode and all paper / model-card numbers untouched (#304).
• Bug fixes (v0.36) -- Memory.add(collection=None) falls back to schema default instead of crashing on the NOT NULL constraint (#296); vstash retrain --synthesize-queries no longer crashes on Ollama / Cerebras backends (#294); web uploads now persist under ~/.vstash/uploads/<uuid>-<safe-name> instead of pointing at deleted temp paths (#295).

What's New in v0.35

• bge-small-rrf-lme-v1 chat-memory specialist (v0.35) — fine-tuned on 398 labeled LongMemEval queries through the eval-gated retrain loop. +3.79pp R@5 on n=102 holdout vs vanilla BGE-small. Use when your corpus is primarily chat sessions / agent memory.
• Eval-gated labeled retrain (v0.35) — vstash retrain --training-queries train.jsonl --eval-queries eval.jsonl accepts user-supplied (query, relevant_paths) JSONL and refuses to save fine-tunes that regress NDCG@10 on the holdout. See docs/retrain.md.
• vstash why miss analysis (v0.33) — diagnose why an expected document did not surface for a query. Traces vector pool, distance cutoff, FTS match, RRF fusion, MMR, and context-expansion stages with parameter suggestions. Auto-logs misses on empty / low-relevance searches.
• retrieval_mode enum (v0.33) — Literal["hybrid", "vec_only", "fts_only"] = "hybrid" on Memory.search, Memory.ask, VstashStore.search, and MCP tools. vec_only is the symmetric branch to fts_only. Default stays hybrid. Legacy fts_only=True boolean was removed in v0.35.
• Custom encoder resolver hook (v0.34) — register_encoder_resolver(fn) lets callers plug LoRA-adapted, locally fine-tuned, or otherwise unnamable encoders into the embed pipeline. See docs/embedding-models.md.
• Cosine metric in vec_chunks (v0.34) — sqlite-vec virtual table now uses cosine distance (was L2 before; v1 DBs migrate in place atomically on first open). Fixed a latent bug where non-unit-normalized models silently mis-ranked.
• Persistent embedder daemon (v0.32) — vstash serve --warm pre-loads the embedding model and exposes /api/embed on localhost:8585. CLI and SDK clients auto-detect and delegate; cold start drops from ~2 s to ~5 ms.

See CHANGELOG for full version history.