Qwen Developers Open-Sources zg (zvec-grep): A Local-First Search Layer Unifying ripgrep, BM25, and Vector Search
Coding brokers spend a big share of their device price range on search. When the goal is a identified image, ripgrep solutions it precisely. When the goal is a habits described in plain language, key phrase matching typically misses, and the agent falls again to guessing phrases, studying entire information, and assembling context by hand. Each of these detours prices device calls, tokens, and wall-clock time.
The Qwen Developer team announced zg (zvec-grep), an open-source local-first search layer that places semantic search, BM25, and ripgrep behind one interface for each people and brokers. The code ships below the zvec-ai GitHub organization with an Apache 2.0 license.
Is it deployable? Yes, at this time. It installs from npm as @zvec/zvec-grep, requires Node.js 22 or newer on macOS, Linux, or Windows, wants no GPU with the default mannequin, and the Apache 2.0 license permits industrial use.
One index, 4 retrieval routes
zg indexes a workspace as soon as and then exposes a number of methods to question it. The retrieval pipeline docs outline 4 routes: a hybrid default that mixes intent with lexical anchors, --fts for BM25-ranked actual phrases, --vector for conceptual similarity with no lexical rating, and --rg for exhaustive literal or regex matching. The first three learn the index. The --rg route wants no index in any respect, which issues when a repository has not been listed but.
An nameless workspace index lives in <root>/.zvec-grep/. Both .git and .zvec-grep are all the time excluded, together with frequent dependency, construct, cache, and log directories, plus something the repository’s personal ignore guidelines exclude. Re-running zg index updates incrementally; altering the embedding mannequin requires an express --rebuild as a result of vector areas from totally different fashions are incompatible even at matching dimensions.
Indexed outcomes report a freshness state of recent or possibly_stale, so an agent can act on a good-enough end result as a substitute of working a standing preflight first.
The MCP floor brokers truly see
zg set up detects Codex, Claude Code, Cursor, and OpenCode on the machine and wires up the native MCP integration. The server speaks Streamable HTTP MCP on a loopback-only endpoint at http://127.0.0.1:7999/mcp, with optionally available bearer authentication.
The design determination price noting is restraint. Per the MCP guide, the default agent toolset exposes precisely two instruments: zvec_grep_search for when the intent is thought however the actual string isn’t, and zvec_grep_rg for when a logo, path, or regex is thought. Index lifecycle stays with the CLI. A six-tool compatibility set that provides index create, drop, standing, and server standing exists however is opt-in by zg server on --mcp-toolset full, and the docs state that an agent mustn’t ever silently create, rebuild, or delete a persistent index.
Output is formed for context economic system. Results come again grouped by file with line spans, and listed supply previews are omitted by default until requested. zg additionally rejects output-changing ripgrep flags similar to --json, --count, -l, and --vimgrep so the compact end result format holds.
Embeddings run on machine by default
The embedding catalog presently paperwork ten native fashions and three distant Qwen endpoints. The quickstart default, native/potion-code-16m-v2, is a Model2Vec static mannequin with a 256-dimension output and an 8,192-token enter restrict; as a result of it makes use of static vector lookup, choosing a GPU doesn’t velocity it up. Heavier native choices embody jina-embeddings-v2-base-code, embeddinggemma-300m, and qwen3-embedding-0.6b. Remote choices run to qwen/qwen3.7-text-embedding at 128,000 enter tokens and the multimodal qwen/qwen3-vl-embedding.
Remote use is gated. Configuring a supplier credential doesn’t authorize information switch; that requires both --allow-remote for a single command or a signed workspace grant through zg auth grant, revocable with zg auth revoke. The launch submit cites eleven on-device fashions towards ten within the present docs, a small discrepancy price flagging.
What the benchmark numbers say
The analysis numbers seem within the launch submit, not within the repository, the place the benchmarks part continues to be a placeholder. Both runs have been paired A/B exams holding agent, mannequin, immediate, runtime, and job constraints mounted, with the zg situation including solely a prebuilt index, MCP instruments, and utilization steerage. Index construct price is excluded from the tables.
On a 20-question SWE-QA-Bench pattern, zg minimize device calls by greater than half and enter tokens by practically half whereas elevating the Judge rating by 1.50 factors. On an 80-question BrowseComp-Plus pattern, accuracy moved from 98.67% to 99.00% whereas enter tokens fell 37.56%, device calls 43.52%, and agent time 38.58%. Separately, indexing the Django repository (3,457 information) is reported to complete in below 30 seconds on an Apple M4 Pro.
Sample sizes of 20 and 80 questions are small, and the reported reductions come from the seller’s personal runs, so impartial replication is the plain subsequent step.