vstash 0.7.0

Local document memory with instant semantic search. Drop any file. Ask anything. Get an answer in under a second.

vstash

Local document memory with instant semantic search.

Drop any file. Ask anything. Get an answer fast.

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

---

Why vstash?

Most RAG tools are slow, cloud-dependent, or require a running server. vstash is none of those things.

Layer	Technology	Why
Embeddings	FastEmbed (ONNX Runtime)	~700 chunks/s, fully local, no server
Vector store	sqlite-vec	Single .db file, cosine similarity, zero deps
Keyword search	FTS5 (SQLite)	Exact matches, porter stemming, built into SQLite
Hybrid ranking	Reciprocal Rank Fusion	Best of both: semantic + keyword, no training needed
Inference	Cerebras / Ollama / OpenAI	~2,000 tok/s via Cerebras, or 100% local via Ollama
Parsing	markitdown	PDF, DOCX, PPTX, XLSX, HTML, Markdown, URLs

Zero cloud required for search. Inference is optional.

What's new in v0.7

• Adaptive scoring — maturity gate (γ) suppresses frequency+decay until access patterns show genuine signal (max/mean ≥ 8×). Eliminates the -8.6% cold start degradation from fixed scoring. Scoring is now safe to enable by default.
• Zero-cost cold start — when γ = 0, scoring is completely short-circuited: no metadata lookups, no decay computation. Pure RRF with zero overhead.

What's new in v0.6

• Relevance signal — distance-based confidence (F1=0.952) warns when results may not match your query. Works from the first search, no setup needed.
• Document deduplication — one result per document, improving diversity from ~3.2 to 5.0 unique docs per top-5.
• Context expansion — adjacent chunks (±1) automatically included for LLM answers, 2.64× richer context.
• Tiered feedback — high (silent), medium (? indicator), low (full warning) in CLI and MCP.
• LLM grounding — system prompt rules enforce source citation and correct wrong-document attributions, passing 9/9 anti-hallucination trap tests.
• Discard telemetry — search events tracked for real-world relevance signal validation.

---

Install

pip install vstash

Or from source:

git clone https://github.com/stffns/vstash
cd vstash
pip install -e .

---

Quick Start

Search (free, no API key needed)

Semantic search works 100% locally — no inference backend required:

vstash add report.pdf
vstash add ~/docs/notes.md
vstash add https://arxiv.org/abs/2310.06825
vstash search "what is the proposed method?"

Ask (requires an LLM backend)

To get natural language answers, configure an inference backend:

# Option A: Fully local with Ollama (free, private)
ollama pull llama3.2

# Option B: Fast with Cerebras (free tier available)
export CEREBRAS_API_KEY=your_key_here

# Option C: OpenAI or any compatible API
export OPENAI_API_KEY=your_key_here

Then:

vstash ask "summarize the key findings"
vstash chat   # interactive Q&A session

---

Python SDK

Use vstash as a building block in your own agents and pipelines:

from vstash import Memory

mem = Memory(project="my_agent")
mem.add("docs/spec.pdf")

# Semantic search — free, no LLM
chunks = mem.search("deployment strategy", top_k=5)
for c in chunks:
    print(c.text, c.score)

# Search + LLM answer
answer = mem.ask("What are the system requirements?")

# Management
mem.list()                # → list[DocumentInfo]
mem.stats()               # → StoreStats
mem.remove("docs/old.pdf")

---

Commands

vstash add <file/dir/url>   Add documents to memory
vstash ask "<question>"     Answer a question from your documents
vstash search "<query>"     Semantic search without LLM (free, local)
vstash chat                 Interactive Q&A session
vstash list                 Show all documents in memory
vstash stats                Memory statistics (docs, chunks, DB size)
vstash forget <file>        Remove a document from memory
vstash watch <dir>          Auto-ingest on file changes
vstash export               Export chunks as JSONL for training data curation
vstash config               Show current configuration
vstash-mcp                  Start MCP server (for Claude Desktop integration)

Filtering with metadata

vstash add notes.md --collection research --project ml-survey --tags "attention,transformers"
vstash list --project ml-survey
vstash ask "what architectures were compared?" --project ml-survey
vstash export --project ml-survey --format jsonl

Documents with YAML frontmatter are parsed automatically:

---
project: ml-survey
layer: literature-review
tags: [attention, transformers]
---

# My Research Notes
...

---

Configuration

vstash looks for vstash.toml in your current directory, then ~/.vstash/vstash.toml, then falls back to sensible defaults. Run vstash config to see your active settings.

See the Configuration Reference for all options.

---

Privacy

Component	Data leaves machine?
Embeddings (FastEmbed)	Never — fully local ONNX
Vector store (sqlite-vec)	Never — local .db file
Semantic search	Never — local embeddings + SQLite
Inference (Cerebras/OpenAI)	Yes — query + retrieved chunks sent to API
Inference (Ollama)	Never — fully local

For full privacy, use backend = "ollama" or skip inference entirely and use vstash search instead of vstash ask.

---

Supported File Types

PDF, DOCX, PPTX, XLSX, Markdown, TXT, HTML, CSV, Python, JavaScript, TypeScript, Go, Rust, Java — and any URL.

---

Documentation

Guide	Description
Configuration	Full TOML reference — all sections and options
How It Works	Ingestion pipeline, search pipeline, chunking strategies, RRF
Memory Scoring	Frequency + decay re-ranking — formula, tuning, disabling
MCP Server	Claude Desktop integration setup
LangChain	VstashRetriever for chains and agents
Embedding Models	Model comparison and backend selection

---

Roadmap

• Phase 1 ✅: Core — ingest, embed, hybrid search, answer
• Phase 2 ✅: Usability — MCP server, collections, watch mode, metadata, export
• Phase 3 ✅: Python SDK — from vstash import Memory
• Phase 4 ✅: LangChain integration — VstashRetriever
• Phase 5 ✅: Memory scoring — frequency + temporal decay re-ranking
• Phase 6 ✅: Retrieval quality — distance-based relevance signal, document dedup, context expansion
• Phase 7: Sync — cr-sqlite CRDT peer-to-peer sync, multiple profiles

---

Easter Egg

In a 2018 Cornell paper "Local Homology of Word Embeddings", researchers used the variable v_stash (p. 11) to refer to the "vector of the word stash" — making this the first documented use of the exact term in the context of AI/embeddings.

---

License

MIT