Qwen Open-Sources zg (zvec-grep) Search Layer

Zg (zvec-grep) is the new open-source search layer from the Qwen Developer team, and it is trying to solve a problem that has quietly been eating coding agents alive: the cost of looking things up.

Ripgrep is perfect for exact symbols. But when an agent needs to find behavior described in plain language, keyword matching falls apart, forcing the agent to guess terms, read entire files, and stitch context together by hand, which drains tool calls, tokens, and time. That detour is costly. So the team built a single local-first interface that puts semantic search, BM25, and ripgrep behind one command. It's live today. The code sits under the zvec-ai GitHub organization, licensed under Apache 2.0, and you can install it from npm as @zvec/zvec-grep. Don't underestimate that fix.

One Index, Four Ways to Ask

The core idea is simple. Index a workspace once, then query it through several routes, and the retrieval pipeline defines four distinct paths that each answer a different kind of question. A hybrid default combines intent with lexical anchors, which gives you a balanced starting point without much fuss. The --fts flag runs BM25-ranked exact term matching, so it's perfect when you need precision on literal words. The --vector flag handles conceptual similarity, but it's got no lexical ranking at all, meaning you trade exactness for meaning. And --rg provides exhaustive literal or regex matching, which can be slow but leaves no stone unturned if you know the exact pattern you're hunting for. Four routes. One workspace. Pick your tool.

The first three read from the index. The --rg route does not need one, which matters when a repository has not been indexed yet. An anonymous workspace index lives in <root>/.zvec-grep/. Both .git and .zvec-grep are always excluded, alongside common dependency, build, cache, and log directories. Repository ignore rules are respected too.

Re-running zg index updates things incrementally. Changing the embedding model, however, requires an explicit --rebuild because vector spaces from different models are incompatible even when dimensions match. Indexed results report a freshness state of fresh or possibly_stale, which lets an agent act on a good-enough result without running a status preflight first.

What Agents Actually See

The design restraint is worth noting. Per the MCP guide, the default agent toolset exposes exactly two tools: zvec_grep_search for when intent is known but the exact string is not, and zvec_grep_rg for when a symbol, path, or regex is known. Index lifecycle stays with the CLI. A six-tool compatibility set exists with index create, drop, status, and server status, but it is opt-in through zg server --mcp-toolset full.

The docs state a hard rule. An agent must never silently create, rebuild, or delete a persistent index, and that restriction holds without exception. Output is shaped for context economy, so results come back grouped by file with line spans. Indexed source previews are omitted by default unless requested, which keeps the payload lean. Zg rejects output-changing ripgrep flags like --json, --count, -l, and --vimgrep to preserve the compact result format intact. It's a strict boundary. Don't cross it. But the design does favor speed over convenience, and that trade‑off is deliberate.

Embeddings That Stay on Device

Zg installs detect Codex, Claude Code, Cursor, and OpenCode on the machine, then wire up the local MCP integration. The server speaks Streamable HTTP MCP on a loopback-only endpoint at http://127.0.0.1:7999/mcp, with optional bearer authentication. That loopback-only choice keeps the data local by default.

The embedding catalog currently documents ten local models and three remote Qwen endpoints.

The quickstart default, local/potion-code-16m-v2, is a Model2Vec static model with a 256-dimension output and an 8,192-token input limit. Because it uses static vector lookup, selecting a GPU does not speed it up. Heavier local options include jina-embeddings-v2-base-code, embeddinggemma-300m, and qwen3-embedding-0.6b. Remote options run up to qwen/qwen3.7-text-embedding at 128,000 input tokens and the multimodal qwen/qwen3-vl-embedding.

Remote use is gated. Configuring a provider credential does not authorize data transfer. That requires either --allow-remote for a single command or a signed workspace grant via zg auth grant, revocable with zg auth revoke. The launch post cites eleven on-device models against ten in the current docs, a small discrepancy worth flagging.

