Introduction

Semantic code search + knowledge graph as an MCP plugin for Claude Code

What is VecGrep?

VecGrep is a semantic code search and knowledge graph tool that works as an MCP (Model Context Protocol) plugin for Claude Code.

Instead of grepping 50 files and sending 30,000 tokens to Claude, VecGrep returns only what’s relevant:

Mode	Avg tokens	vs raw files	Latency
Raw file read	26,009	—	—
search_code	~3,007	−88%	~83ms
hybrid_search	~3,324	−87%	~76ms
search_graph	~47	−99.8%	~3ms

How it works

1. Chunk

   Parses source files with tree-sitter to extract semantic units — functions, classes, and methods.

2. Embed

   Encodes each chunk locally using all-MiniLM-L6-v2-code-search-512 (384-dim, ~80MB one-time download) via the fastembed ONNX backend (~100ms startup) or PyTorch.

3. Store

   Saves embeddings and metadata in LanceDB, and optionally a knowledge graph (graph.json), under ~/.vecgrep/<project_hash>/.

4. Search

   Uses an ANN index (IVF-PQ) for fast approximate search, keyword search over graph nodes, or a blended hybrid of both.

Incremental re-indexing via mtime/size checks skips unchanged files.

Which tool to use

Query type	Tool
Semantic / behaviour (“how does authentication work”)	search_code
Structural / navigation (“where is class X defined”, “what calls Y”)	search_graph
Both semantic and structural context needed	hybrid_search
Explore call graph or inheritance	graph_neighbors

Key features

Up to 99.8% token reduction

Returns only relevant chunks or graph nodes instead of entire files.

Fast startup

ONNX backend starts in ~100ms. No PyTorch required by default.

Knowledge graph

AST-based graph index captures calls, imports, inheritance — no LLM required.

Works automatically

Claude decides when to call VecGrep — no manual invocation needed.