zg Operational

zg (zvec-grep) is an open-source, local-first unified retrieval foundation tool from Zvec AI for developers and AI Agents. It combines ripgrep exact matching, BM25 lexical search, and vector semantic search to bridge the vocabulary gap between natural-language intent and the actual wording of code and documents, providing a complete retrieval workflow from fuzzy exploration to precise locating. zg performs file scanning, embedding, indexing, and retrieval locally by default, with lightweight edge models built in. It requires neither a GPU nor external services, balancing privacy and efficiency.

Follow WeChat and reply “开源” to join the AI open-source project community
Semantic search: Discover relevant code and documentation based on natural-language intent without having to guess the exact keywords in advance.
BM25 search: Rank text fragments by relevance using term-frequency weighting to quickly focus on the best matches.
Hybrid search: Combine semantic vectors and BM25 multi-path retrieval, then deduplicate and unify rankings through RRF fusion.
ripgrep exact matching: Exhaustively verify known symbols, function names, configuration keys, or text patterns.
Multi-format content extraction: Automatically parse code symbol hierarchies, document structures, and data files while preserving location metadata.
Local embedding: Includes 11 lightweight models that run on the device by default, requiring neither a GPU nor data uploads.
Embedded index storage: Uses the Zvec in-process database for vector and BM25 indexes, with no need to deploy a separate service.
Incremental index updates: After the initial build, process only changed content. Indexes can be reused across queries and Agent tasks over time.
CLI + MCP entry points: Provides a command line for people and the MCP protocol for Agents such as Codex and Cursor.
Automatic Agent integration: zg install automatically discovers Agents installed on the local machine and completes MCP configuration.

Install: Install the zg tool globally with npm install -g @zvec/zvec-grep.
Configure: Run zg install to automatically discover locally installed Agents such as Codex and Cursor and complete MCP integration.
Build an index: Enter the target repository directory and run zg index to build local semantic and BM25 indexes for code and documentation.
CLI search: Use zg query --human "your question" in the terminal to search local content in natural language.
Agent search: Ask questions directly in a connected Agent using natural language. The Agent automatically calls zg through MCP to perform the search.

Unified retrieval paradigm: Integrates semantic discovery, BM25 ranking, and ripgrep exact matching into a complete retrieval workflow covering the entire process from fuzzy intent to symbol verification.
Agent-native design: Deeply integrates with mainstream Agents through MCP and has been tested to reduce tool calls and Token consumption by more than 40%.
Local-first privacy: File scanning, embedding, indexing, and retrieval all take place on the device by default, with no need to upload any content.
Lightweight edge models: Includes 11 edge embedding models and runs by default with just 16M parameters, requiring neither a GPU nor a remote API.
Zero-dependency embedded storage: Uses the Zvec in-process database for vector and BM25 indexes, eliminating the need to deploy or maintain a separate database service.
Reusable incremental indexes: After the initial build, only changed content is processed. The same index can be shared and reused over time by the CLI and multiple Agent tasks.
Structured content extraction: Automatically parses code symbol hierarchies, document structures, and metadata, making retrieval results locatable and verifiable.
One-click Agent integration: zg install automatically discovers Codex, Cursor, Claude Code, and other Agents on the local machine and completes MCP configuration.

GitHub repository: https://github.com/zvec-ai/zvec-grep

Intent exploration in codebases: Developers or Agents describe business behavior in natural language, and zg's semantic search locates the relevant implementation of hydratePreferences in code or “account authorization and approval” in documentation.
Fault localization and root-cause analysis: Given vague error logs or user feedback, Agents use zg's semantic search to quickly find relevant code paths, configuration files, and documentation, reducing repeated searches and irrelevant file reads.
Cross-file code understanding: When understanding the end-to-end implementation of a feature in a large codebase, natural-language questions retrieve relevant functions, interface definitions, and call relationships across modules and languages, avoiding manual traversal of the directory tree.
Local knowledge-base Q&A: Index Markdown and text files such as technical documentation, research materials, and notes, then use natural-language queries to quickly obtain accurate answers with source files and specific section locations.