zg (zvec-grep) – Zvec AI's Open-Source Local-First Unified Retrieval Foundation Tool

1. What is zg

zg (zvec-grep) is an open-source, local-first unified retrieval foundation tool developed by Zvec AI, designed for developers and AI Agents. This tool integrates the precise matching capabilities of ripgrep, BM25 lexical retrieval, and vector semantic retrieval into a single retrieval pipeline, effectively bridging the lexical gap between natural language intent and the actual wording in code or documentation, thereby enabling a complete retrieval process from fuzzy exploration to precise localization. By default, file scanning, Embedding generation, index building, and retrieval queries are all completed on the local device. It includes lightweight on-device models and can be run without GPU or external services, balancing data privacy and retrieval efficiency.

Technical positioning and domain: This falls within the intersection of information retrieval and semantic search engines, specifically targeting code retrieval and knowledge base management within the developer toolchain. zg combines two major technical approaches—lexical matching and semantic understanding—to provide a unified retrieval interface for local codebases and document collections. Its design goal is not to replace traditional text search tools, but to build upon them with retrieval-enhancing solutions that understand intent.

Development background: zg was developed by the Zvec AI team, which has ongoing technical expertise in vector databases and local-first infrastructure. The motivation for open-sourcing the project stems from the current overreliance of mainstream semantic retrieval solutions on cloud-based APIs or limitations in offline scenarios due to model resource constraints. Meanwhile, developers and AI Agents have urgent needs for retrieval capabilities that can bridge lexical gaps in local code audits and troubleshooting. zg chooses to use an embedded in-process database as its foundation, localizing both vector and BM25 indexes to reduce deployment complexity and avoid data transmission risks.

Core value: This tool addresses the core pain point in codebase and document retrieval: "knowing what is needed but not knowing the right keywords." Developers or AI Agents can directly locate corresponding code symbols, configuration items, and document sections using natural language descriptions of business phenomena or functional semantics, and then verify the results using ripgrep's precise matching. Additionally, its native support for MCP and automatic Agent discovery mechanism significantly reduces the integration cost of adding retrieval capabilities to AI programming tools. Real-world testing has shown that it can reduce tool calling and Token consumption by over 40%.

Technical features: zg includes 11 built-in on-device Embedding models and can run with as few as 16M parameters, without requiring a GPU or remote API. It uses the Zvec in-process database to embed the storage of vector and BM25 indexes, eliminating the need to deploy a separate database service. The index supports incremental updates and can be reused across multiple queries and Agent tasks over the long term. It also automatically parses code symbol hierarchies and document section structures, providing retrieval results with verifiable location metadata.

2. Key Features

• Hybrid Retrieval Paradigm: Combines semantic vectors with BM25 lexical retrieval for multi-path recall, then merges and deduplicates the results using the RRF (Reciprocal Rank Fusion) algorithm. This mechanism balances semantic relevance and lexical match accuracy, enabling the discovery of conceptually similar content when user intent is ambiguous, while preserving high-priority matches when lexical precision is required.

• Semantic Retrieval: Identifies relevant code and documentation based on natural language intent, without the need to pre-determine keywords. For example, entering "restore theme preferences" can directly locate the hydratePreferences function, effectively bridging the gap between user expressions and code naming conventions.

• BM25 Lexical Retrieval: Sorts text fragments by term frequency using a weighted approach (an advanced version of TF-IDF), quickly focusing on the most relevant candidate results. This algorithm provides search engine-grade relevance scores in text-dense areas such as code comments and document content.

• ripgrep Exact Matching: Performs exhaustive exact verification for known symbols, function names, configuration keys, or text patterns. This layer of retrieval, positioned at the end of the chain, ensures that developers can obtain fully deterministic matches when they have a clear target, without introducing noise from semantic matching.

• Multi-format Content Structured Extraction: Automatically parses code symbol hierarchies, document section structures, and data files while preserving location metadata. Retrieval results not only return matching fragments but also indicate the class, method, or section where the symbol is located, facilitating quick navigation and contextual understanding.

• On-device Embedding Generation: Includes 11 lightweight Embedding models, which run natively on the device by default, eliminating the need for a GPU to perform vectorization. Model switching and resource usage during runtime are configurable, allowing users to choose a balance point between retrieval quality and performance overhead.

• Embedded Index Storage: Implements persistent management of vectors and BM25 indexes using the Zvec in-process database, without requiring the deployment of a separate database service. This storage model is suitable for local repositories, CI environments, and sandboxed development containers, offering zero external dependencies and fast startup capabilities.

