Vectr v1.0.0: The Release Gate, the Bugs It Caught, and the Numbers I Didn't Round Up

If you've read the earlier posts you know the shape of this already, so I'll keep the recap short. Vectr is two things wired into one MCP server, served locally, no API key, MIT-licensed.

Semantic codebase search

Hybrid retrieval combining a local dense embedding model (ibm-granite/granite-embedding-english-r2, swapped in after earlier posts referenced Snowflake's arctic-embed) with BM25, weighted by how large and unfamiliar the codebase looks. Underneath that, dual-vector indexing: every symbol gets a body-stripped "purpose" vector alongside its full-body vector, closing a dilution gap where a symbol's own doc paraphrase of your query didn't surface it in the dense pool. A symbol graph backs vectr_locate (five fallback strategies, unchanged since Part 1) and vectr_trace for callers and callees. AST-aware chunking now covers 9 languages — Python, JavaScript, TypeScript, Go, Rust, Java, Zig, C, and C++ — with a windowed fallback for everything else.

Persistent working memory

The layer Part 2 was about. Five note kinds now carry genuinely distinct injection semantics instead of being flavors of the same thing: directive fires unconditionally every session, task carries current-work state, gotcha resurfaces when its anchored file is touched, finding is relevance-ranked, reference is a pointer. Recall is two-tier — a token-bounded index by default, full bodies only on request. Boot injection puts directives and high-priority tasks in front of the model before turn one. Snapshots checkpoint a whole working-memory state under a label.

14 MCP tools total. Everything runs on your machine; nothing about a search or a recall call leaves it.

Here's the part that isn't in the README. Before the tag went out, the three families of adoption behavior that make working memory actually get used — not just exist — went through what I've started calling a dogfood gate: a fresh reviewer, with no memory of building any of this, driving the release candidate through the real MCP tool surface, call by call, on real tasks. Not reading the code and nodding at it. Actually calling vectr_remember, actually calling vectr_recall, actually watching what came back, exactly the way a caller model would.

The three families under review map neatly onto the four families of context relief I wrote about a few weeks ago: subagent working memory (families 2 and 4 combined — offload-and-recall serving as the shared bus between an orchestrator and its subagents), token eviction (family 1, vectr's vectr_evict_hint and vectr_fetch), and hook-injected recall (the delivery mechanism from the hooks post). Two of the three passed clean: subagent memory and hook injection held up under adversarial first-person use. Eviction came back with a verdict of REWORK and two release-blocking defects.

That "re-running the same query on purpose" is the whole trick — it's the seam all three bugs hid in. A caller that has already seen a result will ask for it again — it re-checks a file it just touched, it re-fetches a chunk it saw ten turns ago. The first call to any of these paths worked fine. It was the second identical call that misbehaved, and a code review reading the function top-to-bottom has no reason to imagine that second call. You have to actually make it.

vectr_evict_hint orders the files it lists by recency — most-recently-retrieved first, so the caller sees what it just touched at the top. The recency dedup guard broke this in the single most common case: retrieving the same chunk twice. record() deduped a repeat retrieval by returning early — correct, in that it doesn't double-count tokens or store a second copy — but that early return also meant it never moved the chunk's position in the recency-ordered list. Run the same search again, get the same top hit back (which is exactly what happens when a caller re-checks something), and the file you'd just re-retrieved rendered dead last, as if it were the oldest thing in the session.

# before — dedup guard returns early, recency position never refreshes
def record(self, file_path, lines, ...):
    key = f"{file_path}:{lines}"
    if any(f"{c.file_path}:{c.lines}" == key for c in self._chunks):
        return
    self._chunks.append(RetrievedChunk(...))

# after — dedup hit moves the existing entry to the end instead of a no-op
def record(self, file_path, lines, ...):
    key = f"{file_path}:{lines}"
    for i, c in enumerate(self._chunks):
        if f"{c.file_path}:{c.lines}" == key:
            self._chunks.append(self._chunks.pop(i))  # fresh recency, no dup, no counter bump
            return
    self._chunks.append(RetrievedChunk(...))

The fix is three lines and reads as obvious once you've seen the failure. The point is that you don't see the failure by reading the "before" version — the early return looks like a correct, even careful, dedup. You see it by retrieving a.py, then b.py, then a.py again, and noticing that a.py — the thing you touched last — is sitting at the bottom of the list labeled as the stalest chunk in the session. The demo below is exactly that sequence. Toggle between the shipped fix and the bug and watch where a.py lands on the re-retrieve.

vectr_fetch exists to restore a chunk you saw earlier, exactly as it was, no re-search and no file re-read required. But large classes and methods get capped at index time — roughly 2000 characters per stored chunk — and _format_fetch_results() rendered whatever content was stored, with no signal when that content was itself incomplete.

_format_search_results() already detected this by comparing the rendered lines against the symbol's recorded start/end span and appending a Read(...) fallback; vectr_fetch never ran that check. The result: re-fetching a storage-capped chunk returned it silently truncated, directly contradicting the one guarantee vectr_fetch exists to make. A caller that trusted the re-fetch — the entire reason the tool exists is so it can trust the re-fetch — would work from a class body missing its last third and never know.

The fix pulled the detection into a shared _storage_cap_truncation_warning() helper so both surfaces — search's first showing and fetch's later re-showing — flag a capped chunk identically, and applied it to the CLI's vectr fetch renderer as well, which had the same gap on its own code path.

Both fixes shipped the same day, each with its own test — a dedup-then-recency-position test for the first, a re-fetch-of-a-capped-chunk test for the second — before the tag went anywhere near being cut.

A separate pass — not the adoption gate, but a measurement pass checking whether eviction was actually efficient, turn over turn — turned up a third defect the gate hadn't been looking for. The escalated eviction banner (the "action required, you have unsaved findings" version that only fires once both a chunk-count and a token-count threshold are crossed) lists a Re-fetch keys line telling the caller exactly which ids it can pull back instead of re-reading. That list was byte-identical across an entire session, no matter what had been retrieved since.

The cause: it sliced the front of an oldest-first list, so it pinned the session's very first chunks in that slot permanently.

# before — prefix slice over an oldest-first list pins the OLDEST ids forever
fetch_ids = [c.chunk_id for c in self._chunks if c.chunk_id][:EVICTION_HINT_MAX_IDS]

# after — suffix slice + reverse: newest retrieved first, matching the file list above it
fetch_ids = [c.chunk_id for c in self._chunks if c.chunk_id][-EVICTION_HINT_MAX_IDS:][::-1]

A one-line fix, caught only because someone asked "does this banner's content actually track the session, or does it just look plausible once?" — the kind of question a code review doesn't naturally ask and a live measurement pass does. It was fixed and tested the same day, before the README got its final pass and well before the tag. (It's the second half of the demo above: in "before" mode, the re-fetch keys line never changes no matter how many chunks you retrieve after the first three.)

The rule in force for all three: a defect found while dogfooding the release candidate gets fixed before release. Not logged as a follow-up, not shipped with an asterisk. If it's bad enough to find in a gate, it's bad enough to hold the tag for a few hours.

This is the section I care most about getting right, because it's the one most launch posts skip. Most "we shipped v1.0" posts for AI dev tools print the number that makes the tool look good and stop there. Vectr's README has a section literally titled "Measured costs, honestly", and the discipline behind that title is the actual point of this post, not a footnote to it.

The clean win

Recalling 3 stored notes with vectr_recall costs 360 tokens in one tool call. Re-deriving the same three facts with grep and Read, on the same 182-file Python repo, costs roughly 2,060 tokens across six tool calls — about 5.7× fewer tokens, 6× fewer calls, and it comes back in under 50 milliseconds. That's the /compact-and-cross-session story from Part 2, with an actual token count attached instead of an intuition.

The sprint-scale win, with its floor shown

Across the 6-task CPython sprint from Part 3, recall discipline cut re-discovery by 39% overall — but the per-task spread runs the full range from 0% to 85%, and the 0% task isn't hidden in a footnote. It's debug_descriptor_priority: a bug in Python's descriptor protocol, a part of the language the model already knows cold from training. Vanilla and vectr took the same 6 re-discovery calls. The honest read is the same one Part 3 landed on — vectr's advantage is proportional to how unfamiliar the code actually is to the model, and printing the 0% case next to the 85% case is what makes the 39% mean something.

The other side of the ledger

For a single pointed lookup on a small, already-familiar repo, grep is cheaper — vectr's median cost across 5 single-fact tasks ran +60% more tokens than grep — and grep is faster: a vectr_search round trip takes 1.7–3.6 seconds against roughly 28 milliseconds for a local grep. And the automatic reminder banners riding on tool responses aren't free either: the always-on re-fetch footer costs about 27 tokens, a light nudge about 89, and the escalated action-required banner (the one bug three lives in) scales from roughly 480 to 535 tokens before it plateaus.

The shape of the trade-off, stated plainly: vectr pays off on unfamiliar or large codebases, on work you come back to — later in the same session, after /compact, or in a new session entirely — and on long sessions with many turns. It does not pay off on a one-off grep against code you already know cold. That second sentence is not a caveat I'm burying. It's half of the value proposition. A tool whose docs only describe the conditions under which it wins is a tool whose docs you can't actually trust when it's your codebase on the line.

A handful of changes landed in the final pre-release wave, mostly because dogfooding the tool surfaces exactly the kind of gap that only shows up once you're relying on it for real work.

• Per-hook-kind injection counters, visible in vectr status. Before this, a working memory system that was silently failing to inject anything and one that was injecting correctly looked identical from the outside — both just sat there. Now you can see, per hook kind, how many injections actually fired.
• Gotcha injection extended to file reads, not just edits. A gotcha ("this file's config is regenerated, edit the source instead") used to fire only on Edit/Write. It now fires on Read too — the moment you open a file is often the moment you'd want the warning, not just the moment you're about to change it.
• Task-note recency, newest-first. This one came from my own resume-workflow pain: task notes used to sort by a trust/decay score that could put an old checkpoint ahead of the one I'd just written. They now sort newest-first, full stop.
• Explicit subagent attribution and the handoff pattern. vectr_remember(..., agent="coder-2") tags a note to the subagent that wrote it — never inferred, always explicit — and the orchestrator/subagent pattern this enables is durable handoff: a subagent finishes its investigation, writes its findings as notes, and the orchestrator recalls them instead of re-reading the subagent's entire transcript.
• Watcher burst governor and an RSS self-limit, so a large or rapid burst of file changes (a branch switch, a big refactor landing) doesn't let the file watcher run away with CPU or memory.
• --memory-only mode. Working memory and hooks, with no code index and no file watcher — for projects where you want the memory half without paying indexing cost at all.

2,275 tests passing, and the full suite runs independently before every push to main — not sampled, not "the tests relevant to the diff," the whole thing. That's the mechanical backstop underneath the dogfood gate: the gate catches the class of bug that only shows up in real usage of a real tool call sequence; the test suite catches everything else, every time, before anything merges.

The two do different jobs. A test asserts that a behavior you already know about stays fixed. The gate goes hunting for behavior nobody thought to assert yet — which is exactly why all three bugs here were caught by a human making a second identical call, not by a red test. Each one became a test the moment it was found. Gate discovers, suite pins.

A few things are missing on purpose, not by oversight, and I'd rather say so than let the README's silence on them read as an accident.

Codex CLI support. The host matrix in the README marks it "Planned (post-v1)" — every other editor listed there is either verified or experimental, meaning the MCP config at minimum works. Codex CLI gets neither yet. It's next, not skipped.

A search-relevance floor I haven't shipped. The efficiency measurements above point at an obvious-looking fix: vectr_search returns five results by default with no minimum relevance score, so the low-scoring tail — chunks matching at 0.15 that have nothing to do with your question — gets returned and paid for anyway. Cutting that tail is the single biggest token lever the measurement pass found. It's also exactly the kind of change I refuse to rush: a score floor that trims noise on easy queries can silently drop the correct answer on hard ones, where the right symbol legitimately scores low. Shipping a ranking change on hope instead of evidence is exactly the kind of thing this whole post is arguing against, so it waits for a proper evidence gate against the full acceptance corpus.

PyPI. Install today is pip install git+https://github.com/swapnanil/vectr. A proper PyPI package is coming; it wasn't worth holding the tag for.

The immediate queue is the three items above, roughly in that order: Codex CLI parity, then the relevance floor once it clears its own evidence gate, then packaging. Longer-term, the interesting open question is the one Part 3 ended on and I still don't have a better answer to: controlled benchmarks tell you the tool isn't broken, but they don't tell you whether it helps you, on your codebase, with your tasks.

The benchmarks and the honest numbers in this post are the evidence that the approach works in principle. Whether it's worth the five minutes of setup for your specific situation is something only running it will tell you — and now there's a tagged, gated, honestly-documented 1.0 to run.