Skip to main content

zvec-grep (zg): Code and Document Radar

zvec-grep (often abbreviated as zg) is a search tool designed for human developers and AI assistants. Unlike older search tools that only look for exact matching letters, zg understands what you mean, pointing directly to the exact paragraphs or lines where that topic lives.

The Library Metaphor: Why Did We Need This?​

Think about searching for an old conversation on your phone:

  • You know you discussed "where to eat hot pot this weekend", but you cannot remember the exact words you typed.
  • A traditional search tool (like standard grep) is like scanning every single word with a magnifying glass. If you search for "hot pot", but back then you typed "Sichuan spicy soup", traditional search returns zero results.
  • What did early AI coding assistants do to solve this? They took the brute-force route: they hauled twenty 500-page binders to their desk and tried to read every single line from start to finish.
    • The Result: Information Indigestion. The AI's short-term memory became overwhelmed. It forgot the owner's original instructions, got confused, and began writing hundreds of lines of broken, overly complicated code that nobody asked for.

The Solution: An Intelligent Index Card​

zvec-grep acts like a librarian who already read the table of contents of every notebook in your office:

  1. You ask in plain, everyday human language: "Where do we calculate trade execution fees?"
  2. zg does not dump the whole library on the AI's desk. Instead, it hands over an index card:
    matching.py: lines 148 to 253 (match_fifo_lots)
  3. The AI reads only those specific 100 lines, completes the requested fix cleanly, and stops.

The Real-World Benefits​

Without zg (Brute Force)With zg (Precision Radar)
Memory Overload: Reads 3 large files (~5,000 words of context), quickly exhausting the AI's short-term attention.Surgical Focus: Returns only the file name and line coordinates (~80 words of context).
Straying Off-Course: As memory fills up, the AI forgets user constraints and begins inventing unwanted features.Staying on Track: The AI's working memory stays clean, keeping it focused strictly on the assigned task.
Duplicate Files: Unable to locate existing notes, the AI creates redundant duplicate documents.Single Source of Truth: The AI finds existing pages instantly and updates them in place.
Expensive and Slow: Repeatedly sending massive blocks of code across the network burns time and API fees.100% Local & Fast: Runs entirely on your computer's processor in seconds, without sending your code to any cloud.

Practical Recipes: The 3 Commands You Will Actually Use​

All commands are run from your project directory in the terminal:

1. Build the Search Index (First Time Setup)​

Teaches the tool the structural outline of your files:

# For coding projects (Python, JavaScript, etc.)
npx @zvec/zvec-grep index --embedding local/potion-code-16m-v2

# For multilingual documentation (like this website)
npx @zvec/zvec-grep index --embedding local/potion-multilingual-128m

2. Search Code by Business Meaning​

You do not need to guess variable names. Search the business idea directly:

npx @zvec/zvec-grep query "order execution slippage commission fee" -g '*.py' --limit 3 --human

3. Check for Duplicate Topics Before Writing​

Before asking an AI to draft a new guide, check if the website already has a page for it:

npx @zvec/zvec-grep query "personal knowledge system" -g 'docs/**' --limit 3

If an existing file matches, update that page instead of creating a second redundant document.

Related Notes & Connected Systems​

  • The Bigger Picture: Agent Memory and Hierarchical Retrieval — How zg fits into the broader 4-tier system that keeps AI agents grounded.
  • The Decision Keeper: Basic Memory — While zg finds where code lives, Basic Memory holds the high-level human rules telling the AI what it is allowed to do.
  • The Concept Garden: QMD — The Markdown knowledge vault search for domain theories and past lessons.

Official Resources & References​