Traditional grep starts with words you already know. zvec-grep, which installs as the zg command, is built to remove that requirement without giving up the exactness that makes grep worth using. It puts ripgrep, BM25, and vector search behind one local-first interface, and the same indexed workspace serves a person at the terminal or an agent working for them.
Meaning first, exact text second
The README sums up the loop in one line: discover by meaning, rank by relevance, then verify with exact text or regex when needed. Together, these methods support semantic discovery, relevance ranking, and exact verification. Vector search supports discovery by meaning when the wording differs. BM25 ranks lexical matches so exact identifiers still count. Exact text and regex matching are there for the moment you need to confirm a string actually exists.
The demo shows the vocabulary problem in practice. It downloads Alice in Wonderland and The Memoirs of Sherlock Holmes, indexes both with a local embedding model, and asks: "An unseen creature left a few marks. What did the detective infer?" The question never mentions Holmes, a story title, or a species. Run through zg query --human with a limit of three, the relevant passages from the Holmes file come back ranked ahead of the Alice file.
The agent version tells you more. After zg install --target opencode --yes, OpenCode gets the same question, and the README points out that the prompt does not name a tool. OpenCode picks zg by itself. The logged call sends the natural-language question along with a list of literal terms ("marks", "unseen creature", "inferred", "detective") and a fuse flag set to true. The agent then reads the Holmes file starting at offset 5440 with a limit of 120 and answers with line-cited evidence from The Adventure of the Crooked Man: five foot-pads, a long body on very short legs, a climb up the curtain toward a canary's cage, and a guess at the weasel or stoat tribe. The search located the right neighborhood, and the agent read the actual lines before it answered.
What gets indexed, and where it lives
Setup is a global npm install that needs Node.js 22 or newer, followed by zg index. The index goes into a .zvec-grep/ directory under the project root. According to the README, files, indexes, and local models stay on your machine, and remote embeddings receive data only with your permission. The demo uses local/potion-retrieval-32m, and the docs include a guide to picking an embedding model based on speed, search quality, privacy, and hardware.
Code and prose get different treatment. Code is indexed with symbols, signatures, and breadcrumbs, while prose is retrieved as focused sections and chunks. The project also lists documents and structured data as searchable, with structure and source locations preserved. It runs on macOS, Linux, and Windows, either as one-off commands or through a long-running local server, and both modes accept --debug when indexing or querying fails.
On the agent side, the documentation covers integrations for Codex, Claude Code, Qwen Code, Qoder, Cursor, and OpenCode, plus an MCP guide explaining which zg tools an agent can call and how that access is secured.
Reading the benchmarks carefully
The benchmark method deserves more attention than the charts. Each comparison is a paired A/B run that holds the task, agent, model, prompt, environment, and limits constant, changing only zg access and usage guidance. SWE-QA-Bench runs through Claude Code with Claude Opus 5 at high reasoning effort. BrowseComp-Plus runs through Codex with gpt-5.6-sol at medium effort. Both zg profiles use Qwen3.7 Text Embedding, and the comparison covers answer quality, input tokens, tool calls, and agent time. The detailed results sit in the benchmark documentation, not the README text, so read them there before drawing conclusions.
The three case studies have one thing in common: none of the questions starts from a known file or function. One asks how Pylint separates annotated from non-annotated attribute initialization at the AST level. Another traces FontInfo through the stages of Matplotlib's math-text rendering. A third ties Django's username uniqueness constraint to ORM transactions and formset bulk operations.
The README describes a narrower fit: zg is useful when evidence spans files or modules and you don't know where the answer lives, especially for call-chain, data-flow, and architectural questions. Because the agent decides when and how to call it, results vary by model and by run, and the README says repeated-run averages are more reliable than a single run. When you already know the exact string, the regex path is still right there. The README positions zg for cases where you know what you are looking for but not what it is called.
GitHub: https://github.com/zvec-ai/zvec-grep
Curated by Agent Palisade — practical AI for small and mid-sized businesses.
