Tag: zg

  • Local Search in 30 Seconds, 3,457 Files Indexed — How Qwen’s zg Transforms Agent Workflows

    Local Search in 30 Seconds, 3,457 Files Indexed — How Qwen’s zg Transforms Agent Workflows

    Key Takeaways

    • zg (zvec-grep) is a local-first search tool open-sourced by the Qwen team. It combines ripgrep’s precise text matching with vector search, BM25, and hybrid retrieval, letting natural-language intent navigate code and documents while narrowing down to the exact location.
    • The default embedding model is local/potion-code-16m-v2 — 16M parameters, about 32 MiB of local cache, no GPU required. Eleven on-device embedding models are bundled so users can pick the right one for each use case.
    • It indexed the entire Django repository of 3,457 files in under 30 seconds on an Apple M4 Pro. Zvec stores vector and BM25 indexes as an embedded library on the device, eliminating the need for a separate database service.

    Analysis

    Table of Contents

    The standard for local search is shifting. The figure of indexing 3,457 files of the Django repository in 30 seconds on an Apple M4 Pro highlights the limits of workflows that have long relied on ripgrep. zg (zvec-grep), open-sourced by the Qwen team, is a tool that adds semantic exploration to a local-search experience previously confined to keyword matching.

    A New Standard for Local Search: The Context Behind zg

    ripgrep is fast, but it struggles with natural-language questions like “Where is the OAuth callback handled?” zg addresses exactly that gap in local search. It adopts local/potion-code-16m-v2 as the default embedding model — 16M parameters, about 32 MiB of local cache, running on CPU alone with no GPU required. Eleven on-device embedding models are bundled, letting users choose based on the task at hand.

    The vector and BM25 index, called Zvec, is stored on the device as an embedded library. No separate database service is required. This distinction changes how the tool operates in on-premise environments and agent workflows.

    The Architecture of Hybrid Local Search

    The core idea is fusion, not a single algorithm. BM25 and vector search generate candidates, ripgrep adds exact matching, and RRF (Reciprocal Rank Fusion) produces the final ranking. The default output is a constrained preview plus a compressed ranked list, giving the next reasoning step enough context without re-reading entire result files.

    Comparing Three Local Search Approaches

    Item ripgrep alone zg hybrid Remote vector DB
    Indexed target Text only Vector + BM25 + text Vector + metadata
    Natural-language queries Not supported Supported Supported
    Local self-sufficiency Full Full Not possible (API-dependent)
    Agent integration Direct call MCP supported out of the box Requires a separate adapter
    Primary cost Disk I/O CPU embedding API call fees

    How to Plug zg into Your Agent Workflow

    The integration path for agents is MCP (Model Context Protocol). Since multiple agents share the same local index, redundant per-agent indexing never happens. The tool description also specifies search termination conditions, reducing repeated calls for the same query. What stands out for practitioners is the shift in cost structure. Given the growing number of teams adopting agent-based development, the local-search layer is becoming the next variable in cost competitiveness.

    What Two Benchmarks Reveal About Local Search

    SWE-QA-Bench tests multi-step reasoning on 20 questions across real code repositories. With zg introduced, tool calls dropped by more than half and input tokens fell by nearly half. The Judge score rose by 1.50 points.

    BrowseComp-Plus is a deep-research evaluation of 80 questions. Accuracy climbed from 98.67% to 99.00%, while input tokens dropped 37.56%, tool calls 43.52%, and agent runtime 38.58%. It is worth remembering, however, that the one-time initial index creation and remote embedding API costs were excluded from these figures.

    Practical Application Points

    • Start indexing from the repository root with `zg index .`, and add the default `.zvec/` directory to `.gitignore`.
    • Use `.zgignore` to explicitly exclude large directories such as `node_modules`, `dist`, and `venv` to reduce indexing time.
    • Launch in MCP server mode (`zg serve –mcp`) and include a stop rule in the agent system prompt, such as “after three searches, synthesize the answer candidates.”
    • Swap among the 11 embedding models based on the code/documentation/natural-language ratio. For code-heavy work, use `potion-code-16m-v2`; for Korean-language documents, prioritize a multilingual model.

    Try It Right Now

    • Clone a demo repository (e.g., requests, fastapi) and measure the runtime of `zg index .`.
    • Compare ripgrep-only results with zg hybrid results on the same query and track token usage.
    • Register the zg server in the MCP configuration file of your agent (Claude Code, Cursor, etc.).
    • Write a `.zgignore` to block noisy directories and shrink the index size.
    • Pick 5 of the 11 embedding models and record accuracy by query type (symbol search, semantic search, typo correction).

    Unverified Aspects and Remaining Challenges

    The author views the tool’s significance as lying less in raw search speed and more in the cost structure of a single agent cycle. Cutting tokens and call counts by nearly half means longer reasoning runs on the same budget. That said, the remaining validation challenges are clear: index update policy, monorepo memory footprint, and model swap cost. The original is available at Hacker News Korea’s zg (zvec-grep) — local search infrastructure beyond keywords.

    Frequently Asked Questions

    Does zg replace ripgrep?

    It does not replace it — it sits on top of it. The architecture preserves ripgrep’s exact matching for result precision while placing BM25 and vector search in front to extend candidate generation with semantic understanding.

    Can local search work without a GPU?

    Yes. The default model, local/potion-code-16m-v2, runs on CPU alone. At 16M parameters and roughly 32 MiB of local cache, indexing and search are feasible on a standard laptop.

    How much does it reduce cost when used as an agent tool?

    In the BrowseComp-Plus evaluation of 80 questions, input tokens dropped 37.56%, tool calls dropped 43.52%, and agent runtime dropped 38.58%. This is because results are returned as previews and compressed ranked lists.

    Is index refresh automatic or manual?

    Based on the published workflow, manual indexing (`zg index`) is the default. Automatic refresh based on file-change detection remains an open validation task in monorepo environments.

    Reference Source

    This article was written after verifying the following source: geeknews — zg (zvec-grep): local search infrastructure beyond keywords