How stffns/vstash works
vstash is a local-first document memory and hybrid retrieval product. Its main workflow accepts files, URLs, or text; chunks and embeds content into a SQLite-backed store; then serves queries through vector and keyword retrieval, adaptive fusion, and diversity filtering. The product also exposes CLI, SDK, web, and MCP interfaces, plus Q&A, journal memory, monitoring, and self-supervised embedding refinement. Some subsystem links below follow README documentation or SOURCE INDEX references; unsampled implementation details are not inferred as specific calls.
Main entry points: search.py Search service · ingest.py Document ingestion · __init__.py Document store · _app.py CLI commands
Components 27
User interfaces
- CLI commands
vstash/cli/_app.py - Python SDK
vstash/memory.py - Web UI
vstash/web.py - MCP server
vstash/mcp.py - Framework adapter
vstash/langchain.py
Content and memory
- Document ingestion
vstash/ingest.py - Code splitting
vstash/code_split.py - Embedding engine
vstash/embed.py - Journal memory
vstash/journal.py - Document store
vstash/store/__init__.py - Store primitives
vstash/store/_common.py
Hybrid retrieval
- Input validation
vstash/validation.py - Search service
vstash/services/search.py - Answer and chat
vstash/services/ask.py - LLM backends
vstash/chat.py - Typed data models
vstash/models.py
Tuning and operations
- Configuration
vstash/config.py - Store setup
vstash/_store_open.py - Embedding retraining
vstash/retrain.py - Batch retraining
vstash/retrain_batch.py - Profiles
vstash/profile.py - File watching
vstash/watch.py - Search metrics
vstash/metrics.py - Retrieval evaluation
experiments/beir_benchmark.py
Other components
- User / agent
- SQLite database
- Optional LLM
Connections 42
- User / agent → CLI commands: invokes
- User / agent → Python SDK: uses
- User / agent → Web UI: uses
- User / agent → MCP server: connects
- User / agent → Framework adapter: uses
- CLI commands → Document ingestion: dispatches ingestion
vstash/cli/_ingest.py - CLI commands → Search service: dispatches search
vstash/cli/_search.py - CLI commands → Embedding retraining: dispatches retraining
vstash/cli/_retrain.py - Python SDK → Document ingestion: adds documents
vstash/memory.py - Python SDK → Search service: queries
vstash/memory.py - Python SDK → Journal memory: uses journal
vstash/memory.py - Web UI → Search service: searches through
vstash/web.py - Web UI → Document ingestion: ingests through
vstash/web.py - MCP server → Search service: searches through
vstash/mcp.py - MCP server → Document ingestion: ingests through
vstash/mcp.py - MCP server → Journal memory: uses journal
vstash/mcp.py - Document ingestion → Code splitting: splits code
vstash/ingest.py - Document ingestion → Embedding engine: embeds chunks
vstash/ingest.py - Document ingestion → Document store: writes documents
vstash/ingest.py - Search service → Input validation: validates query
vstash/services/search.py - Search service → Embedding engine: embeds query
vstash/services/search.py - Search service → Document store: retrieves candidates
vstash/services/search.py - Search service → Search metrics: records latency
vstash/services/search.py - Search service → Typed data models: returns results
vstash/services/search.py - Document store → Store primitives: uses primitives
vstash/store/__init__.py - Document store → SQLite database: reads and writes
- Document store → Typed data models: uses typed records
vstash/store/__init__.py - Answer and chat → Search service: gets context
vstash/services/ask.py - Answer and chat → LLM backends: generates answer
vstash/services/ask.py - LLM backends → Optional LLM: calls optional backend
- Answer and chat → Typed data models: returns answer
vstash/services/ask.py - Python SDK → Answer and chat: asks questions
vstash/memory.py - Configuration → Store setup: configures store
vstash/_store_open.py - Store setup → Document store: opens
vstash/_store_open.py - Store setup → Profiles: resolves path
vstash/_store_open.py - Embedding retraining → Embedding engine: refines model
vstash/retrain.py - Embedding retraining → Document store: reads corpus
vstash/retrain.py - Embedding retraining → Batch retraining: uses batch training
vstash/retrain.py - Retrieval evaluation → Embedding engine: embeds evaluation data
experiments/beir_benchmark.py - Retrieval evaluation → Document store: evaluates retrieval
experiments/beir_benchmark.py - File watching → Document ingestion: auto-ingests changes
- CLI commands → File watching: starts watching
vstash/cli/_manage.py