vectr

<!-- mcp-name: io.github.swapnanil/vectr -->

<p align="center">
  <img src="https://raw.githubusercontent.com/swapnanil/vectr/main/assets/banner.svg" alt="vectr: semantic codebase search and persistent working memory for AI code editors" width="560">
</p>

# 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.

[![CI](https://github.com/swapnanil/vectr/actions/workflows/ci.yml/badge.svg)](https://github.com/swapnanil/vectr/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/)
[![Version 1.12.0](https://img.shields.io/badge/version-1.12.0-blue.svg)](CHANGELOG.md)
[![MCP: 23 tools](https://img.shields.io/badge/MCP-23%20tools-blue.svg)](#23-mcp-tools)

Version 1.12.0 · Last updated 2026-09-03 · [CHANGELOG](CHANGELOG.md)

## 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.

```bash
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.

| | A typical memory layer | Vectr |
|---|---|---|
| **How memory reaches the model** | The agent or developer calls an explicit store-and-retrieve API, `add()` and `search()` or the equivalent. Memory arrives only when something decides to ask for it. | Every note carries trigger conditions over `{path, symbol, semantic, event, temporal}`. On editors with session hooks the harness evaluates them deterministically and injects the match. The agent never has to remember to ask. |
| **Domain** | Generic conversational memory, aimed broadly at assistants and applications rather than at source code. Notes are strings about a user or a session. | Code native. A symbol graph, AST chunking, semantic code search, and working memory fused in one daemon, so a note can be anchored to a real symbol or path rather than a string. |
| **Inference** | Commonly runs note extraction through an LLM and embeds through a provider API, so an API key and a provider account are part of the setup. | Zero internal LLM calls, by design. A local embedding model, no provider account, no API key. |
| **Deployment** | Usually a library or a self-hosted server, frequently with a managed cloud tier alongside it. | One local daemon bound to `127.0.0.1`, one per workspace. Team mode is available and opt in. |

**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](https://arxiv.org/abs/2607.20972) (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](#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](#when-vectr-can-hurt).

---

## Benchmarks

Public results live in [`benchmarks/`](https://github.com/swapnanil/vectr/tree/main/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:**

| Metric | Vanilla | Vectr | Delta |
|---|---|---|---|
| Cost | $2.50 | $1.97 | **-21%** |
| Wall time | 17.6 min | 13.5 min | **-24%** |
| Turns | 123 | 94 | **-24%** |
| Read + Bash calls | 102 | 62 | **-39%** |

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

| Task | Vanilla | Vectr | Delta |
|---|---|---|---|
| `debug_gc_finalizer` | 16 | 6 | -62% |
| `feature_dict_pop_last` | 13 | 3 | -77% |
| `cross_session_set_cartesian` | 23 | 9 | -61% |
| `debug_descriptor_priority` | 6 | 6 | 0% |
| `cross_session_bytes_find_all` | 13 | 2 | -85% |
| `cross_session_list_rotate` | 21 | 16 | -24% |

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.

| Phase | Vanilla | Vectr | Why |
|---|---|---|---|
| Research (1 session, paid once) | $1.36 | $2.63 | Storing notes costs output tokens |
| Impl (6 sessions, repeating) | $2.50 | $1.97 | Notes replace re-discovery |
| Total sprint | $3.86 | $4.60 | Inverts to a net gain after about 8 tasks |

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):

| Tool | Median tokens | Range |
|---|---:|---|
| `vectr_search` | ~2,320 | 1,437 to 3,091 (n=8) |
| `vectr_locate` | ~192 | |
| `vectr_trace` | ~720 | |
| `vectr_recall` (index tier) | ~180 | |

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)**

```bash
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](https://www.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)**

```bash
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