zrag

ProData SovereigntyFSL-1.1-ALv2

Local-first, high-performance RAG built on zvec. Nothing ever leaves the machine - sub-1-second query latency through a persistent daemon that keeps collections and embedding models hot in memory.

Capabilities

Persistent daemon keeps zvec collections and embedding models hot in memory for zero-latency queries.
Hybrid search - keyword and semantic via Reciprocal Rank Fusion, with cross-encoder reranking.
AST-aware code chunking (Python, TypeScript, Go, Rust, C++) and semantic Markdown splitting.
Ingests text, Markdown, code, PDFs, images (via OpenCLIP), and web URLs.
Native MCP server for AI assistant integration (Claude Desktop, Cursor).
Built-in SSRF protections block malicious internal network requests during URL ingestion.
HyDE query expansion with a configurable LLM backend.

Requirements

git (for collection update --pull).
Base install (CPU): uv tool install zrag-<version>.whl - no GPU needed.
GPU acceleration (Linux): add the [cuda] extra - uv tool install 'zrag-<version>.whl[cuda]' - for CUDA-accelerated torch and llama-cpp.
macOS: MPS acceleration works out of the box on Apple Silicon - no extra needed.
Windows GPU: install a CUDA PyTorch wheel separately (PyPI ships CPU-only wheels).

zvec-powered RAG demo showing local semantic search across code collections

Installation Instructions

Install (base)

uv tool install zrag-<version>.whl

Or with GPU acceleration (CUDA torch + llama-cpp)

uv tool install 'zrag-<version>.whl[cuda]'

The installer fetches @bastilleworks/shared from public npm automatically. Replace <version> with the version you downloaded.

Usage Instructions

Shell

zrag daemon start

Shell

zrag collection add <name> ./src --mask "**/*.py"

Shell

zrag query "<natural language>" -c <name>

Shell

zrag query $'intent: auth middleware\nlex: AuthMiddleware\nvec: login flow' -c <name>

Shell

zrag mcp

Operates as a continuous background engine - start the daemon, index knowledge into collections, then search or expose them to AI assistants via MCP. For maximum precision, use a structured multi-line query with intent: (what to find), lex: (exact anchors like file names or symbols), vec: (semantic paraphrase), and hyde: (a hypothetical document passage). Configuration lives in ~/.zrag/config.yaml.

Uninstall

uv tool uninstall zrag

Notes

Ships as a standalone Python wheel - not packaged inside the Pro or Team meta-bundle tarball. Install the .whl directly with uv tool install.
Nothing ever leaves the machine - local embeddings and a local vector store by default.
Requires a valid Polar license.

All modules