Qwen Developers Open-Sources zg (zvec-grep): A Local-First Search Layer Unifying ripgrep, BM25, and Vector Search
zg (zvec-grep) is an open-source, local-first search layer that unifies ripgrep, BM25, and semantic vector search behind a single interface for both humans and AI agents It exposes exactly two default MCP tools (zvec_grep_search and zvec_grep_rg), keeping index lifecycle management in the CLI rather than giving agents destructive control All indexing and embedding runs on-device by default using local models like potion-code-16m-v2, with remote Qwen embeddings requiring explicit authorization Ve
Analysis
TL;DR
- zg (zvec-grep) is an open-source, local-first search layer that unifies ripgrep, BM25, and semantic vector search behind a single interface for both humans and AI agents
- It exposes exactly two default MCP tools (zvec_grep_search and zvec_grep_rg), keeping index lifecycle management in the CLI rather than giving agents destructive control
- All indexing and embedding runs on-device by default using local models like potion-code-16m-v2, with remote Qwen embeddings requiring explicit authorization
- Vendor A/B benchmarks show ~50% reductions in tool calls and input tokens on SWE-QA-Bench and BrowseComp-Plus, with Django repo indexing under 30 seconds on Apple M4 Pro
- Released under Apache 2.0, installable via npm as @zvec/zvec-grep, requiring Node.js 22+ and no GPU for the default model
Why It Matters
This directly addresses a critical bottleneck in agentic AI workflows: coding agents waste significant tool budgets and tokens on inefficient code search. By unifying lexical, semantic, and hybrid retrieval into a single local-first layer with a restrained MCP surface, zg reduces context consumption and improves agent accuracy without requiring cloud infrastructure or GPU hardware.
Technical Details
- Four retrieval routes: hybrid default (intent + lexical anchors),
--ftsfor BM25-ranked exact terms,--vectorfor conceptual similarity without lexical ranking, and--rgfor exhaustive literal/regex matching without any index - Local-first architecture: Workspace index stored in
<root>/.zvec-grep/, with incremental updates;.gitand.zvec-grepalways excluded along with standard dependency/build/cache directories - MCP integration: Detects Codex, Claude Code, Cursor, and OpenCode; serves via Streamable HTTP MCP on loopback-only with optional bearer auth; default toolset is intentionally limited to two search tools
- Embedding options: Ten local models (including Model2Vec static potion-code-16m-v2 with 256-dim output, jina-embeddings-v2-base-code, embeddinggemma-300m, qwen3-embedding-0.6b) and three remote Qwen endpoints up to 128K token context
- Benchmark results: SWE-QA-Bench (20 questions) showed 50%+ tool call reduction, ~50% token reduction, +1.50 Judge score; BrowseComp-Plus (80 questions) showed 98.67%→99.00% accuracy with 37-43% reductions across tokens, tool calls, and agent time
Industry Insight
- The deliberate restraint in MCP tool exposure (two default tools, index lifecycle in CLI) sets a precedent for safe agent-tool design, preventing agents from silently creating, rebuilding, or deleting persistent indexes—a pattern other agentic search tools should adopt
- Local-first semantic search for code closes the gap between keyword-based and intent-based retrieval without cloud dependency, making it viable for enterprises with strict data residency requirements
- The reported ~40-50% efficiency gains in tool calls and tokens suggest that investing in specialized search infrastructure for coding agents yields compounding returns as agent workflows scale, though independent benchmark replication is needed before widespread adoption
Disclaimer: The above content is generated by AI and is for reference only.