On September 2, 2026, the developers behind zvec quietly dropped a tool that aims to end the tired argument over grep versus semantic search. zg, short for zvec-grep and powered by the zvec project, is a local-first search layer that unifies three retrieval paradigms behind one interface: ripgrep for exact text and regex, BM25 for lexical ranking, and vector search for meaning. The result is a single search engine that works for a person typing in a terminal and for an AI agent making tool calls, with the workspace index kept on the machine by default.
One Layer, Three Search Engines
Most developers have felt the split. ripgrep finds a string blindingly fast, but it cannot find what you meant. A vector database finds related concepts, but it is fuzzy on exact identifiers and can return plausible noise. zg refuses to make you choose. Under the hood, the engine exposes two complementary retrieval paths behind the same product boundary.
The first path is indexed retrieval, which combines BM25 full-text search with vector candidates and fuses their ranks using reciprocal rank fusion (RRF). This path is best for intent, related concepts, and ranked keywords, and it draws on data in the workspace index. The second path is managed ripgrep, which is exhaustive by default, requires no embedding model, and is best for known text, symbols, paths, and regular expressions. Both paths apply workspace-aware filtering and return file-oriented results readable from the terminal or usable as agent context.
That architecture matters. Semantic discovery narrows the search space, while ranked lexical retrieval anchors exact identifiers, and compact evidence reduces broad scans and repeated tool calls. The design centers on RRF fusion, where a document does not have to win either ranking outright; it can surface by being consistently relevant across both lexical and vector orderings.
Built for Humans and Agents Alike
The defining choice in zg is the dual interface. People and scripts enter through the zg CLI, while agents normally enter through a local Streamable HTTP MCP endpoint configured by a single install command. The CLI routes indexed operations through auto, server, or direct modes, and both the server and direct modes call the same engine; the difference is process lifetime, not search behavior.
Agent integrations cover Codex, Claude Code, Qwen Code, Qoder, Cursor, and OpenCode. In the project demo, an OpenCode agent given a natural-language question about a Sherlock Holmes story independently chose the zvec-grep tool, pulled the relevant passage, and answered with file-and-line citations after a tiny number of reads. The agent is not forced into the tool, which is the point.
For a technically literate reader, the trust boundary is where zg earns its name:
- Workspace scanning, managed ripgrep, index storage, and local embedding models stay on the machine.
- The local MCP server listens on loopback only, protected by Bearer authentication.
- Remote embedding providers receive query or workspace content only after explicit, one-time or workspace-scoped authorization.
- zg runs with local embedding by default, so the common case never leaves the box.
The Numbers Behind the Retrieval
zg ships benchmarks that isolate its effect using controlled, paired A/B runs. The only intended difference between baseline and treatment is access to zg, with tasks, model, agent, prompt, and limits held constant. Two suites anchor the claims.
SWE-QA-Bench uses Claude Code with Claude Opus 5 at high reasoning effort across 20 repository-level tasks, probing cross-file and multi-hop software-engineering questions. BrowseComp-Plus uses Codex at medium reasoning effort across 100 cases and measures multi-document evidence retrieval over a large fixed corpus. Both zg profiles used Qwen3.7 text embeddings, a nice tie-back to the Qwen ecosystem.
The reported direction is consistent: answer quality holds at a similar level across runs, while input tokens and tool calls drop because the agent spends fewer tool calls searching. The benchmark authors are honest that results vary by model and run, and they advise running balanced trials because trajectories diverge stochastically. Real-world cases on Pylint, Matplotlib, and Django trace architecture, data-flow, and design-rationale questions across multiple files where the exact target location is unknown.
The practical checklist for a developer evaluating zg on their own workload:
- Run paired runs with the same model and reasoning settings; only add the zg index and tools to the treatment.
- Keep prompts general-purpose, and let the agent decide when to use zg rather than forcing it.
- Run an equal number of independent trials for baseline and treatment, because agent trajectories vary run to run.
- Smoke-test that the installed tool actually resolves in the agent environment before trusting longer runs.
- Keep reference answers out of the indexed workspace to avoid leakage.
zg is released under Apache 2.0 and requires Node.js 22 or newer, installed from the @zvec/zvec-grep npm package. The repository has drawn strong early community interest, and the surrounding ecosystem is already growing: agent skills, a Hermes memory provider on hybrid BM25 plus vector retrieval, and a Prime-Agent package all point at a wider adoption curve. For anyone building local-first coding agents or hunting across large workspaces, zg reframes search as a single, local layer that serves both the human at the keyboard and the agent at the tool.
Comments