zvec-grep: Search Code and Documents by Meaning
zvec-grep, or zg, is a local-first search tool for source code, documents, and structured data. It brings together exact or regular-expression search through ripgrep, ranked keyword search with BM25, and vector search for similarity in meaning. It is useful when you know what a piece of code does but not its name, or want to find an existing document about a topic.
For a known identifier, exact search is often the simplest starting point. For “where are execution fees allocated?”, semantic search can suggest relevant code even if the implementation uses different words. Similarity is a way to find candidates, not proof that the tool understands the business rule.
What an index adds
Indexing breaks files into searchable pieces while preserving useful structure and source locations. Code results can include symbols and signatures; prose results can point to sections and passages. This helps you decide which source to open next without first reading every file.
Results are not restricted to file coordinates. The default output is compact Markdown for agents; --human provides terminal-oriented output with full previews by default. Output length depends on the query, result count, and preview settings. A returned range is a starting point: read callers, tests, surrounding definitions, or the whole file when the task requires them.
Vector indexes explain how approximate search reduces comparisons; returned neighbors still need checking against the source.
Build and query a workspace index
These examples require Node.js 22 or newer and the official npm package. npx can download the package if it is not installed. Run commands from the directory you intend to index. Choose one initial model for that workspace:
# Code repository
npx @zvec/zvec-grep index --embedding local/potion-code-16m-v2
For a multilingual document collection, use this alternative instead:
npx @zvec/zvec-grep index --embedding local/potion-multilingual-128m
The index is stored in .zvec-grep/ beneath the project root. Keep this generated index out of version control. Local models may need a first-use download; local inference does not mean installation is offline. The tool also supports remote embedding providers, which require authorization to receive data. Check the model choice before indexing sensitive material.
In an indexed Python repository, search for fee-related logic:
npx @zvec/zvec-grep query "order execution slippage commission fee" -g '*.py' --limit 3 --human
In an indexed documentation repository with a docs/ directory, search for existing coverage:
npx @zvec/zvec-grep query "personal knowledge system" -g 'docs/**' --limit 3
Here -g filters paths and --limit caps results per query group. If a page covers the same subject, consider updating it or linking to it. A small result limit is convenient for a first look, but it cannot establish that a topic is absent.
Check the source before changing it
Open promising results in the current working tree and confirm the behavior against tests or supporting documents. If results are missing or stale, check the indexed scope and status, then refresh the index as needed:
npx @zvec/zvec-grep status
npx @zvec/zvec-grep index
These commands assume an existing workspace index and reuse its model configuration. Search relevance and performance vary with the corpus, model, and hardware. Neither a short result nor a local index guarantees a correct patch or prevents an assistant from exceeding the requested scope.
Related tools
QMD focuses on searching document collections such as Markdown notes. Basic Memory supports linked notes that people and assistants can read and edit across sessions. These are optional complements, not mandatory layers. Agent Memory and Retrieval explain how to combine retrieval with source inspection and current instructions.