Vectr

Vectr

Delivery, not storage. A local daemon that gives an AI code editor semantic search over your codebase, plus working memory that shows up on its own when it is relevant.

Version 1.12.0 · Last updated 2026-09-03 · CHANGELOG

In 30 seconds

Your AI code editor pays for the same knowledge twice. It re-reads files it read yesterday, re-greps symbols it already found, and loses the exact signature it discovered at turn 5 the moment the conversation is compacted. Vectr is one local process that removes both halves of that bill:

• Retrieval that understands code. AST-aware chunks, a symbol and call graph, and hybrid semantic plus BM25 ranking. Describe a behaviour and get the whole function back, in one call instead of a grep loop and three blind file reads.
• Working memory that gets delivered. Save a finding once. It comes back verbatim in under 50ms, and on editors that expose session hooks it arrives automatically at the moment it applies, without the agent choosing to ask for it.
• Local, keyless, zero config. One pip install, one vectr start. The embedding model runs on your machine. Nothing is transmitted anywhere, and there is no API key.

pip install vectr && cd /path/to/your/project && vectr start

That is the whole setup. Vectr writes the MCP config for your editor, then indexes in the background.

---

How vectr differs from other AI agent memory tools

There is a healthy category of general-purpose memory layers for AI agents, and the good ones solve a real problem well. Vectr is most often compared to them, so here is the difference stated plainly. The left column describes the design these tools tend to share, not any one product; individual tools vary, so check the one you are considering.

Why the first row is the one that matters. Storage is not the bottleneck. Retrieval that an agent must volunteer to call is, because it largely does not call it. In our controlled evaluation the agent performed 0 memory operations across 114 turns even when the store was pre-seeded with knowledge directly relevant to its task. Deterministic injection delivered in every injection-equipped run, with zero false-alarm fires across the audit-logged trigger evaluations. Under repeated compaction, ten facts held only in the conversation were absent from 106 of 108 forced compactions, while the same ten facts injected from a harness-owned store arrived intact across 138 of 138 compact-resumes.

Full method and results: Delivery, Not Storage: Cue-Anchored Working Memory as a Harness Property for Coding Agents (arXiv:2607.20972).

---

What it costs and what it saves

Measured, not hypothetical. Recalling 3 stored notes with vectr_recall costs 360 tokens in one tool call. Re-deriving the same three facts with grep plus Read costs about 2,060 tokens across six tool calls on the same 182-file Python repo. That is roughly 5.7x fewer tokens and 6x fewer tool calls, in under 50ms (chars/4 tokenization, full breakdown in Measured costs, honestly).

Notes are persisted to disk, not held in the conversation, so they survive /compact and a fresh session equally. The session boundary does not matter: saving at turn 5 and recalling at turn 15 is the same mechanism as recalling three days later.

Where it pays off: unfamiliar or large codebases, work you resume, and long sessions with many turns. Where it does not: a one-off grep on code you already know cold. Reach for grep instead, and see When vectr can hurt.

---

Benchmarks

Public results live in benchmarks/. The corpora below are witnesses chosen because they are large and unfamiliar to the model, nothing more.

A six-task sprint on a large unfamiliar C codebase simulates a week of feature work. One research session stores findings with vectr_remember. Six isolated implementation sessions each open cold and call vectr_recall.

Implementation sessions only, 6 tasks combined:

Per-task re-discovery (Read and Bash calls before the first write):

The 0% row is real and kept on purpose: that task was one the model could already navigate from training knowledge alone.

Research versus implementation, stated honestly. The research phase is paid once and costs *more* with vectr (+94%), because storing rich code stubs and signatures produces output tokens. The implementation phases repeat every task and cost less, because recall replaces re-discovery. The overhead breaks even after roughly 8 tasks of note reuse.

An earlier run on a 5,856-file Java corpus measured -58% implementation cost, -72% implementation tool calls, and -39% wall time.

---

Measured costs, honestly

Per-call token cost (median, 182-file Python repo, chars/4 tokenization):

The trade-off, stated plainly: for a single pointed lookup on a small, already-familiar repo, grep is cheaper. Vectr's median cost across 5 single-fact tasks was 60% more tokens, and it is slower too, since a vectr_search round trip takes 1.7 to 3.6 seconds against about 28ms for grep. Vectr does not win on per-call cost. It wins on tool-call count (one round trip instead of several), on answer completeness (a whole symbol back, not a partial file read), and on everything in working memory, where the 5.7x recall refund compounds with every task you resume.

Fine print: the automatic eviction and reminder banners riding along on tool responses cost tokens too. An always-on re-fetch footer runs about 27 tokens, a light nudge about 89 tokens, and the escalated action-required banner (which fires only after both the chunk and token thresholds are crossed without a save) scales from about 480 to 535 tokens before it plateaus.

---

Quick start

Local (recommended)

python3.14 -m venv ~/.vectr-env

source ~/.vectr-env/bin/activate # Windows: ~/.vectr-env/Scripts/activate pip install vectr cd /path/to/your/project vectr start

Requires Python 3.14+. To install:

• macOS: brew install python@3.14
• Ubuntu/Debian: sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.14 python3.14-venv
• Windows: python.org/downloads

vectr start returns immediately. Indexing runs in the background, so run vectr status to check progress. On first run the embedding model downloads once (about 290 MB). Restart your AI code editor once to pick up the new MCP config.

Docker (CI and servers)

git clone https://github.com/swapnanil/vectr

cd vectr docker-compose up api

Exposes port 8765. Docker does not auto-write IDE config files, so use the local install for IDE integration.

---

Connect to your AI code editor

vectr start writes the MCP config for your editor automatically. Restart your editor once.

"Verified" means the full integration (config, guidance, and hooks) has been exercised end to end. "Experimental" means the MCP config is written and works, but the integration has not been run through the same verification pass.

Automatic delivery of memory depends on the host exposing session hooks. Where it does not, every tool below still works on demand over MCP.

Manual setup

Claude Code, .claude/settings.json:

{ "mcpServers": { "vectr": { "type": "http", "url": "http://localhost:8765/mcp" } } }

Cursor, .cursor/mcp.json:

{ "mcpServers": { "vectr": { "url": "http://localhost:8765/mcp" } } }

VS Code / GitHub Copilot (1.99+), .vscode/mcp.json:

{ "servers": { "vectr": { "type": "http", "url": "http://localhost:8765/mcp" } } }

Windsurf, ~/.codeium/windsurf/mcp_settings.json:

{ "mcpServers": { "vectr": { "serverUrl": "http://localhost:8765/mcp" } } }

Continue.dev, .continue/config.json:

{ "mcpServers": [{ "name": "vectr", "transport": { "type": "http", "url": "http://localhost:8765/mcp" } }] }

Codex CLI, project-scoped .codex/config.toml (written automatically by vectr start):

[mcp_servers.vectr]

url = "http://localhost:8765/mcp"

On its first run in the workspace, Codex shows a