zvec-grep — Local Hybrid Search for People and Agents
Why This Matters
grep needs you to know the words. Agents that don't know them scan broadly and spend context doing it. zvec-grep , whose command is zg , puts ripgrep, BM25, and vector search behind one local interface: find by meaning, rank by relevance, then verify with exact text. It's built on zvec , the in-process vector database at alibaba/zvec . It landed in Homebrew core on October 22, 2026 at version 0.2.2. Apache-2.0. The version matters here. Homebrew still ships the Node.js-based 0.2.2 as of November 3, 2026, while 0.3.0, published on GitHub that same day, rebuilds the core in Rust and changes the CLI (
zg index becomes zg --index ). The details below reflect the 0.3.0 docs unless noted, checked November 3, 2026. What It Actually Does
- Mixed content. Indexes source code, documents, and structured text, with results linked to paths and lines. Text only, even with models that support images.
- Per-workspace index. Stored in
.zvec-grep/under the project root, one embedding model per workspace, with incremental updates by rerunning the index command. - Agent access. A local MCP server and an installer for Claude Code, Codex, OpenCode, and others.
- Exact search without an index. The ripgrep route works without building anything.
Local by Default, With One Footnote
The default model,
local/potion-code-16m-v2 , runs on CPU. Remote embedding needs provider credentials plus a separate authorization step, and the docs are clear that it sends workspace content and queries to the provider. The footnote is the benchmarks. The README's agent results use Qwen3.7 Text Embedding, which the docs list as a remote model. So those charts don't describe the default local setup. The project also notes that results vary by model and run, and that
zg works best when evidence spans files and the location is unknown. The Rust release's speed figures are vendor numbers too, comparing its own two versions. How It Compares With Our Corpus
We run a local Chroma corpus already, but it's a different kind of tool, and
zg isn't a substitute in either direction. | Our Chroma corpus | zvec-grep | |
| Scope | Whole tree, across repos | One workspace root |
| Contents | context-v/ , changelogs, Claude Code sessions, tool traces | Code, docs, and data files in that workspace |
| Freshness | Updated when we run ingest-all.sh | Incremental updates, per workspace |
| Good question | "What did we decide about X, and when?" | "Where is X handled in this repo?" |
| Exact matching | Not its job | Built in, through ripgrep |
Chroma holds our institutional memory, including prior sessions, which
zg would never see. It doesn't index source code, though, and that's the gap zg might fill. Where It Fits in Our Workflow
We haven't run it. The fair test would be a single code-heavy repo, comparing how many tool calls an agent needs with and without it. Our largely prose repos would want a different model from the code-oriented default, since the docs point to
local/potion-retrieval-32m for English documents. We'd also want to see how reindexing behaves with parallel sessions, and .zvec-grep/ should stay out of git. It could also go in the
vector-databases study under ai-labs/studies/ . For other local retrieval approaches in this batch, see deja vu Local Memory Across Your Agent Sessions and Hister Self Hosted Search over Your Browsing History . Install
bash
brew install zvec-grep # 0.2.2 as of this writing
zg index # 0.2.2 syntax; 0.3.0 uses zg --index
zg query --human "where are permissions checked" --limit 3