Does Vectr require an API key to run?

No. The default embedding model (Snowflake/snowflake-arctic-embed-m-v1.5) runs locally via sentence-transformers. It downloads once (~440MB) and requires no API key. The codebase passport is synthesised by your AI code editor on the first vectr_map call — using your editor's existing API access, not a separate key Vectr requires. All features — search, symbol graph, working memory — run entirely offline.

How does Vectr remember working context across sessions?

Vectr provides vectr_remember and vectr_recall MCP tools. The AI calls vectr_remember to save a working note — key files, edge cases, what's still missing — to a persistent SQLite store. Notes survive /compact and new sessions intact. vectr_recall retrieves them in <50ms, verbatim, any time. Notes have time-based decay and priority levels. A vectr_snapshot captures the full session state for exact restoration.

What does vectr_evict_hint do?

vectr_evict_hint lists the retrieved code chunks that vectr can re-retrieve in <50ms — the AI doesn't need to re-read those files. Vectr tracks everything retrieved in a session, estimates token cost, and lists exactly which chunks are fully indexed with a <50ms re-retrieval guarantee. This is the reverse signal in the vectr protocol: the AI saves findings (vectr_remember), vectr signals what it can recall instantly (vectr_evict_hint).

Why is AST-aware chunking better than splitting by token count?

Token-based splitting cuts code at arbitrary boundaries — often mid-function or mid-argument-list. This produces chunks that are syntactically incomplete and embed poorly. AST-aware chunking splits at semantic boundaries (function, class, method) so each chunk is a complete, meaningful unit. Vectr uses tree-sitter for Python, JavaScript, TypeScript, Go, Rust, and Java.

What is vectr_locate and how is it different from vectr_search?

vectr_locate finds where a symbol is defined — file path, line number, and kind (function/class/method) — without returning any code content. It costs almost no tokens. vectr_search returns the actual code chunk. The intended workflow is: locate first to know where to look, then search only when you need the code itself.

Code Intelligence

VECTR

Q: What does vectr_evict_hint do?

vectr_evict_hint lists the retrieved code chunks that vectr can re-retrieve in <50ms — the AI doesn't need to re-read those files. Vectr tracks everything retrieved in a session, estimates token cost, and lists exactly which chunks are fully indexed with a <50ms re-retrieval guarantee. This is the reverse signal in the vectr protocol: the AI saves findings (vectr_remember), vectr signals what it can recall instantly (vectr_evict_hint).

Q: Why is AST-aware chunking better than splitting by token count?

Token-based splitting cuts code at arbitrary boundaries — often mid-function or mid-argument-list. This produces chunks that are syntactically incomplete and embed poorly. AST-aware chunking splits at semantic boundaries (function, class, method) so each chunk is a complete, meaningful unit. Vectr uses tree-sitter for Python, JavaScript, TypeScript, Go, Rust, and Java.

Q: What is vectr_locate and how is it different from vectr_search?

vectr_locate finds where a symbol is defined — file path, line number, and kind (function/class/method) — without returning any code content. It costs almost no tokens. vectr_search returns the actual code chunk. The intended workflow is: locate first to know where to look, then search only when you need the code itself.

Your AI code editor forgets everything. Vectr doesn't. Semantic search + persistent memory over your codebase — via MCP, zero config, the moment you open a workspace.

View on GitHub All Tools

# No config. No API key. Just run.
pip install git+https://github.com/swapnanil/vectr
cd /path/to/your/project
vectr start
# Indexes workspace + builds symbol graph in background.
# Writes MCP config. 12 tools available.
✓ Indexed 847 files → 14,523 chunks (9m 12s)
✓ Symbol graph: 6,841 symbols, 22,104 edges
✓ MCP ready at http://localhost:8765/mcp
→ Open your AI editor and ask about the codebase
  to build the structural map on first vectr_map call

Problem

On a codebase with 40,000 files, the AI runs rg -l "authenticate", gets 200 results, reads 8 complete files — 12,000 tokens gone for one query. And the next session, it starts over from zero: no memory of what it found, no record of what's still missing.

Retrieve, Locate, Remember