What the Benchmarks Say

The evaluation numbers appear in the launch post, not in the repository. The benchmarks section there is still a placeholder. Both runs were paired A/B tests that held agent, model, prompt, runtime, and task constraints fixed, so the only meaningful difference between the two conditions was the addition of a prebuilt index, MCP tools, and usage guidance in the zg setup. Index build cost is excluded from the tables. It's not counted.

On a 20-question SWE-QA-Bench sample, zg cut 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 (3,457 files) is reported to finish in under 30 seconds on an Apple M4 Pro.

Small sample sizes. Twenty and eighty questions don't tell us much. The reported reductions come from the vendor's own runs, which means there's no independent check on those numbers, and that's a serious limitation when you're trying to decide whether any real-world gain actually exists. So independent replication is the obvious next step before we draw firm conclusions. It's the only way to know.

Local-First at the Core

The requirements are modest: Node.js 22 or newer on macOS, Linux, or Windows, no GPU needed with the default model, and Apache 2.0 permits commercial use. Indexing, embedding, and retrieval run on device. Remote embeddings need explicit per-command or workspace authorization, which keeps the local-first promise intact.

• zg unifies ripgrep, BM25, and vector search behind one local-first interface for humans and agents.
• The default MCP toolset exposes only two tools; index lifecycle stays with the CLI by design.
• Indexing, embedding, and retrieval run on device; remote embeddings need explicit authorization.
• Vendor A/B runs report roughly 40% to 50% cuts in tool calls and input tokens on small samples.
• Apache 2.0, npm-installable, Node.js 22+, no GPU needed with the default model.

The real question is whether the agent ecosystem adopts a tool that asks for restraint. It's a bet on less. The two-tool default assumes that less surface area means fewer mistakes, and that's a quiet wager on simplicity over raw capability. The freshness state on indexed results is another quiet innovation, letting agents act on possibly stale data instead of stalling, so they don't freeze up waiting for perfect information. Zg (zvec-grep) is available now. But the only way to know if those benchmark numbers hold is to run it yourself, and you can't trust anyone else's claims here.

Frequently Asked Questions

What is zg (zvec-grep) and what problem does it solve?

Zg (zvec-grep) is an open-source search layer from the Qwen Developer team. It solves the problem of coding agents incurring high costs when looking up behavior described in plain language, which keyword matching like ripgrep cannot handle efficiently. It provides a single local-first interface that puts semantic search, BM25, and ripgrep behind one command.

How does the --vector flag in zg differ from the --fts flag?

The --vector flag handles conceptual similarity but has no lexical ranking, trading exactness for meaning. The --fts flag runs BM25-ranked exact term matching, which is perfect when precision on literal words is needed. These are two distinct retrieval paths among the four that zg offers.

Why does changing the embedding model require an explicit --rebuild?

Changing the embedding model requires an explicit --rebuild because vector spaces from different models are incompatible even when dimensions match. The article states that re-running zg index updates things incrementally, but a model change cannot be updated incrementally due to this incompatibility. Thus, a full rebuild is necessary.

What is the default MCP toolset for agents, and what is the hard rule about index lifecycle?

The default MCP toolset exposes exactly two tools: zvec_grep_search for when intent is known but not the exact string, and zvec_grep_rg for when a symbol, path, or regex is known. The hard rule is that an agent must never silently create, rebuild, or delete a persistent index, and that restriction holds without exception. Index lifecycle stays with the CLI, and a full toolset is opt-in separately.

How does zg ensure data stays local, and what are the authorization requirements for remote embeddings?

Zg ensures data stays local by using a loopback-only endpoint for its MCP server (http://127.0.0.1:7999/mcp) with optional bearer authentication, and remote embeddings need explicit authorization. Configuring a provider credential does not authorize data transfer; it requires either --allow-remote for a single command or a signed workspace grant via zg auth grant, revocable with zg auth revoke. This keeps the local-first promise intact.