zvec-grep: Local-First Search for Humans and AI Agents — ripgrep, BM25, and Vector in One Index

🎯 The Problem zg Solves 0:02

The video opens on a problem every developer has felt without naming: you're looking for something in a codebase or a folder full of documents, and you can't quite remember the exact word. Grep needs the exact word. And your AI agent? It'll "happily burn through twenty tool calls and half its context window just wandering around your files hoping to stumble onto the answer."

The question the whole tool is built around: "What if search just… understood what you meant?" That's the pitch behind zvec-grep 🔗 — zg for short. The tagline says it best: "know the words, or don't — just zg."

🔍 Three Engines, One Interface 0:31

zg takes three different ways of searching and puts them behind one interface:

The clever part is the combination, because it mirrors how a human actually investigates: start broad by meaning, rank what's relevant, then verify with an exact match. "Semantic search finds the neighborhood, keyword search anchors the exact identifiers, and regex confirms the precise line" — zg runs that whole loop for you. "Normally you'd pick one. zg says, why not all three?"

🏠 Local-First 1:55

The "local-first" in the name is doing a lot of work, and it's the non-negotiable part for a lot of users. Your files, your search indexes, even the embedding models can all stay right on your machine. Nothing gets shipped to a cloud service by default; if you do want a remote embedding model, zg only sends data with your explicit permission.

📚 The Demo: A Two-Book Mystery 2:50

The README's demo is genuinely charming and shows the tool's whole personality in two minutes. You make a folder, download two classic books into it — Alice in Wonderland and the Memoirs of Sherlock Holmes — and you've got a tiny bookshelf. "Notice this isn't code, it's plain prose. zg doesn't care — it searches text, documents, and data all the same way."

You run zg index pointing at a local embedding model (a small one called potion-retrieval), which reads your files, chunks them, and builds the hybrid index in a hidden dot-folder in your project — self-contained and easy to throw away. Then you ask it a riddle: "an unseen creature left a few marks, what did the detective infer?" — deliberately not typing any keyword that appears in the book, just describing the idea. zg returns the relevant Sherlock passages ranked ahead of Alice, "because it understood you were asking about a detective, not a tea party."

🤖 Agents: MCP & "Show Your Work" 4:02

The moment the host says "sold me" is when you hand that exact same index to an AI agent. zg install targets your agent (the README uses OpenCode), the agent gets zg as a reachable tool, and you ask the same detective question in plain English without telling it which tool to use. The agent decides on its own to call zg, reads exactly the right slice of the file, and answers — Holmes deduced the creature had five foot-pads and long nails, a long body with short legs, was carnivorous (it climbed toward a canary's cage), probably from the weasel family — with every claim cited by file name and line numbers.

📊 Benchmarks & Case Studies 5:54

"Big claims deserve receipts, and to their credit, this team brought receipts." They run paired A/B benchmarks where everything is held constant — same tasks, same model, same prompt, same limits — and the only variable is whether the agent has zg. They test a software-question benchmark with Claude and a general text-retrieval benchmark with Codex, and the results line up with the theory: better answer quality while using fewer input tokens, making fewer tool calls, and finishing faster.

The logic is almost tautological once stated: "if you find the right evidence quickly, you're not stuffing the model's context full of junk, and you're not going back to the well over and over. Less searching, less noise, better answers." The real-world case studies are the gnarly kind — Pylint (how it separates annotated vs non-annotated attributes deep in the AST), Matplotlib (tracing font data through a rendering pipeline), and Django (connecting username constraints to ORM transactions across multiple files). "Exactly the questions where you don't know where to look — and that's where zg shines."

⚖️ Honest Limits & Verdict 7:16

The candor about limits is what earns the host's trust. The team flat-out says zg works best when evidence is spread across files and you don't know where the answer lives — for a quick lookup where you already know the exact function name, plain grep is fine. They also note that since the agent decides when to use the tool, results vary run to run, so averages are more honest than any single cherry-picked win.

On the engineering side, it's TypeScript, Apache-2.0, leaning on ripgrep for fast lexical search and tree-sitter to actually understand code structure — symbols, signatures, breadcrumbs — rather than treating source as a wall of text. It's at version 0.2, so young, but "clearly built with care: real tests, real benchmarks, real docs." The docs are well organized (per-agent wiring guides, CLI reference, retrieval-pipeline page, architecture doc, an embedding-model rundown for trading off speed/quality/privacy/hardware), and there's a public roadmap.

Verdict: if you're drowning in a big codebase or have an agent that keeps flailing around your files, zg is "very much worth an afternoon." Install it, index the two-book mystery, ask it a riddle — it takes five minutes and "it'll click instantly."

💡 Key Takeaways

1. One hybrid index, three engines. ripgrep (exact), BM25 (keyword ranking), and vector search (semantic) behind a single zg interface.
2. It runs the whole investigation loop. Semantic finds the neighborhood, keyword anchors identifiers, regex confirms the line — the way a human actually searches.
3. Local-first is the point. Files, indexes, and embedding models stay on your machine; remote models only with explicit permission.
4. Agents cite their sources. Via MCP, agents (Codex, Claude Code, Qwen Code, Cursor, OpenCode) get ranked, source-linked evidence — file names and line numbers.
5. Receipts included. Paired A/B benchmarks show better answers with fewer tokens, fewer tool calls, and faster completion; case studies on Pylint, Matplotlib, and Django.
6. Honest about limits. Best when evidence is spread across files and you don't know where it lives; for a known function name, plain grep is still fine.

🔗 Resources & Links

• 📦 github.com/zvec-ai/zvec-grep — the repo (Apache-2.0, TypeScript)
• 📚 npmjs.com/package/@zvec/zvec-grep — the npm package
• 📰 From rg to zg: Local Search Beyond Keywords — the zvec.org launch blog

Source video: youtube.com/watch?v=LbeQgUdcyQ4

⏱️ Timestamp Index