zg - Zvec AI's open-source local-first unified retrieval foundational tool

What is zg

zg (zvec-grep) is an open-source local-first unified retrieval foundational tool from Zvec AI, built for developers and AI Agents. The tool integrates ripgrep exact matching, BM25 lexical retrieval, and vector semantic retrieval into one, bridging the vocabulary gap between natural language intent and the actual wording of code/documents, enabling a complete retrieval chain from fuzzy exploration to precise location. zg supports file scanning, Embedding, indexing, and retrieval all completed locally on the device by default, with built-in lightweight on-device models, requiring no GPU or external services, balancing privacy and efficiency.

Main features of zg

Semantic retrieval: Discover relevant content in code and documents by natural language intent, without needing to guess the exact keywords in advance.
BM25 retrieval: Rank text snippets by relevance based on term frequency weighting, quickly focusing on the best-matching results.
Hybrid retrieval: Combine semantic vectors and BM25 multi-path recall, with RRF fusion for deduplication and unified ranking.
ripgrep exact matching: Perform exhaustive exact verification of known symbols, function names, configuration keys, or text patterns.
Multi-format content extraction: Automatically parse code symbol hierarchies, document section structures, and data files, preserving location metadata.
Local on-device Embedding: Built-in 11 lightweight models, running on-device by default, with no GPU or data upload required.
Embedded index storage: Implements vector and BM25 indexes based on the Zvec in-process database, with no need to deploy a separate service.
Incremental index updates: After the initial build, only changed content is processed, and the index can be reused long-term across queries and Agent tasks.
CLI + MCP dual entry points: Provides a command line for human use, and is also callable by Agents such as Codex and Cursor through the MCP protocol.
Automatic Agent integration：zg install One-click automatic discovery of Agents installed on the machine and completion of MCP configuration.

Follow WeChat and reply "open source" to joinAI open-source project exchange group

How to use zg

Install: Via npm install -g @zvec/zvec-grep to globally install the zg tool.
Configure: Run zg install to automatically discover Agents such as Codex and Cursor installed on the machine and complete MCP integration.
Build index: Enter the target repository directory and run zg index to build a local semantic and BM25 index for code and documents.
CLI retrieval: In the terminal, use zg query --human "你的问题" to search local content with natural language.
Agent retrieval: Ask questions directly in natural language in a connected Agent, and the Agent automatically calls zg through MCP to complete retrieval.

zg's core advantages

Unified retrieval paradigm: Integrates semantic discovery, BM25 ranking, and ripgrep exact matching into a complete retrieval pipeline, covering the entire workflow from fuzzy intent to symbol verification.
Agent-Native Design: Through deep integration with mainstream Agents via the MCP protocol, it has been measured to reduce tool calls and Token consumption by more than 40%.
Local-First Privacy: File scanning, embedding, indexing, and retrieval are all completed on-device by default, with no content needing to be uploaded.
Lightweight On-Device Models: Built in with 11 on-device embedding models, running by default with just 16M parameters, no GPU or remote API required.
Embedded Zero-Dependency Storage: Implements vector and BM25 indexes based on the Zvec in-process database, with no need to deploy and maintain a separate database service.
Incremental Index Reuse: After the initial build, only changed content is processed, and the same index can be shared and reused over the long term by the CLI and multiple Agent tasks.
Structured Content Extraction: Automatically parses code symbol hierarchies, document section structures, and metadata, making retrieval results locatable and verifiable.
One-Click Agent Integration：zg install Automatically discovers Codex, Cursor, Claude Code, and others on the local machine and completes MCP configuration.

zg's project address

GitHub Repository：https://github.com/zvec-ai/zvec-grep

zg's comparison with similar competitors

Comparison Dimension	zg（zvec-grep）	ripgrep（rg）
Core Positioning	Local-first unified retrieval infrastructure (semantic + BM25 + exact matching)	High-performance recursive regex text search tool
Retrieval Capabilities	Four-in-one: semantic retrieval, BM25, hybrid retrieval, and ripgrep exact matching	Supports regex-based exact text matching
Natural Language Queries	✅ Supported, can discover related content by intent (e.g., "restore theme preference" →`hydratePreferences`）	❌ Not supported, accurate keywords or regex patterns must be provided
Result Ranking	After multi-path recall, results are fused and deduplicated via RRF and uniformly ranked by relevance	Output in file traversal order, with no relevance ranking
Content Structuring	Automatically extracts code symbol hierarchies and document section structures, preserving metadata	Plain text line-level matching, does not recognize code/document structure
Agent Integration	Native MCP support, automatically configures Codex / Cursor / Claude Code	No native MCP; Agents need to invoke via shell and parse the output themselves
Indexing Mechanism	Pre-builds a local semantic + BM25 index, supports incremental updates and long-term reuse	No index; traverses the file system in real time on every search
Local-first	On-device Embedding + embedded index, zero external dependencies by default	Fully local, but without semantic capabilities
Applicable scenarios	Complete chain from fuzzy intent exploration → relevance focus → precise verification	Fast exhaustive matching of known symbols, function names, and error messages
Privacy protection	All-local processing by default; remote Embedding requires explicit authorization	Fully local, no external transmission involved

Application scenarios of zg

Codebase intent exploration: Developers or Agents describe business phenomena in natural language, and zg semantic retrieval locates in the code hydratePreferences or the related implementation of "account authorization and approval" in the documentation.
Fault localization and root cause analysis: Facing error logs or vague descriptions in user feedback, the Agent quickly discovers relevant code paths, configuration files, and documentation explanations through zg semantic retrieval, reducing multiple rounds of searching and reading of irrelevant files.
Cross-file code understanding: When understanding the full-chain implementation of a feature in a large codebase, asking questions in natural language can retrieve relevant functions, interface definitions, and call relationships across modules and languages, avoiding manual traversal in the directory tree.
Local knowledge base question answering: After indexing Markdown/text files such as technical documents, research materials, and notes, accurate answers can be quickly obtained through natural language queries, with source files and specific section locations attached.