• Incremental Index Updates: After the initial full index build, subsequent updates only process changed content, allowing the index to be reused across multiple queries and Agent tasks. This capability ensures that continuous retrieval over large codebases remains low-maintenance.

• MCP Protocol Integration: Exposes retrieval capabilities to Agents such as Codex, Cursor, and Claude Code via the Model Context Protocol. Agents can autonomously invoke semantic and exact retrieval to perform tasks like code comprehension and fault localization. The zg install command automatically detects locally installed Agents and completes MCP configuration, eliminating the need for manual configuration file editing during integration.

3. How to Use

1. Environment Preparation: Requires a Node.js environment (recommended version v18 or higher), supporting Windows, macOS, and mainstream Linux distributions. No GPU or standalone database service is needed, and the installation process does not involve compiling system-level dependencies.

2. Install the Tool: Install zg globally via npm by executing npm install -g @zvec/zvec-grep in the terminal to complete the deployment. After installation, verify the version with zg --version. If the correct output is displayed, you can proceed with further operations.

3. Agent Automatic Integration: Run the zg install command. The tool will automatically scan locally installed AI programming agents such as Codex, Cursor, and Claude Code, and complete the MCP server configuration. This command does not require manual path specification or editing of the MCP configuration file; the entire process is automated.

4. Build Index: Enter the target repository directory and execute zg index to build local semantic and BM25 indexes for the code and documentation. The first build will scan all supported file types, while subsequent runs will only process changed parts. After the build is complete, the index is persisted in the Zvec in-process database within the directory.

5. CLI Search: Use natural language to search local content via the terminal with zg query --human "your question". The output includes matching files, relevant code snippets, and location metadata. You can also use zg query --regex "pattern" to directly invoke the exact match capability of the ripgrep layer.

6. Agent Search: Ask questions in natural language directly in the connected Agent conversation window. The Agent will automatically call zg via the MCP protocol to perform the search and return results. This mode is ideal for querying during coding sessions, such as "Where is this feature implemented?" or "Which files are involved in this error?"

7. Custom Embedding Models: In the configuration file, you can switch between the built-in Embedding model or specify a remote Embedding API (requires explicit authorization). By default, a lightweight model with approximately 16M parameters is used. Users can adjust based on a trade-off between search accuracy and resource consumption.

8. Notes: It is recommended to limit the indexed directories to code repositories or document sets, avoiding indexing of system temporary directories. The remote Embedding API feature is disabled by default and can only be enabled when the user explicitly configures the key and endpoint, ensuring the local-first principle remains intact.

4. Pros and Cons Analysis

5. Comparative Analysis with Similar Tools

Selection Recommendations: For individual developers or deep users of AI Agents, zg provides a complete workflow from natural language intent to precise code verification, making it especially suitable for scenarios requiring frequent exploratory and intent-driven searches in code repositories. Its native MCP support seamlessly integrates search capabilities into tool sessions like Codex and Cursor, improving search efficiency while reducing token consumption. If the primary need is to quickly locate known symbols or specific patterns in configuration files, and there is no requirement for semantic understanding, ripgrep remains the most straightforward lightweight option, with its single-binary deployment and minimal memory usage still offering advantages in purely exact matching scenarios.

For team-level code search and cross-repository navigation needs, Sourcegraph's server-side indexing architecture provides a better collaborative experience and richer code insights, but its deployment and maintenance costs are significantly higher than local tools. The Silver Searcher excels in speed but lacks semantic understanding and Agent integration capabilities, making it suitable for highly deterministic query patterns in fast lookup tasks. Overall, zg demonstrates differentiated competitiveness in search workflow completeness and AI ecosystem compatibility, while traditional tools still remain irreplaceable in terms of simplicity for straightforward exact matching.

6. Editor's Summary

zg demonstrates a noteworthy innovative approach in the design paradigm of retrieval tools. Traditional retrieval tools have long remained confined to the lexical matching dimension, whereas zg introduces an on-device semantic model, bringing query understanding capabilities down to the local environment. At the same time, it retains the precise matching layer of ripgrep, creating a complete retrieval pipeline that balances fuzzy discovery with accurate verification. This layered design avoids the common compromise of sacrificing precision for semantic recall, making it technically sound and rational.

In terms of practical value, zg's compatibility with AI Agent workflows is commendable. By automatically integrating with mainstream coding agents such as Codex, Cursor, and Claude Code via the MCP protocol, it effectively reduces the token consumption and frequency of tool calls during the codebase retrieval phase. Empirical data shows that it can cut overhead by more than 40%. This achievement directly translates into reduced developer maintenance costs and response latency, rather than merely停留在概念验证层面 (staying at the concept validation stage).

