zg Unifies ripgrep, BM25, and Vector Search in Two MCP Tools

The Qwen Developer team has released zg (zvec-grep) under the zvec-ai GitHub organization, an Apache 2.0-licensed, npm-installable tool that places ripgrep, BM25 full-text search, and on-device vector embeddings behind a single query interface. It targets a concrete inefficiency in coding agent workflows: when an agent cannot match a known symbol through exact text search, it typically degrades into multi-step heuristics — guessing terminology, reading full files, assembling context piecemeal — each step burning additional tool calls and input tokens. zg addresses that failure mode by making semantic retrieval available through the same invocation path as literal matching, with no GPU required for the default model. This matters to practitioners building local AI search and retrieval workflows because the tool ships today and imposes no cloud dependency by default.

Four Retrieval Routes, One Index

A zg index run scans a workspace once and writes state to a /.zvec-grep/ directory, excluding .git, dependency trees, build artifacts, and anything covered by the repository's own ignore rules. Four retrieval paths are exposed. The hybrid default fuses BM25 and vector results before they reach the agent. --fts applies BM25 ranking to exact terms. --vector runs pure semantic similarity with no lexical component. --rg bypasses the index entirely and hands the query directly to ripgrep — relevant when a repository has not yet been indexed.

Indexed results carry a fresh or possibly_stale freshness flag, letting an agent act on a cached result without a status preflight. Switching embedding models requires --rebuild because vector spaces from different models are incompatible even when output dimensions match. The tool rejects ripgrep flags that alter output format — --json, --count, -l, --vimgrep — to enforce a compact, agent-readable result shape. Results are grouped by file with line spans; indexed source previews are suppressed by default unless explicitly requested.

MCP Surface and the Two-Tool Default

Running zg install detects Codex, Claude Code, Cursor, and OpenCode on the local machine and wires up MCP integration automatically. The server listens on a loopback-only endpoint at http://127.0.0.1:7999/mcp using Streamable HTTP MCP, with optional bearer authentication. The default toolset exposes exactly two tools — zvec_grep_search for intent-driven queries where the exact string is unknown, and zvec_grep_rg for known symbols, paths, or regex patterns. Index lifecycle operations remain with the CLI; the documentation explicitly states that an agent must never silently create, rebuild, or delete a persistent index.

A six-tool compatibility set that adds index create, drop, status, and server status commands is available when the server is started with zg server on --mcp-toolset full. This restraint is architecturally consistent with the argument that pipeline architecture, not better models, drives AI gains: the tool narrows the agent's surface area to retrieval and keeps destructive index management out of the agent's hands entirely.

Embedding Catalog and Remote Authorization

The documentation lists ten local embedding models and three remote Qwen endpoints. The quickstart default, local/potion-code-16m-v2, is a Model2Vec static model producing 256-dimensional output with an 8,192-token input limit. Because it uses static vector lookup rather than neural inference, GPU selection provides no throughput benefit. Heavier on-device alternatives include jina-embeddings-v2-base-code, embeddinggemma-300m, and qwen3-embedding-0.6b. On the remote side, qwen/qwen3.7-text-embedding accepts up to 128,000 input tokens; qwen/qwen3-vl-embedding adds multimodal support.

Remote access is governed by an explicit authorization model. Configuring a provider credential does not automatically permit data transfer. Each remote call requires either --allow-remote on a per-command basis or a signed workspace grant issued via zg auth grant, revocable at any time with zg auth revoke. The launch post references eleven on-device models while the current documentation lists ten — a minor discrepancy that may reflect the docs lagging a recent addition.

Benchmark Numbers and Their Limits

The evaluation figures come from the launch post, not the repository — the benchmarks section there remains a placeholder. Both runs were vendor A/B tests holding agent, model, prompt, runtime, and task constraints fixed, with the zg condition adding only a prebuilt index, MCP tools, and usage guidance. Index build cost was excluded from all reported figures.

On a 20-question SWE-QA-Bench sample, zg reduced tool calls by more than half and input tokens by nearly half, while raising the Judge score by 1.50 points. On an 80-question BrowseComp-Plus sample, accuracy moved from 98.67% to 99.00% while input tokens fell 37.56%, tool calls 43.52%, and agent time 38.58%. Separately, indexing the Django repository across 3,457 files completed in under 30 seconds on an Apple M4 Pro. Sample sizes of 20 and 80 questions are small, and the absence of independent replication is the most significant gap in the current evidence.

zg is installable today from npm as @zvec/zvec-grep, requires Node.js 22 or newer, and runs on macOS, Linux, and Windows. The Apache 2.0 license permits commercial use. The directional signal is consistent with the broader pattern that architectural specificity can outperform raw GPU scaling — targeted retrieval design reducing resource consumption rather than requiring more compute to compensate for it. Independent evaluation against larger codebases and longer agent runs remains the obvious next step.