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. An API key is only needed for the optional one-time codebase passport build (~$0.005) that generates vectr_map output. All other 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 offload a working note — key files, edge cases, what's still missing — to a persistent SQLite store. Next session, vectr_recall retrieves it instantly. 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 tells the AI which retrieved code chunks it can safely drop from its context window. Vectr tracks everything retrieved in a session, estimates token cost, and — when the threshold is reached — lists exactly which chunks to discard with a guarantee of recall in under 50ms. This is the bidirectional protocol: the AI tells Vectr to remember, Vectr tells the AI what to forget.

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

Your AI coding assistant starts every session with amnesia. Vectr gives it a structural map, a symbol lookup, and working memory that persists across sessions — via MCP, automatically, 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,
# writes MCP config. Ten tools available.

✓ Passport built — 247 tokens, structural map ready
✓ Indexed 847 files → 14,523 chunks (9m 12s)
✓ Symbol graph: 6,841 symbols, 22,104 edges
✓ MCP ready at http://localhost:8765/mcp

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 when the session ends, the AI offloads its working notes to Vectr. Next morning, one call brings it back to exactly where it left off — key files, edge cases found, what's still missing. The context window clears. The knowledge doesn't.

Architecture

Three Layers of Knowledge

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

Layer 1

Codebase Map

One LLM call at startup builds a 300-token plain-English passport: module purposes, tech stack, entry points, domain vocabulary, and architectural patterns. Every session starts with a complete structural picture — no file reading required.

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

At startup, one LLM call walks the directory structure and README to produce the codebase passport. Stored permanently, refreshed only when structure changes significantly. Cost: ~$0.005, once.

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

Ten MCP tools at localhost:8765/mcp. Map, locate, search, remember, recall, evict, snapshot. Any MCP-compatible tool — Cursor, Claude Code, Windsurf — connects with two lines of JSON config.

Features

What Makes It Different

Session memory that persists

vectr_remember offloads a working note — key files, edge cases found, what's still missing — to a SQLite store. vectr_recall retrieves it next session. The AI picks up exactly where it left off without re-reading code.

Bidirectional context protocol

The AI tells Vectr to remember things. Vectr tells the AI what it can safely forget. vectr_evict_hint lists every retrieved chunk with its estimated token cost and a <50ms recall guarantee. The context window stays usable, not full.

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 MCP config for Cursor and Claude Code. The embedding model runs locally. No API key required for search — only for the one-time passport build.

Quickstart

Up in Under 15 Minutes

First run downloads the embedding model (~440MB). Subsequent startups take seconds.

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

# 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 exactly where it left off. No files re-read. No symbols re-grepped.

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