zvec-grep (zg): a local-first search layer that unifies ripgrep, BM25 and vector search

The gap zg is trying to close between grep and an agent's context window

Plain ripgrep answers exact-match questions quickly and cheaply, but it cannot answer a question phrased in different words than the file. A vector store can answer that kind of question, but it returns chunks without the exact line numbers an agent needs to cite. zg's stated aim is to sit between the two: the README describes it as unifying "ripgrep, BM25, and vector search behind one local-first interface", so a single query can combine keyword matching, relevance ranking and semantic retrieval, then return source-linked results. The audience is explicit in the tagline, "built for humans and AI agents". In practice that means two consumers of the same index: a person typing zg query at a terminal, and an agent that calls zg as a tool. The README's worked example is telling. An agent is asked what a detective inferred from marks left by an unseen creature, and the tool call shows fts:["marks","unseen creature","inferred","detective"] alongside fuse:true, meaning the agent supplied keyword terms and the tool fused them with the vector side. That is the problem zg addresses: reducing the number of tool calls and the amount of text an agent has to read before it finds the passage worth citing.

What actually happens between zg index and a ranked result

The README states that zg is powered by zvec, which it links to as a separate project, and that the index lives in a .zvec-grep/ directory under the indexed project root. The index command takes an --embedding flag, and the example uses the value local/potion-retrieval-32m, which the README's local-first claim implies runs on the machine rather than against a hosted API. The README says remote embeddings receive data "only with your permission", so a remote embedding provider is possible but not the default path shown. On the query side, the agent tool call in the README exposes at least two parameters that matter: fts, an array of keyword terms, and fuse, a boolean that appears to control whether keyword and vector results are merged. The example passes fuse:true. The returned result is a file path with an offset and limit, which is how the agent then reads sherlock-holmes.txt at offset=5440 with limit=120. That is the data flow in the material: index once into .zvec-grep/, query with a mix of keyword terms and a natural-language question, receive ranked source locations, then read the file at those locations. The README does not document the fusion algorithm, the ranking weights, or how BM25 scores are combined with vector similarity, so anyone who needs to tune relevance cannot do it from what is published here.

Install and first index: the commands the README actually gives

The setup path is short. The README requires Node.js 22 or newer and installs globally with npm install -g @zvec/zvec-grep. The sample workflow creates a directory, downloads two public-domain texts with curl, and runs zg index --embedding local/potion-retrieval-32m. A note in the README states the index is stored in .zvec-grep/ under the indexed project root, which means the directory is per-project and will need to be excluded from version control. For agent integration the command is zg install --target opencode --yes, and the README's example then runs a prompt through OpenCode without naming zg, noting that "OpenCode chooses zg on its own". That detail matters: the integration is not a prompt template that tells the model to use the tool, it is a tool registration the host discovers. Diagnostics are handled by a --debug flag that the README says works in both direct and server modes. Three specific diagnostic commands are given: zg status --mode direct --debug reports per-file failures stored in an existing index, zg status --mode server --debug inspects recorded server indexing errors, and zg server status checks server connection state, with server logs pointed to at docs/06-server.md. The existence of direct and server modes is itself the most important operational detail here, because it implies zg can run as a one-shot process or as a long-lived server, and the failure surface differs between them.

The index is a cache you have to maintain, and the README does not say how

Everything the README shows assumes a workspace that was indexed and then queried. It does not describe incremental re-indexing, file watching, or what happens when a file changes after zg index has run. The --debug guidance is the closest thing to a staleness story: zg status --mode direct --debug reports per-file failures stored in an existing index, which tells you an index can carry failed files, but not whether a successfully indexed file is re-read when its contents change. If you adopt zg, treat the index as a build artifact with an explicit refresh step rather than something that tracks your working tree. The second constraint is the Node.js 22 floor. That is a hard requirement stated in the README and repeated in the badge, and it rules out environments pinned to older runtimes. The third is platform scope: the README claims macOS, Linux and Windows support, but the only agent integration documented in the material is OpenCode, so agents running in other hosts have no install path shown here. The fourth is the embedding model. The example pins local/potion-retrieval-32m, and the README does not list alternatives or describe how to choose one, so the quality of semantic retrieval is tied to a model choice the documentation leaves open.

How zg differs from ripgrep and from a standalone vector store

The obvious comparison is ripgrep, since zg's name and its fts parameter both point at it. The difference is statelessness. ripgrep reads the filesystem on every invocation and has no persistent artifact; zg builds a .zvec-grep/ index and answers from it, which is what lets it rank by meaning rather than by pattern match. The cost of that trade is visible in the install path: ripgrep needs a binary, zg needs Node.js 22, a global npm install, and an indexing pass with an embedding model before the first query returns anything. The second comparison is a standalone vector store or embedding pipeline, where you chunk files, embed them, and query a vector index yourself. zg's contribution there is the fusion layer and the source locations. A raw vector store returns chunks; zg returns a file path with an offset and limit that the agent reads directly, and it can be given explicit keyword terms through fts at the same time. What zg does not appear to offer, based on the README, is a way to influence that fusion. There is a fuse boolean and a --limit flag on the human query path, and that is the extent of the tuning surface described.

Licence, releases and what an upgrade costs you

zg is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. The README ships a Chinese translation at README_CN.md, and the repository lists a docs/ directory with at least an architecture document and a server document, so the documentation is broader than the README alone. The release history in the supplied material shows v0.1.5 on 2026-07-16 and v0.2.0 on 2026-08-27, with the last push to the default branch on 2026-09-10. That is a roughly six-week gap between the two releases and a version bump from 0.1.x to 0.2.x, which by convention signals a breaking change, though the material does not include a changelog or release notes describing what changed. For anyone running zg in an agent pipeline, that is the upgrade risk to plan for: the tool call shape shown in the README (root, query, fts, fuse) is the interface your agent host depends on, and a minor version bump is exactly where such a shape can shift. Nothing in the material describes a migration guide, so pinning the version in your global install is the conservative move until you can read the release notes. Note that this is a description of the licence text, not legal advice; if Apache-2.0 terms matter to your organisation, read the LICENSE file in the repository.

Editorial conclusion

zg is worth adopting if you already run an agent against a workspace and want one index that serves both the terminal and the agent, and you are willing to keep a .zvec-grep/ directory in sync with your files. It is the wrong tool if you need a single stateless grep, if you cannot run Node.js 22 or newer, or if you need the index to stay current without an explicit re-index step. Before committing, verify three things in your own checkout: that zg index --embedding local/potion-retrieval-32m completes on your file types, that zg status --mode direct --debug reports no per-file failures, and that your agent host is one of the targets zg install actually supports.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. zvec-ai/zvec-grep on GitHub