Skip to content

v0.2.0

Latest
Latest

Choose a tag to compare

View all tags
@zhourrr zhourrr released this 27 Aug 16:15
· 20 commits to main since this release
v0.2.0
38fe0f9

🎉 zvec-grep v0.2.0 — Public Preview

We are excited to release zvec-grep v0.2.0, our first comprehensive public preview.

zvec-grep (zg) is a local-first workspace search layer for people and AI agents. It combines ripgrep, BM25 full-text search, and vector search so you can move naturally between exact lookup and semantic discovery—without loading entire files or repositories into an agent’s context.

This release brings the core product together: hybrid retrieval, structure-aware indexing, managed agent integrations, local and remote Embedding options, incremental updates, and a shared local MCP server.

✨ Highlights

🔎 One search layer for exact and semantic retrieval

Use natural language when you know the intent but not the exact file or symbol:

zg query "where theme preferences are restored"

Indexed search combines BM25 and vector retrieval, with Reciprocal Rank Fusion (RRF) for multi-route ranking. Queries can be narrowed by path, glob, file type, symbol type, or modification time.

When you already know the exact text, symbol, path, or regular expression, use the managed ripgrep route instead:

zg query --rg -n -F "AuthService" -g "*.ts" src

Managed ripgrep is exhaustive by default and works without an index or Embedding model.

🤖 Built for AI agents

v0.2.0 includes managed MCP integrations for:

  • Codex
  • Claude Code
  • Qwen Code
  • OpenCode
  • Cursor

Run zg install to detect and configure supported agents, or select one explicitly:

zg install --target codex --yes
zg install --target qwen --yes

Where supported, the installer configures MCP access, retrieval guidance, and local tool approval or trust settings. The guidance helps agents choose between semantic discovery and exact lookup, combine the two when necessary, and stop searching once the available evidence is sufficient.

📚 Search more than source code

zvec-grep is designed for mixed-content workspaces. It can search source code, documentation, configuration, research material, notes, and structured text data through the same interface.

This preview includes structure-aware extraction for major languages such as C, C++, Go, Java, JavaScript, TypeScript, Python, and Rust; heading-aware Markdown indexing; and text extraction for many additional programming languages and formats including JSON, YAML, TOML, CSV, HTML, XML, and plain text.

With a compatible multimodal Embedding model, raster images can also be explicitly included in an index.

🔒 Local-first by default

Workspace scanning, index storage, retrieval, and local Embedding inference stay on your machine by default. The shared server listens on loopback, and workspace indexes are stored under <workspace>/.zvec-grep/.

The built-in model catalog includes local Model2Vec, ONNX, and GGUF options for code, English documents, multilingual content, and long-context retrieval. Remote Qwen text and multimodal Embedding models are also supported, but sending workspace content or query text to a remote provider always requires separate, explicit authorization.

⚡ Incremental indexing and shared server mode

Indexes can be updated incrementally while preserving the workspace’s model and file-selection settings:

zg index --embedding local/potion-code-16m-v2
zg index
zg status

For persistent agent workflows, the local server coordinates workspace runtimes, background refreshes, MCP access, and loaded Embedding models:

zg server on
zg server status

CLI operations can run in auto, server, or direct mode. Managed ripgrep remains available without the server or an index.

🎯 Compact, source-grounded results

Search results are ranked, grouped by file, and returned with source locations and bounded previews. The default output is intentionally compact for agent context, while --human provides richer terminal output:

zg query --human "plugin lifecycle" --limit 5

📊 Benchmarks

The repository includes reproducible paired A/B benchmark suites for two different workloads:

  • SWE-QA-Bench for repository-level, cross-file software-engineering questions
  • BrowseComp-Plus for multi-document retrieval over a fixed large corpus

The suites compare baseline and zvec-grep runs under the same task, agent, model, prompt, environment, and resource limits. They report answer quality, input tokens, tool calls, agent execution time, and execution traces, with index preparation measured separately.

See the benchmark documentation for the methodology, results, and reproduction instructions.

🚀 Get started

zvec-grep supports macOS, Linux, and Windows and requires Node.js 22 or later.

npm install -g @zvec/zvec-grep@0.2.0

cd your-workspace
zg index --embedding local/potion-code-16m-v2

# Search from the terminal
zg query --human "where is authentication handled?"

# Connect an installed agent
zg install

🧪 Preview status

v0.2.0 is a preview release. The core indexing, retrieval, CLI, server, and agent integrations are ready for real-world testing, but CLI and MCP contracts, configuration defaults, index compatibility, and installation behavior may continue to evolve before the first stable release.

Feedback from real workflows will shape what comes next. If you encounter a search that should work better, an integration issue, or a missing data format, please open an issue.

Thank you for trying zvec-grep.

Assets 2
Loading