Vectr replaces the grep-then-read loop with three knowledge layers. A structural map gives the AI a 300-token overview of the entire codebase at session start. A symbol graph answers "where is X defined?" without reading any code. A content index returns the exact function body only when needed.

And as discoveries happen, the AI saves working notes to Vectr. Next morning, one vectr_recall() brings it back to exactly where it stopped — key files, edge cases, what's still missing. The conversation is gone, but the knowledge survived the gap.

Architecture

Three Layers of Knowledge

Humans don't memorise codebases — they recall intelligently. Vectr applies the same principle to LLMs.

Layer 1

Codebase Map

The first time your AI editor calls vectr_map with no cached passport, Vectr returns raw metadata and the CLAUDE.md that vectr init wrote prompts the editor to write a 300-token structural summary and save it with vectr_map_save. After that, every session opens with the full picture — module purposes, tech stack, entry points, domain vocabulary — without reading a single file.

vectr_map

Layer 2

Symbol Graph

tree-sitter extracts every function, class, and method into a persistent call graph. Ask "where is EvaluateSegments defined?" and get targeting/segment/evaluator.go:45 — no code content, no tokens wasted.

vectr_locate vectr_trace

Layer 3

Content Search

AST-aware chunks embedded with Snowflake/snowflake-arctic-embed-m-v1.5 (local, no API key). Adaptive hybrid search: vector + BM25 weights tuned per codebase fingerprint. Returns exact function bodies with file paths and line numbers.

vectr_search

How It's Built

Map

On the first vectr_map call with no saved passport, Vectr returns raw directory metadata and prompts the AI editor to write a structural summary. The editor calls vectr_map_save to store it. Vectr makes no LLM calls at any point — the AI editor uses its own API access for this one step.

Parse

tree-sitter reads every file and extracts functions, classes, and methods — both as embeddable chunks and as a call graph with caller/callee relationships. Unsupported languages fall back to 200-line windows.

Embed

Each chunk is embedded with Snowflake/snowflake-arctic-embed-m-v1.5. Runs locally — no API key needed, downloaded once (~440MB) and cached. A file watcher re-embeds only changed files on save. Override with VECTR_EMBED_MODEL=<hf-model-id> for any sentence-transformers compatible model.

Serve

12 MCP tools at localhost:8765/mcp. Map, locate, search, remember, recall, evict, snapshot, forget. Any MCP-compatible AI code editor connects with two lines of JSON config.

Features

What Makes It Different

Session memory that persists

vectr_remember saves a working note — key files, edge cases found, what's still missing — to a SQLite store. Notes survive /compact and new sessions. vectr_recall retrieves them in <50ms, verbatim, any time. If referenced files changed since the note was written, recall automatically flags them with a [STALE] warning so the AI knows to re-verify before acting.

Bidirectional recall protocol

The AI saves findings; Vectr signals what it can recall instantly. vectr_evict_hint lists every retrieved chunk with its estimated token cost and a <50ms re-retrieval guarantee — the AI never needs to re-read those files.

Symbol graph, not just search

vectr_locate finds where a function is defined — file, line, kind — without returning any code content. vectr_trace follows the call graph: who calls this, what does this call. Navigate before you read.

300-token codebase passport

vectr_map returns a plain-English structural overview: module purposes, tech stack, entry points, domain vocabulary. One call at session start means the AI already knows where everything lives before asking a single question.

AST-aware chunking + hybrid search

tree-sitter splits code at function and class boundaries — never mid-logic. Adaptive hybrid search (vector + BM25, weights auto-tuned per codebase) finds verify_jwt_token when you ask about JWT validation, and surfaces exact symbol names for precise lookups.

Zero-config, zero cloud

Run vectr start. Vectr detects your git root, indexes the workspace, and writes config files for Claude Code, Cursor, VSCode/Copilot, and Windsurf automatically. The embedding model runs locally — no API key required anywhere. See the README for the full list.

Quickstart

Up in Under 15 Minutes

First run downloads the embedding model (~440MB). Restart your AI editor once after vectr start — the installed CLAUDE.md will guide it through the first-session passport setup automatically.