In terms of target users, zg precisely addresses two categories: first, the codebase navigation needs of local developers, especially the ability to locate specific functions within large legacy codebases using natural language; second, developers who rely on AI programming assistants as their core workflow. zg provides agents with a locally self-sustained retrieval infrastructure, reducing their dependency on cloud-based retrieval services.

Zvec AI positions zg as a retrieval infrastructure rather than a single tool. This strategic direction suggests that future development may focus on unified retrieval across multiple repositories, cross-project knowledge association, and more granular code semantic understanding. As retrieval serves as the bridge layer between AI applications and the code world, its value will continue to grow with the increasing adoption of Agent-based programming.

7. Application Scenarios

• Codebase Intent Exploration: Developers or AI Agents can describe business phenomena or functional behaviors in natural language, and zg locates the corresponding code implementation through semantic search. For example, describing "restore user preferences after login" can retrieve the hydratePreferences function and related storage modules without needing to remember the exact naming beforehand. This scenario is ideal for developers who are new to a project and need to quickly get familiar with an unfamiliar codebase.

• Fault Localization and Root Cause Analysis: When dealing with error logs or vague user feedback, the Agent uses zg's semantic search to quickly identify relevant code paths, configuration files, and documentation. When developers are troubleshooting issues in production environments, they can simply paste the semantic key points of the error message to skip irrelevant files and directly access potentially related code sections, reducing the time needed to locate the issue.

• Cross-file Code Understanding: When trying to understand the full implementation of a feature in a large codebase, natural language queries can retrieve related functions, interface definitions, and call relationships across modules and languages. For example, asking "how does the user permission system work" can simultaneously retrieve permission validation functions, configuration items, database table structure comments, and related documentation sections, forming a horizontal view without manually expanding directories layer by layer.

• Local Knowledge Base Q&A: After indexing technical documents, research materials, notes, and other Markdown/text files, accurate answers can be retrieved quickly through natural language queries, along with source files and specific section locations. This scenario is suitable for personal knowledge management, internal team documentation searches, and information queries in offline environments. The search results include citation information, making it easy to verify the original context.

• Automated Search in CI/CD Pipelines: Embed zg as an auxiliary code inspection tool in the CI/CD pipeline. When tests fail or lint errors occur, zg can automatically trigger semantic searches of the relevant code, assisting in analyzing the cause of failure and correlating it with recent changes. The zero-dependency nature of the embedded index allows for rapid deployment in containerized build environments, without requiring additional service components.

8. FAQ

Q: Does zg's semantic search capability require GPU or external API support?
A: No. zg includes 11 types of on-device Embedding models and by default uses the smallest model with approximately 16M parameters, which can run normally on a CPU. The tool will only call external services when you explicitly configure a remote Embedding API and desire stronger semantic understanding capabilities. This feature is disabled by default to ensure local priority.

Q: Can zg and ripgrep be used together?
A: Yes. zg integrates regular expression matching capabilities at the level of ripgrep, while maintaining the search speed characteristics of rg. If you are already using ripgrep in your workflow, you can continue using your existing commands without any migration. zg only provides additional value when semantic search or BM25 relevance ranking is needed.

Q: How long does the first index build take? How much disk space will the index occupy?
A: The first index build requires scanning all target files and generating Embedding vectors. The time depends on the number of files and their average size, typically taking a few minutes for repositories with thousands of files. The index size is positively correlated with the total number of files and their content length. As a rough estimate, it can be expected to occupy about 50MB per 10,000 text files. Specific values and configuration options can be found in the official documentation.

Q: What file formats does zg support for content extraction?
A: zg automatically parses the symbol hierarchy of code files (classes, function, method definitions), the section structure of document files (Markdown heading levels), and common data file formats. For file types that cannot be parsed structurally, zg degrades to plain text content extraction, retaining only basic text fragments for lexical and semantic search.

Q: Can zg be used normally on a Windows system?
A: Yes. zg is implemented based on Node.js and supports Windows, macOS, and mainstream Linux distributions. On Windows, it is recommended to use Windows Terminal or PowerShell for command-line operations. The Agent's automatic discovery feature also works with installed desktop versions of Codex and Cursor applications.

9. Project Links

• GitHub Repository: https://github.com/zvec-ai/zvec-grep —— Official open-source repository for zg, containing complete source code, README user guide, configuration instructions, and version release history.