Option A — pip (recommended)

Individual developers. Runs the embedding model locally. No API key required.

Option B — Docker

Servers and CI pipelines. No Python environment needed — docker-compose up api and you're indexing.

# Option A — pip install
pip install git+https://github.com/swapnanil/vectr
cd /path/to/your/project
vectr start

# Option B — Docker
git clone https://github.com/swapnanil/vectr
docker-compose up api

# Either way: stop and restart on a different workspace
vectr restart --path /path/to/other/project

# Write CLAUDE.md + .mcp.json without starting the server
vectr init

# Clear working memory after a large refactor
vectr forget --path .

# Search from the terminal
vectr search "JWT token validation"

Example

A Session With Memory

What an AI assistant's session looks like with Vectr — from cold start to end-of-day handoff.

Morning — session start (3 calls, ~5 seconds)

# 1. Structural overview — free, ~247 tokens
vectr_map()
→ "Go DSP ad server. targeting/ (audience matching),
   bidder/ (bid logic), tracker/ events.
   Entry: bidder/pipeline.go:RunBidPipeline"

# 2. Recall yesterday's notes
vectr_recall()
→ "[HIGH] Entry: EvaluateSegments() in
   targeting/segment/evaluator.go. Missing tests
   for nil visitor_id case."

# 3. Find the symbol — no code read yet
vectr_locate("EvaluateSegments")
→ [function] EvaluateSegments
   targeting/segment/evaluator.go:45

End of day — context handoff

# After implementing, before closing
vectr_remember(
  "Segment targeting done. EvaluateSegments in
   evaluator.go:45. Added nil guard at line 61.
   Still need: integration test for multi-segment
   visitor with expired segments.",
  tags=["segment-targeting", "wip"],
  priority="high"
)
→ "Stored note #4. You can safely drop
   related code chunks from context."

# Vectr tells the AI what to drop
vectr_evict_hint()
→ "Vectr has 6 chunks (~3,840 tokens) indexed.
   You can safely drop:
   targeting/segment/evaluator.go [lines 40-110]
   bidder/auction.go [lines 88-134]
   Recall latency: <50ms. Nothing will be lost."

Benchmarks

Measured on Real Codebases

Two-phase benchmark: Phase 1 explores and stores notes; Phase 2 opens cold, calls vectr_recall(), and implements. Vanilla Phase 2 re-reads from scratch.

Django

Familiar codebase

Mixed results. Complex ORM internals: −24% tokens, −60% cost. Well-known APIs where the model already has training coverage: no benefit. Vectr helps in proportion to how much re-discovery work Phase 2 would otherwise do.

Camel

5,856-file enterprise Java

−40% Phase 2 input tokens, −58% Phase 2 cost across 3 tasks. On custom_component, vanilla produced 0 bytes after 51 tool calls. Vectr produced a complete 5-file implementation. On route_policy: both working, but vectr was 3× cheaper and 2.4× faster.

Why

The mechanism

vectr_recall() at Phase 2 start returns structured notes in ~200 tokens, replacing hundreds of re-discovery tool calls. The AI picks up mid-thought: no files re-read, no symbols re-grepped. On Apache Camel, this dropped Phase 2 tool calls from 135 to 38.

When

When it matters most

Large unfamiliar codebases, cross-session continuation tasks, and implementation work following a research phase. Single-session tasks on well-known codebases see minimal benefit — the model's training data already covers those.

Task	Vanilla P2	Vectr P2	Cost Δ	Tools Δ	Output
custom_component	$0.56 · 134s · 51 tools	$0.36 · 195s · 11 tools	−35%	−78%	0 bytes (failure) vs 9,398 bytes (5 files)
route_policy	$1.15 · 430s · 59 tools	$0.35 · 177s · 16 tools	−70%	−73%	both 280-line impl
type_converter	$0.48 · 187s · 25 tools	$0.20 · 86s · 11 tools	−57%	−56%	both working
Totals (Camel)	$2.19 · 751s · 135 tools	$0.92 · 458s · 38 tools	−58%	−72%	−40% input tokens