Skip to main content
Glama
swapnanil

Vectr

by swapnanil
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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 License: MIT Python 3.14+ Version 1.12.0 MCP: 23 tools

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.

Related MCP server: aivectormemory

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

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)

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.

Editor

Config

Status

Claude Code

Auto: .claude/settings.json, guidance file, and session hooks (memory auto-injected at session start, per prompt, and before file read or edit)

Verified

Cursor

Auto: .cursor/mcp.json

Experimental

VS Code / GitHub Copilot

Auto: .vscode/mcp.json

Experimental

Windsurf

Manual, see below

Experimental

Cline

Manual, see below

Experimental

Continue

Manual, see below

Experimental

Codex CLI

Auto: .codex/config.toml, AGENTS.md guidance, and .codex/hooks.json (vectr init --hooks)

Experimental

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

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 one-time interactive prompt to trust the project before it loads a project-scoped config. If you also ran vectr init --hooks, Codex shows a second one-time prompt to trust the hook commands. Both persist after you accept them once, and a config writer cannot clear them for you without weakening your security posture.

Stdio transport

The editors above connect over HTTP (vectr start plus POST /mcp). For MCP clients and hosting platforms that spawn the server as a subprocess and speak MCP over its stdin and stdout instead of opening an HTTP connection, run:

vectr mcp-stdio [WORKSPACE]

No port, no daemon: a single foreground process framed as newline-delimited JSON-RPC 2.0 (one JSON object per line on each of stdin and stdout, no Content-Length headers). initialize and tools/list answer immediately, while the embedding model load and initial indexing happen on a background thread. A tools/call made before that finishes gets a graceful "still starting up" response instead of hanging. Stdout carries protocol JSON only, and all logging goes to stderr. The process exits cleanly on stdin EOF. --memory-only and --search-only behave the same as on vectr start.

How it works

  1. AST-aware chunking. tree-sitter parses each file and splits at function, class, and method boundaries. No chunk breaks mid-logic.

  2. Code embeddings. ibm-granite/granite-embedding-english-r2 (local, CPU-fast, overridable) maps natural-language queries to code symbols, so "JWT validation" finds verify_jwt_token. BM25 handles exact symbol names.

  3. Hybrid search. Vector similarity and BM25 combined, weighted by codebase characteristics. Large and unfamiliar leans semantic, small and well-documented leans BM25.

  4. Symbol graph. Call edges, import chains, and HTTP routes (Flask, FastAPI, Express, Spring) are extracted and stored. vectr_locate resolves a name through a 6-strategy cascade: exact match, suffix, same-module, import-chain, substring, then fuzzy. A fuzzy answer is always rendered as explicitly inexact rather than presented as a confident match, because a confident wrong symbol is worse than a not-found.

  5. Working memory. vectr_remember stores structured notes to SQLite and ChromaDB. vectr_recall runs semantic search over notes rather than a SQL LIKE, so multi-word queries still find the relevant context.

  6. Trigger evaluation. Each note's conditions are checked deterministically by the daemon at lifecycle moments, with a per-session fire ledger and injection budgets, so a note resurfaces exactly when it applies and never twice in the same window.

  7. MCP protocol. 23 tools served over HTTP. Any MCP-compatible AI code editor connects without plugins.

23 MCP tools

vectr start writes a guidance file into your workspace with this table, so your AI code editor knows which tool to reach for without being prompted.

Search tools, which retrieve code from the index:

Situation

Tool

You know a concept or behaviour, not a name

vectr_search("description")

You know a symbol name, not its file

vectr_locate("SymbolName"), with a multi-strategy fallback cascade and optional caller_file

You need callers or callees of a symbol

vectr_trace("symbol_name")

You need an architectural overview

vectr_map()

You want to save a synthesised map summary

vectr_map_save(summary)

You have runtime call data to inject

vectr_ingest_traces([{caller, callee}])

You need index health or note count

vectr_status()

Memory tools, which store and recall across sessions:

Situation

Tool

Notes exist from a prior session

vectr_recall(query), semantic vector search rather than substring match, two-tier (crisp index by default, expand one note with note_id=N or all bodies with detail='full')

One note must survive every recall regardless of the query

vectr_pin(note_id=N), which places it in Tier 0 so it is injected on every vectr_recall(query=...) call. Bounded, so pin sparingly. vectr_remember(..., pin=true) does the same at write time

You found something worth preserving

vectr_remember(content, tags, priority, kind, title, agent). kind controls delivery: directive fires unconditionally every session, task carries current-work state, gotcha resurfaces when its file is touched, operational covers build and environment facts, finding (the default) is relevance-ranked, reference is a pointer, and decision is an architectural decision recallable as a chronological ADR-style timeline via vectr_recall(kind="decision", sort_by="chronological"). title labels the note in index output, and agent attributes it to a subagent or orchestrator

A stored note turns out to be about a file you did not declare

vectr_anchor(note_id=N, anchors=[...]), attaching file anchors to an existing note without re-storing it. Idempotent, hashed at write time, and it emits no lifecycle event, so the note's history stays clean (also vectr anchor --id N PATH... on the CLI)

A stored note was anchored to the wrong file, or the anchored file's relevance is gone

vectr_unanchor(note_id=N, anchors=[...]), the inverse of vectr_anchor. Removes file paths from a note's anchor set; a removed anchor simply stops being a staleness candidate, never a claim that the note is wrong. Idempotent, paths the note was never anchored to are reported back rather than treated as failures

Starting a session, want to pick up where you left off

vectr_resume(), returning the most recent task note, the latest snapshot, and open gotchas with their file anchors in one call (also vectr resume on the CLI)

Context is filling up

vectr_evict_hint(), which identifies chunks vectr can re-retrieve, with the exact re-fetch ids

A chunk shown earlier has left your context

vectr_fetch(ids=[...]), a deterministic byte-verbatim re-fetch by id, with no re-search and no file re-read. Flags a truncation warning if the index itself stored a capped chunk

End of a long session, want a checkpoint

vectr_snapshot("label")

Looking for a prior checkpoint

vectr_snapshot_list()

Notes are stale after a large refactor

vectr_forget(note_id=N) per note, or vectr_forget(all=true) to clear

An auto-captured note has been reviewed and still holds

vectr_promote(note_id=N), raising its trust class one step from auto to agent. Promotion to human is reserved for user-side surfaces, never the agent's call

Automatically captured failure-to-success moments are waiting

vectr_distill(), which renders pending arcs (a command failed, then passed after an edit) for review. Persist a lesson with vectr_remember(..., distilled_from=[arc_id]) or dismiss with vectr_distill(dismiss=[...], reason)

A stored note turned out to be wrong

vectr_revoke(note_id=N, reason), which keeps the note visible as a deterrent ("previously believed ..., revoked ...") instead of deleting it, so the mistake is not silently re-derived. vectr_remember(contradicts=N) corrects and revokes in one step

A note is simply out of date, not wrong

vectr_supersede(note_id=N, successor_note_id=M), which retires it in favour of a newer note without revoke's "proven wrong" framing. The audit trail records post-hoc retirement distinctly from write-time supersession, and vectr_reinstate reverses it

A revoked note was right after all

vectr_reinstate(note_id=N), restoring the original content

Triggers: the delivery layer

Those kind values carry sensible defaults. A note can also declare explicit per-note triggers on vectr_remember:

Axis

Fires when

path

A glob matches the file the current lifecycle moment targets

symbol

The targeted file defines or references that symbol, resolved exactly against the same symbol graph vectr_locate uses, never fuzzy

semantic

Prompt similarity clears a fixed per-kind threshold

event

A lifecycle moment occurs: session-start, prompt-submit, pre-edit, pre-run, pre-commit, or post-compaction

command

The normalized verb of an about-to-run shell command matches a glob

temporal

not_before, expires_visibility, and cooldown guards, which modify a fire but never cause one alone

Conditions AND within one entry and OR across entries. Every fire carries a one-line explanation of which trigger matched. Injection is budgeted (a hard per-turn cap spent jointly across surfaces), deduplicated by note id across every surface within a turn, and framed by provenance, so an unreviewed auto-captured note never renders with the authority of a standing rule from you. A note is never partially truncated: it arrives whole, as an index-tier line, or not at all.

Workspace-scoped notes double as a shared bus for multi-agent workflows. An orchestrator and its subagents all read and write the same note store, so a subagent can call vectr_remember(..., agent="coder-2") with its findings before finishing, and the orchestrator recalls them instead of re-reading the subagent's full transcript. The agent parameter is never inferred. It is explicit attribution, and it shows up as a tag in vectr_recall index output.

CLI reference

vectr start                           # index + start daemon for current dir
vectr start /project/api              # positional workspace: a directory or .code-workspace file
vectr start --path /project/api       # specific workspace (repeatable, multi-root)
vectr start --memory-only             # working memory + hooks only, no code index, no watcher
vectr status                          # index health, chunk count, notes count
vectr status --all                    # all running instances
vectr stop /project/api               # stop one instance (same positional as start)
vectr stop --path /project/api        # stop one instance (equivalent --path form)
vectr stop --all                      # stop all instances
vectr index --path .                  # re-index without restarting daemon
vectr fetch src/auth.py:10-42         # re-fetch a chunk by exact id, verbatim
vectr resume                          # most recent task note, latest snapshot, open gotchas
vectr init --path .                   # write guidance file + MCP config without starting
vectr init --exclude vendor           # exclude directories from indexing
vectr forget --path .                 # delete all working-memory notes
vectr memory export                   # render the working-memory store as a greppable, git-diffable markdown file (default MEMORY.md)
vectr memory export --path notes.md   # write the export to a specific file
vectr memory export --disable         # stop the auto-refresh that keeps the export file in sync
vectr memory edit                     # open the working-memory store in your $EDITOR, one block per note
vectr memory import                   # bring existing on-disk memory files into the working-memory store (see below)
vectr memory import --path NOTES.md   # import a specific file instead of the default discovery list
vectr memory import --dry-run         # preview what would be created (kind, title, source file, line range), change nothing
vectr cache prune                     # remove empty per-workspace cache dirs (live instances skipped)
vectr cache prune --dry-run           # preview what would be removed, delete nothing
vectr proxy                           # experimental: localhost API proxy (see below)
vectr mcp-stdio                       # foreground stdio MCP transport, no port or daemon (see above)

Importing existing memory

vectr memory export and vectr memory edit are the one-way-out and check-out/check-in paths. vectr memory import is the one-way-in: it brings existing on-disk memory into the working-memory store without re-entering it by hand. This is the on-ramp for a new user who already has memory written down.

Discovery. With no --path, the importer walks a closed list of default candidate files at the workspace root: MEMORY.md, CLAUDE.md, AGENTS.md, .cursorrules, and .github/copilot-instructions.md. Pass --path (repeatable) to point at any other file or directory; a directory is walked recursively for *.md and *.mdc files. Files that don't exist are reported but never raised on, since most workspaces will not have every default file.

Granularity. A source file is not one note and not one note per line. It is split at Markdown heading boundaries (^#{1,6}\s+), the same way a human skims a MEMORY.md. A heading-less file becomes one note. Headings inside fenced code blocks and HTML comment blocks are skipped, so a code example or the export-file header comment does not become a section boundary. A file previously exported by vectr memory export is detected by its <!-- Generated by ... --> header and parsed through the same block grammar vectr memory edit uses, recovering each original block as a note with its declared kind, priority, tags, and provenance carried forward.

Dry run. --dry-run prints exactly what would be created (kind, title, source file, source-line range, provenance) and changes nothing. Memory is the one resource the user cannot easily reconstruct, so dry run is the path of first resort:

vectr memory import --dry-run
# + [finding/auto] 'Project conventions'  (MEMORY.md:12-34)
# + [operational/agent] 'Test runner'  (CLAUDE.md:5-9)
# DRY RUN: would create 2 note(s), skip 0 already-imported, ...

Idempotency. Every imported note carries a src:, src-sha:, and src-lines: tag triple. A re-run of vectr memory import against an unchanged source file recognizes those tags and creates zero new notes. Editing a section of the source file produces a new body whose hash does not match the stored one, so it becomes a new note, and the old one is left untouched, since silently deleting a prior import behind the user's back is exactly the silent loss the design defends against on the export side.

Provenance. Imported notes carry a source-file tag (imported and src:FILENAME, where FILENAME is the basename of the source file), so a recall that lists a note carrying imported is telling the user "this came from a file, not from this session's observations." The note's provenance defaults to auto, the class machine-captured facts with no reviewing judgment already carry, since a hand-written MEMORY.md is structurally indistinguishable from a generator's output to a parser. The exception is narrow and structural, not semantic: a note whose body contains imperative-rule markers (the closed keyword set MUST, MUST NOT, NEVER, ALWAYS, DO NOT, DON'T, REQUIRED, FORBIDDEN) is classified as kind="directive" and upgraded to provenance="agent". The reason is the auto + directive write-time guard in remember(): an unreviewed standing rule is a contradiction in terms, and an imported rule is exactly that pair. Promoting to agent is the smallest possible deviation from auto, exactly enough to satisfy the guard, and the user promotes further with vectr_promote after review.

Excluding paths

Create .vectrignore in your project root (same syntax as .gitignore):

vendor/
node_modules/
*.pb.go
dist/

Or pass --exclude at init time:

vectr init --exclude vendor --exclude dist

Exclusions apply to both the initial index walk and the live file watcher, so adding a directory to .vectrignore stops a running instance from re-indexing it. The next index also prunes any chunks already stored for now-excluded or deleted files, so you do not have to rebuild from scratch. If you ever need a clean rebuild, for example after changing the embedding model, force one:

vectr index --path . --force      # ignore the incremental cache, re-embed everything

Supported languages

Language

Chunking

Symbol graph

Python

AST (functions, classes)

Yes

JavaScript

AST (functions, classes, arrow fns)

Yes

TypeScript

AST

Yes

Go

AST

Yes

Rust

AST

Yes

Java

AST

Yes

C

AST

Yes

C++

AST

Yes

Zig

AST

Yes

All others

200-line windows, 50-line overlap

No

HTTP routes (Flask and FastAPI decorators, Express app.get(), Spring @GetMapping) are extracted as symbols and searchable via vectr_locate("GET /api/users").

Cost

Cost

Embedding model

$0.00, a one-time download of about 290 MB, cached at ~/.cache/vectr/

Re-index (10k files, first run)

About 10 min on CPU, under 5 sec on subsequent runs (mtime cache)

Incremental re-index per changed file

About 0.5 sec

vectr_search / vectr_recall

$0.00, local inference only

Security

The default is unchanged and stays the headline: local, no API key, zero config, for a solo developer on a personal machine. Out of the box, the daemon binds to 127.0.0.1 only, CORS is restricted to localhost origins, each workspace gets its own isolated DB directory, port, and process (owner-only 0700 on POSIX), and the index and notes persist locally in ~/.cache/vectr/.

Everything below is opt in. Enabling nothing changes nothing.

Authentication. Set VECTR_API_KEY and every request to /v1/* and /mcp must carry it (X-Api-Key: <key> or Authorization: Bearer <key>, constant-time comparison, with /v1/health left open for liveness probes). Generate a key with vectr key. When the key is set at start time, the editor MCP configs vectr writes include the header automatically. Those files (.mcp.json, .cursor/mcp.json, .vscode/mcp.json) then hold the key in plaintext, so treat them as secrets and keep them out of shared or public version control.

Encryption at rest. Set VECTR_ENCRYPT_KEY, or store a passphrase in the OS keychain (service vectr, username encrypt-key, requires pip install vectr[encryption]), and note content, note titles, and snapshot payloads are encrypted with Fernet and a PBKDF2-derived key. Honest boundary: the code index is not encrypted, because the search engine needs readable chunk text and vectors. Protect it with OS full-disk encryption. Note tags and metadata stay plaintext, and note embedding vectors (a lossy projection of note text) are kept for semantic recall unless you set VECTR_ENCRYPT_DISABLE_NOTE_VECTORS=1.

Retention and audit. Notes are kept until you delete them. Set VECTR_NOTES_TTL_DAYS to auto-purge older notes at startup. vectr_forget(all=true) and vectr forget --all delete notes, snapshots, and note vectors, so everything means everything. Set VECTR_AUDIT_LOG=<path> for a rotating local log of index, search, remember, and recall events (off by default, and it records query text, which is its purpose, and is never transmitted). Full policy: docs/data-handling.md.

Team mode (shared instance). One central daemon can serve a team on one repo. Run VECTR_API_KEY=<key> vectr start --host 0.0.0.0 on the server (a non-loopback bind refuses to start without a key), then vectr connect --url http://<host>:<port> --api-key <key> --label <you> on each client to point the editor at it. Working memory is shared: a note one agent stores, every connected agent can recall, and --label attributes notes and audit lines. Note IDs are allocated by the central store in the order writes arrive, so with concurrent clients your notes are not a contiguous block. They interleave with other clients'. The Stored note #N line the write returns is the canonical reference to that specific note, so do not assume the next ID is also yours. Plain limits: one shared key means every holder is an equal, trusted peer (no roles, no per-user permissions), the server operator can read everything, search results reference the server's checkout, which may differ from your local tree, and vectr speaks plain HTTP, so put TLS at a reverse proxy or tunnel if the network is not trusted.

Proactive context (experimental, localhost only)

Pull-based recall means the agent has to ask. Proactive context extends deterministic delivery to hosts without session hooks, by sitting on the wire instead. It is experimental and localhost only. Since 1.6.0 proactive delivery is on by default on local instances (proactive.enabled; turn off with VECTR_PROACTIVE=0). The wire channel below is governed by launch consent instead of that switch: starting the proxy and pointing your agent at it is the opt-in, and stopping it or unsetting the base URL is the opt-out.

The vectr proxy command runs a small local proxy between your agent and the model API:

vectr proxy                            # starts a localhost proxy (default :8785)
export ANTHROPIC_BASE_URL=http://127.0.0.1:8785   # point your agent at it

What it does and does not do, plainly:

  • Transparent by default. It forwards every request to the real API, and streaming responses and tool calls pass through byte for byte. Your API key is forwarded untouched and never stored or logged.

  • Deterministic injection. With the workspace daemon running, it appends matched working-memory notes to the request after the last prompt-cache breakpoint, so your prompt cache is never invalidated. Triggering is a similarity threshold plus exact structural matches, never keyword guessing, with a strict per-request budget so a hint only lands when it is worth the tokens.

  • Fail open. If the intelligence layer is slow or errors, your request goes through unchanged. To bypass the proxy entirely, unset the base URL: unset ANTHROPIC_BASE_URL. The proxy is on the request path, so if it is down, unset the variable to talk to the API directly.

  • Solo and localhost only. It reads your conversation to compute context, so it refuses any non-loopback bind and is mutually exclusive with team mode.

  • Caveats on a non-first-party base URL, per the host's own documentation: MCP tool search is disabled unless ENABLE_TOOL_SEARCH=true and the proxy forwards tool-reference blocks, and Remote Control is disabled on a non-api.anthropic.com base URL.

Org-wide caching (team mode). With a central shared instance, vectr can cache its own expensive artifacts, namely semantic search and recall results, keyed by exact identity and the current index state, so a re-index or note change invalidates them automatically and every connected developer benefits. It is off by default (proactive.cache), and vectr status reports its hit rate and estimated tokens saved so the value is measured rather than asserted. Vectr does not cache LLM responses across similar requests, only byte-identical ones, locally, and opt in, because a wrong cache hit would silently corrupt a conversation.

When vectr can hurt

Stale notes after codebase churn. Notes store file paths at write time. After a large refactor, vectr_recall flags changed referenced files with [STALE]. Re-verify before acting, delete the stale note with vectr_forget(note_id=N), or clear everything with vectr_forget(all=true).

Over-retrieval on a well-known API. If the model already knows a framework deeply from training, vectr's research overhead may exceed the savings. The benchmark above shows exactly that on debug_descriptor_priority, a task where training knowledge alone was enough to navigate.

Stale architectural overview. A passport saved by vectr_map_save describes the architecture at index time. After renamed modules or restructured entry points it can be confidently wrong, so vectr_map surfaces a staleness warning and you should re-run vectr_map_save.

Broad recall costs tokens. vectr_recall() with no query returns everything. Pass a targeted query, and check vectr_status() first if you are unsure whether recall is warranted at all.

Built with

Python 3.14 · FastAPI · sentence-transformers · tree-sitter · ChromaDB · BM25 · Docker

Author

Swapnanil Saha · swapnanilsaha.com

Available Tools

23 tools
vectr_anchorA
Idempotent

Attach file paths to an EXISTING note so future changes to those files can flag the note as possibly-stale (UPG-ANCHOR-ATTACH). The single-call replacement for re-storing with anchors=[...] and supersedes= when you notice afterwards that a note is about a specific process/config file. Anchors are staleness probes, never a claim that the note is wrong: on the next staleness check, a changed anchor means the process MAY have changed. Idempotent — paths already attached are reported back, not duplicated.

ParametersJSON Schema
NameRequiredDescriptionDefault
anchorsYesWorkspace-relative file paths to anchor this note to (at least one)
note_idYesID of the note to attach anchors to (the [#N] id from vectr_recall)

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate idempotentHint=true and destructiveHint=false; the description adds important nuance by defining anchors as staleness probes rather than correctness claims, and by explaining that already-attached paths are reported back rather than duplicated. There is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then packs the alternative workflow, anchor semantics, and idempotency behavior into four dense sentences. Every sentence adds operational value without filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with 100% schema coverage and idempotency annotation, the description covers the operation's purpose, when to use it, the meaning of anchors, and the behavior on repeated invocation. No critical missing information prevents an agent from calling it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents both required parameters with 100% coverage, including workspace-relative paths and the source of note_id. The description reinforces the semantics but does not need to add much beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: attach file paths to an existing note, with a clear purpose of flagging possibly-stale notes. It also distinguishes itself from re-storing with anchors/supersedes, helping an agent tell this operation apart from related vectr tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly frames the tool as 'the single-call replacement for re-storing with anchors=[...] and supersedes=<note_id>' and gives the trigger condition: when you notice afterwards that a note is about a specific process/config file. This is clear when-to-use guidance and implies when the alternative workflow would be preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_distillA
Idempotent

Review pending arcs — discovered failure->success moments captured automatically from your own tool calls (e.g. a command that failed twice, then succeeded after an edit) — and turn the ones worth keeping into working-memory notes. Call with no arguments to render pending arcs for review, oldest and most-confident first, token-bounded. For each arc worth keeping, call vectr_remember(..., distilled_from=[arc_id]) to persist the lesson as a note (see vectr_remember's own parameters for kind/priority/triggers). For arcs not worth keeping, call vectr_distill(dismiss=[arc_id, ...], reason='...'). Distiller rules: (1) recall-first dedupe — vectr_recall(query=) before writing; if an existing note already covers it, dismiss the arc (reason: covered by note #N) — if the arc proves an existing note wrong or outdated, use contradicts=/supersedes= on that note instead of writing a duplicate. (2) Generalize — store the lesson (what class of command fails, why, what fixed it), not the transcript; keep concrete commands/paths only when they ARE the lesson. (3) Kind mapping — an env/process/build fact -> kind='operational' (add triggers=[{'event': 'prompt-submit', 'semantic': True}, {'command': ''}] when the lesson is tied to a command family); tied to specific files -> kind='gotcha' with those files as anchors; a standing user rule -> kind='directive' (rare from arcs). (4) Low-confidence arcs are dismissed unless the same lesson recurs across >= 2 arcs. (5) Priority defaults to medium; high only when acting on the stale belief is costly (e.g. false-pass verification traps). (6) Batch cap — distill at most ~5 notes per sitting; leave the rest pending.

ParametersJSON Schema
NameRequiredDescriptionDefault
reasonNoRequired together with dismiss= — why these arcs are not worth distilling (e.g. 'covered by note #12', 'transient network flake').
dismissNoArc ids (from this tool's own render or GET /v1/arcs) to dismiss without distilling into a note. Pass together with reason.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description discloses extensive behavioral details: token-bounded rendering, oldest-first ordering, batch cap, deduplication rules, and kind mapping. No contradiction with annotations (idempotentHint=true is consistent with idempotent dismiss).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is verbose but well-structured with front-loaded purpose and numbered rules. Every sentence adds value, though could be slightly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given tool complexity (multiple modes, rules, and integration with other tools), the description is remarkably complete. Covers all states: render, dismiss, and distiller rules. No output schema, but return value (rendered arcs) is implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions, but the description adds essential semantics: explains that dismiss and reason must be used together, provides examples, and clarifies behavior with no arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool reviews pending arcs (failure->success moments) and distills them into working-memory notes. It distinguishes from sibling 'vectr_remember' by positioning itself as the review/dismiss step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: call with no arguments to render arcs, call with dismiss+reason to reject, and detailed rules for when to keep vs dismiss. References alternatives like vectr_remember and vectr_recall for deduplication.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_evict_hintA
Read-onlyIdempotent

Lists the code chunks retrieved by THIS session that are safe to drop from context — each is re-fetchable verbatim in one deterministic call, and the response includes the exact vectr_fetch(ids=[...]) re-fetch keys. Use at the exploration → implementation transition, or when context pressure builds. This is the reverse signal in the vectr protocol: the AI saves findings (vectr_remember), vectr signals what it can restore instantly (vectr_evict_hint). NOT needed on short sessions — most useful after many vectr_search/vectr_locate calls.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint, idempotentHint), description adds that each chunk is re-fetchable with exact vectr_fetch keys, explaining the protocol relationship with vectr_remember. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four concise sentences with no waste. Front-loaded with purpose, then usage guidance, then protocol context, then limitations. Each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters or output schema, description fully covers what the tool does, when to use it, its role in the protocol, and its limitations. Complete for this tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters (0 params), so schema coverage is 100%. Description adds meaning about return value (list of chunks with re-fetch keys), exceeding baseline of 4 for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Lists the code chunks retrieved by THIS session that are safe to drop from context', with verb and specific resource. It distinguishes from sibling tools by positioning as the reverse signal in the vectr protocol.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance: 'Use at the exploration → implementation transition, or when context pressure builds.' Also notes it's 'NOT needed on short sessions' and identifies when it's most useful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_fetchA
Read-onlyIdempotent

Deterministic re-fetch of a code chunk by its exact id — no embedding, no rerank, just the chunk. Every vectr_search/vectr_locate/vectr_trace result carries its chunk's id (the file:start-end shown in the result header). Use this to restore a chunk that was cleared from your context (by tool-result eviction, context compaction, or a context-editing tombstone) instead of re-running vectr_search or re-reading the whole file. NOT for finding NEW content — use vectr_search for that.

ParametersJSON Schema
NameRequiredDescriptionDefault
idsYesChunk ids to restore, exactly as shown in a prior search/locate/trace result (e.g. 'src/auth.py:10-20').

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. The description adds that the operation is 'deterministic', 'no embedding, no rerank', and explains the id format 'file:start-end' from prior search results. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tightly-packed sentences with zero waste. The most critical information (purpose and when to use) is front-loaded, followed by the id format reference and a clear exclusion statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the tool's behavior is simple. The description covers purpose, usage context, parameter semantics, and safety (via annotations). It could optionally describe the return format, but the current content is sufficient given the low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a description for the 'ids' parameter. The tool description adds valuable context about the id format and provenance ('exactly as shown in a prior search/locate/trace result'), going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Deterministic re-fetch of a code chunk by its exact id' and distinguishes from siblings by explicitly naming vectr_search, vectr_locate, and vectr_trace for finding new content. The verb 're-fetch' and resource 'code chunk' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'restore a chunk that was cleared from your context' and when not to: 'NOT for finding NEW content — use vectr_search for that'. Provides concrete alternatives, making selection straightforward.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_forgetA
DestructiveIdempotent

Delete working-memory notes. Pass note_id to delete ONE note — the usual case, when a note is stale or superseded (ids are the [#N] shown by vectr_recall). Pass all=true to irreversibly clear EVERY note for this workspace (e.g. after a large refactor). Calling with no arguments deletes nothing. Snapshots are preserved — only active notes are removed.

ParametersJSON Schema
NameRequiredDescriptionDefault
allNoSet true to delete ALL notes for this workspace. Irreversible.
note_idNoID of the single note to delete (the [#N] id from vectr_recall)

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true, but the description adds critical details: snapshots are preserved (only active notes removed), the all=true option is irreversible, and no-arg call does nothing. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at four sentences, each serving a distinct purpose: overall function, note_id usage, all=true usage, and edge cases (no args, snapshots). It is front-loaded with the purpose and efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, the description fully covers behavior for both parameters, the no-argument case, and side effects (snapshot preservation). It references a sibling tool for IDs, making it self-contained and complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions are 100% covered, but the description adds practical meaning: note_id is the [#N] from vectr_recall, and all=true is irreversible. This helps the agent understand the context and consequences of each parameter beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes working-memory notes. It distinguishes between deleting one note by ID (the usual case) and deleting all notes (for refactoring). It references the sibling tool vectr_recall for note IDs, making the purpose specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: use note_id for stale or superseded notes, use all=true after a large refactor, and calling with no arguments deletes nothing. This helps the agent decide when and how to invoke the tool, distinguishing it from other memory tools like vectr_recall or vectr_remember.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_ingest_tracesA

Import runtime trace events into the symbol graph to enrich static call analysis. Use when you have runtime profiling data (Python sys.settrace output, JSON trace logs) that reveals dynamic dispatch patterns the static analyser cannot see: decorators, getattr, dependency injection, monkey-patching, etc. Pass a list of trace events: [{caller, callee, caller_file?, caller_line?}, ...]. Dynamic edges are stored with edge_type='dynamic' and appear in vectr_trace results marked "(dynamic)" so you can tell them apart from statically-discovered calls. A caller/callee name that matches no indexed symbol is still ingested (it may be external or runtime-only) but is reported back as a warning — check for typos. NOT needed if static analysis (vectr_trace) already shows the call relationships.

ParametersJSON Schema
NameRequiredDescriptionDefault
eventsYesList of trace events. Each event: {caller, callee, caller_file?, caller_line?}

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (which indicate mutation but not destructiveness), the description discloses that dynamic edges are stored with edge_type='dynamic' and appear as '(dynamic)' in results. It also warns about typos: unknown symbols are ingested but reported as warnings. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that efficiently conveys purpose, usage, behavior, and parameter details with no fluff. It's front-loaded with the main action. Slight improvement could be breaking into sections, but it remains very concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has one parameter with nested objects and no output schema, the description covers the complete behavioral context: ingestion of dynamic edges, marking, warnings for unrecognized symbols, and when not to use. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaning by explaining the event structure, noting optional fields (caller_file, caller_line), and describing behavior for unmatched symbols. This goes beyond the schema's parameter types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly says 'Import runtime trace events into the symbol graph to enrich static call analysis,' using a specific verb and resource. It distinguishes from siblings by contrasting with static analysis (vectr_trace) and listing dynamic dispatch patterns (decorators, __getattr__, etc.) that only this tool handles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use when you have runtime profiling data... that reveals dynamic dispatch patterns the static analyser cannot see.' Also gives a clear when-not: 'NOT needed if static analysis (vectr_trace) already shows the call relationships.' This is excellent guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_locateA
Read-onlyIdempotent

Use when you know the SYMBOL NAME but not which file it's in. Returns file path + line number + kind for every matching definition. NOT when you're searching by concept or behaviour — use vectr_search instead. NOT when you want call relationships — use vectr_trace instead. Example: vectr_locate(name='EvaluateSegments') → 'targeting/evaluator.go:45'

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesSymbol name or partial name to locate (case-sensitive partial match)
limitNoMax results (default: 10)
caller_fileNoAbsolute path of the file containing the call site. Enables same-module and import-chain fallback strategies.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the absence of side effects is covered. The description adds that the tool returns file path, line number, and kind, which is useful but not behavioral. No additional traits (rate limits, auth needs) are disclosed, but the read-only nature is clear from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (3 sentences plus an example), front-loads the core purpose, and every sentence adds value. No redundant or wasteful language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, no output schema, and annotations already cover read-only/idempotent, the description is fairly complete. It states the output format, provides usage guidance, and gives an example. Minor gap: no description of the 'limit' and 'caller_file' parameters beyond schema, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description provides an example using the 'name' parameter and implies case-sensitive partial match, but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (locate), the resource (symbol definition), and the output (file path + line number + kind). It also explicitly distinguishes from siblings by stating when NOT to use it, listing alternatives vectr_search and vectr_trace.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use ('when you know the SYMBOL NAME but not which file it's in') and when-not-to-use criteria ('NOT when searching by concept/behaviour' and 'NOT when wanting call relationships'), with specific alternative tools named (vectr_search, vectr_trace).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_mapA
Read-onlyIdempotent

Use at the start of a session on an UNFAMILIAR codebase to get a structural overview without reading any files. If a passport has been saved: returns a compact (~300 token) plain-English summary instantly. If not yet saved: returns raw structural metadata (dir tree, languages, frameworks) and instructs you to call vectr_map_save with your synthesised summary. NOT needed if you already know the codebase structure. NOT a substitute for vectr_recall — call vectr_status first to check for prior notes.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations: it explains that the tool returns a compact summary if a passport is saved, or raw metadata with instructions otherwise. It also states it does not read files. This aligns with readOnlyHint and idempotentHint without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the key use case and conditional behavior. While somewhat lengthy, every sentence provides essential information. It could be slightly more concise but is well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's conditional behavior and lack of output schema, the description thoroughly explains both possible outcomes and actionable next steps. It also mentions sibling tools for context, making it complete for the agent's decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the description doesn't need to explain parameters. However, it adds meaningful context about the conditional behavior and return types, which compensates for the lack of parameters. A score of 4 is appropriate as it fully covers what the tool expects and does.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to get a structural overview of an unfamiliar codebase at the start of a session. It specifies the output based on whether a passport is saved, distinguishing it from related tools like vectr_recall and vectr_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit usage guidance is provided: it should be used at the start of a session on an unfamiliar codebase, and not when the codebase is already known. It also directs to call vectr_status first and mentions vectr_map_save as a follow-up if needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_map_saveA
Idempotent

Save your synthesised codebase summary as the permanent passport. Call this ONLY after vectr_map returned raw metadata — i.e. on your first visit to a codebase. NOT when vectr_map already returned a saved summary (passport already exists). Write a concise plain-English summary: what the codebase does, tech stack, key modules, entry points, domain terms. Aim for ~200-350 tokens. Does NOT overwrite an existing passport by default — if one is already saved, the call is a no-op and returns the existing summary; pass overwrite=true to replace it.

ParametersJSON Schema
NameRequiredDescriptionDefault
summaryYesYour plain-English codebase summary (~200-350 tokens)
overwriteNoSet true to replace an already-saved passport. Default false.

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate idempotentHint=true and destructiveHint=false. The description aligns, stating the call is a no-op if a passport already exists. It also adds details like token length guidelines and that overwrite=true replaces the existing summary.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (~4 sentences) and front-loaded with purpose and conditions. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema), the description covers all essential aspects: when to use, what to write, behavior on existing passport, and overwrite option. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Beyond schema descriptions, the description adds critical guidance: what to write in the summary (codebase purpose, tech stack, modules, etc.) and a token range (200-350). This significantly helps the agent craft the correct input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: saving a synthesized codebase summary as a permanent passport. It distinguishes this from siblings by specifying it should be called only after vectr_map returns raw metadata, not when a saved summary already exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit usage conditions: 'Call this ONLY after vectr_map returned raw metadata — i.e. on your first visit to a codebase. NOT when vectr_map already returned a saved summary.' Also explains no-op behavior and the overwrite parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_pinA
Idempotent

Pin a note so it is injected on EVERY future vectr_recall(query=...) call, regardless of the query — never relevance-scored, never dropped for being off-topic. Use for a note that must never be missed by an unlucky query (the same standing-rule role kind='directive' already plays, but for a note you don't want to reclassify as a directive). Pass pinned=false to unpin. Bounded: only a small configured number of directive+pinned notes ever occupy this unconditional tier, so pin sparingly. Equivalent to passing pin=true directly to vectr_remember at write time.

ParametersJSON Schema
NameRequiredDescriptionDefault
pinnedNotrue to pin (default), false to unpin
note_idYesID of the note to pin/unpin (the [#N] id from vectr_recall)

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses non-obvious behavior beyond annotations: unconditional injection, no relevance scoring, never dropped for being off-topic, and a bounded number of directive+pinned notes allowed in this tier. It also makes clear that unpinning is possible via pinned=false. No contradiction with annotations is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and well-structured, with the primary effect front-loaded. Each sentence contributes a distinct aspect: effect, use case, unpin method, resource bound, and equivalence with write-time pinning. It is slightly verbose but not redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter operation with no output schema, the description fully explains when to use it, what it does, and how to undo it. It also covers the resource-administration bound and equivalent alternative, leaving no practical gap for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents note_id and pinned. The description's only added hint is 'Pass pinned=false to unpin,' which essentially restates the schema. Therefore, the description adds no significant value beyond the input schema, yielding the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Pin a note' so it is 'injected on EVERY future vectr_recall(query=...) call'. It further distinguishes itself from the standing-rule directive role and from vectr_remember by explaining that this is for notes you don't want to reclassify.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use this tool: for a note that must never be missed by an unlucky query, and contrasts it with the kind='directive' role. It also names an alternative/equivalent approach: passing pin=true to vectr_remember at write time. The 'pin sparingly' caveat additionally guides usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_promoteA
Idempotent

Raise an auto-captured note's trust class to 'agent' — e.g. after this session has reviewed an auto-captured note and confirmed it still holds. This tool only takes that one step (auto -> agent); it never promotes a note to 'human', because deciding that a person has endorsed something is not the agent's call to make. Human endorsement happens on a user-side surface instead (a CLI/UI a person operates), not through this tool.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesTarget provenance. Only 'agent' is available via this tool (auto -> agent); promoting to 'human' is a user-side action, not available here.
note_idYesID of the note to promote (the [#N] id from vectr_recall)

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds behavioral context beyond annotations: affirms only auto->agent transition, explains why human promotion is unavailable, and implies idempotency. Annotations already provide idempotentHint=true, so no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Fully explains scope, constraints, and rationale for a simple tool. No output schema needed; return behavior is not complex.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and parameter descriptions exist. The description reinforces the 'to' parameter's constraint and rationale, adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the action of promoting a note's trust class to 'agent', specifies the resource (auto-captured note), and distinguishes from other tools by noting it never promotes to human.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (after reviewing and confirming a note) and when not to use (never to human), with reference to alternative user-side action for human endorsement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_recallA
Read-onlyIdempotent

Retrieve notes stored earlier in this session or in prior sessions. TWO-TIER RECALL (UPG-RECALL-HIERARCHY): By default returns a crisp one-line index per note (id + kind/priority + title + age) — token-bounded, safe to call broadly. To read a note body: pass note_id=N (expand one note, full body) or detail='full' (all bodies). Use when vectr_status() confirmed notes_count > 0 — notes may have been stored this session or in a previous one; either way they are immediately useful. Pass a targeted query to retrieve only the notes relevant to your current task — do NOT call with no query unless you need everything.

ParametersJSON Schema
NameRequiredDescriptionDefault
bootNoBoot mode: return ALL directives + high-priority task notes unconditionally (no semantic filter, safe on a fresh workspace). Ignores query/tags/priority/kind/limit.
kindNoFilter to one memory kind: 'directive' | 'task' | 'gotcha' | 'finding' | 'reference' | 'decision' | 'operational'
tagsNoFilter by tags
limitNoMax notes to return (default: 10)
queryNoNatural language query to retrieve only relevant notes (e.g. 'set cartesian product frozenset' returns notes about that task only). Omit only when you need all stored notes.
detailNoDetail level: 'index' (default) = one-line summary per note (id, kind/priority, title, age) — token-bounded; 'full' = full note bodies (use when you need to read all matching notes).index
note_idNoExpand a single note by ID — returns the full body of that note, ignoring query. Use after seeing the index output to read the note you care about. Get IDs from the [#N] prefix in index output.
sort_byNoSort order: 'relevance' (semantic/trust order, default), 'recency' (newest first), 'priority' (high→medium→low then newest), 'chronological' (oldest first — index lines show the creation date instead of a relative age; combine with kind="decision" for an ADR-style decision timeline, or with any other kind/tag filter for the same time-ordered view).relevance
priorityNoFilter by priority: 'high' | 'medium' | 'low'
max_age_daysNoTime filter: only return notes created within this many days.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly and idempotent annotations, the description details the two-tier recall, token-bounded index, sorting behaviors, boot mode, and note expansion. This adds significant behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense yet highly efficient, front-loading the core purpose and then efficiently covering the two-tier recall, usage guidance, and key parameter hints without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (10 parameters, no output schema), the description fully explains the return format, recall hierarchy, filtering options, and usage context, leaving no significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the baseline is 3. The description adds extra context for several parameters (e.g., query example, note_id ID source, sort_by chronological behavior), warranting a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves notes from current or prior sessions, with a specific two-tier recall hierarchy (index vs full body). It uses specific verbs and resources, and the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises when to use the tool (after confirming notes exist via vectr_status) and when not to (calling without query unless needed). It provides clear context but does not explicitly compare to sibling tools, slightly reducing the score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_reinstateA
Idempotent

Reverse a prior vectr_revoke (or a contradicts= write) — the note returns to active state and its original content, not the deterrent block, is shown again.

ParametersJSON Schema
NameRequiredDescriptionDefault
reasonNoOptional: why this note is being reinstated.
note_idYesID of the revoked note to reinstate (the [#N] id from vectr_recall)

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that original content is restored, which is useful but does not go beyond the safe profile established by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the main action. However, the unclear phrase 'or a contradicts= write' slightly reduces clarity and conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks information about return values and error conditions. Given no output schema and the tool modifying state, this omission leaves the agent without needed context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with both parameters documented. The tool description does not add additional meaning beyond what the schema provides, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Reverse a prior vectr_revoke' and explains that the note returns to active state with original content. This clearly distinguishes it from sibling tools like vectr_revoke and vectr_forget.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells when to use: to reverse a prior revoke. However, it does not explicitly state prerequisites (e.g., note must be revoked) or alternatives, though the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_rememberA

Save a working note and recall it on demand in <50ms — whether later this session, through context compaction, or in a future session. Use the moment you discover something non-obvious: a key file path, a call pattern, a gotcha, a partial stub, task progress. Store the actual code or finding — vectr returns it in <50ms; re-reading the file costs tokens and turns. Do NOT store obvious or easily re-derivable facts (e.g. 'the main file is main.py'). For a body over ~2KB, especially code-heavy with quotes/escapes, write it to a file and pass content_file instead of content — long escape-dense strings can be corrupted mid-stream as a tool-call argument. Retrieve with vectr_recall(query='what you need') — any time, same session or later.

ParametersJSON Schema
NameRequiredDescriptionDefault
pinNoOptional: pin this note into Tier 0 at write time — injected on EVERY future vectr_recall(query=...) call regardless of the query, same effect as a separate vectr_pin call right after this write. Bounded, so pin sparingly. Default false.
kindNoMemory kind, controlling how the note is injected (default 'finding'): 'directive' = a must-never-miss rule, injected unconditionally every session; 'task' = current-work context (save checkpoints with priority="high" — session-start/resume surfaces show only high-priority task notes); 'gotcha' = a file/path-anchored caveat; 'finding' = a relevance-ranked learning; 'reference' = a pointer (URL/ticket); 'decision' = an architectural/design decision plus its why — not auto-injected, recall the group chronologically with vectr_recall(kind="decision", sort_by="chronological") for an ADR-style decision history; 'operational' = a build/env/process fact (a build quirk, a CI gotcha, feedback-loop knowledge — e.g. 'tests must run via ./.venv/bin/python'), not anchored to a single code file the way 'gotcha' is. By default surfaces via prompt-time semantic recall (equivalent to declaring triggers=[{'event': 'prompt-submit', 'semantic': True}]). An explicit triggers=[...] REPLACES that default rather than adding to it — declaring triggers=[{'command': '<verb-glob>'}] alone means the note fires ONLY right before a matching shell command and stops firing on prompt-submit. To keep both surfaces, declare both entries: triggers=[{'event': 'prompt-submit', 'semantic': True}, {'command': '<verb-glob>'}]. When a new kind='task' note replaces an earlier checkpoint (the work moved on, the old note is no longer the current state), pass supersedes=<old note_id> so the stale checkpoint stops firing at every future session-start instead of piling up alongside the new one.finding
tagsNoTopic tags for later recall (e.g. ['segment-targeting', 'wip'])
agentNoOptional: your identifier when called by a subagent or orchestrator in a multi-agent workflow (e.g. 'coder-2'). Never inferred — set it explicitly if you want attribution. Shown in vectr_recall() index output as a tag, e.g. '[#12] task/high (coder-2) · title'. A subagent should call vectr_remember with its findings BEFORE finishing so the orchestrator can recall them instead of re-reading the subagent's full transcript.
scopeNoAdvanced: visibility scope, enforced at recall/trigger time. Omit for the kind's own default ('task'→'branch', 'gotcha'→'repo', else 'workspace'); pass explicitly to override — 'branch' (git branch at write time), 'path-subtree' (paths under an anchored dir), 'session' (writing session only), 'repo' (same as 'workspace' today).
titleNoShort label for index-tier display (optional, max ~80 chars). If omitted, the first non-empty line of content is used as the title. Shown in vectr_recall() index output so you can identify notes without reading their bodies.
anchorsNoOptional: file paths this note is about, content-hashed at write time so a later change surfaces as a staleness caveat instead of silently going stale.
contentNoThe note to store. Store whatever you would need to avoid re-reading the file later. If you found a function you'll call or modify — paste its signature and body. If you found a pattern you'll need to replicate — paste the pattern. If you found a location — include the file:line AND the relevant excerpt, not just the pointer. Prose descriptions send the next conversation back to the file; actual code does not. Mutually exclusive with content_file (see below); pass exactly one.
priorityNoNote priority: 'high' | 'medium' (default) | 'low'. Session-start boot injection and the resume surface show only priority='high' kind='task' notes, so a checkpoint you want picked up at resume needs priority='high'.medium
triggersNoAdvanced: explicit overrides for WHEN this note resurfaces (path glob, event, symbol, semantic-similarity, timing/cooldown fields — AND within an entry, OR across entries; see docs for the full field DSL). Omit this entirely (recommended) — each kind already gets a sensible default, e.g. 'directive' fires at session-start and after compaction, 'gotcha' fires when its anchored file is about to be edited.
provenanceNoHow much to trust this note when it resurfaces (default 'agent'): 'agent' = self-recorded, framed as memory to verify; 'auto' = no reviewing judgment, weakest framing, incompatible with kind='directive'. 'human' is only reached via explicit promotion, not settable here.agent
supersedesNoOptional: the note_id this new note replaces — the old note is retired (excluded from recall/firing) but kept for audit, unlike vectr_forget. Especially important for kind='task': pass the prior checkpoint's id so it stops firing at every session-start once superseded.
user_quoteNoOptional: when this note transcribes something the USER said, the user's own words, verbatim. Bound only if that exact text also appears inside `content` (whitespace-insensitive substring check); a bound quote stores the note as provenance='user-stated' so it resurfaces as the user's statement rather than your own recollection. Paraphrase, or words the user did not actually write, will not bind — the note is stored as an ordinary 'agent' note and the reason is returned. Never fails the write.
contradictsNoOptional: the note_id this new note proves WRONG — distinct from supersedes (a normal replacement). The target note is revoked: it stays visible on every future recall/fire but rendered as a deterrent ('previously believed... do not re-derive without verification') instead of its raw content, until vectr_reinstate reverses it.
content_fileNoPath to a UTF-8 file containing the note body — use instead of content for a body over ~2KB, especially code-heavy with quotes/escapes, so it never has to stream as a long JSON string argument. Absolute, or relative to the workspace root; rejected if it resolves outside the workspace. Mutually exclusive with content; pass exactly one.
distilled_fromNoOptional: arc ids (from vectr_distill() or GET /v1/arcs) this note distills. After this note is stored, each named arc is marked distilled into it. Unknown/already-resolved ids, and any entry that is not itself an integer, are reported back in the confirmation, never an error and never silently dropped.

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds meaningful behavioral context beyond annotations: persistence across context compaction and future sessions, <50ms retrieval performance, the token/turn cost of re-reading files, and a concrete corruption risk for long escape-dense strings passed as tool-call arguments. The content_file guidance further exposes an important operational behavior. No contradiction with readOnlyHint=false or destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded, with the core purpose in the first sentence and concrete usage guidance immediately after. It is long, and the '<50ms' point is repeated somewhat redundantly, but most sentences earn their place by giving actionable guidance or rationale.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with no output schema and 16 parameters, the description covers the common path well: what to store, what not to store, how to handle large code-heavy bodies, and how to retrieve later. Advanced fields are delegated to the schema's rich parameter descriptions, which is acceptable; the only notable omission is describing what the tool returns (e.g. the new note_id), which would help with supersedes/contradicts chaining.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds genuine parameter-level guidance for content vs content_file, including the ~2KB threshold and mutual exclusivity, and connects content quality to future recall value. It does not systematically cover all 16 parameters, but the schema already documents those thoroughly and the description adds value where it matters most.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('Save a working note and recall it on demand'), names the resource (vectr memory), and explicitly names the retrieval counterpart vectr_recall. It is clearly distinguishable from the read-side sibling and is not tautological or vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use triggers: 'Use the moment you discover something non-obvious' with examples (file path, call pattern, gotcha, stub, progress), and explicitly says what NOT to store ('Do NOT store obvious or easily re-derivable facts'). It does not enumerate exclusions against related write tools such as vectr_pin or vectr_forget, but the timing and anti-pattern advice is strong enough to guide tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_resumeA
Read-onlyIdempotent

One-call 'pick up where you left off': the most recent current-task note, the latest saved snapshot, and any open gotchas with their file anchors. Call at the start of a session or after a gap to reorient without re-reading files or re-deriving state vectr_recall would otherwise need several calls to assemble.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. The description adds detail on what is returned (note, snapshot, gotchas with anchors), providing additional transparency without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded purpose, no filler. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and straightforward behavior, the description fully covers purpose, usage, and output. Nothing missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No input parameters, so the baseline is high (4). The description explains the tool's output and purpose, making up for the lack of param details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the tool as a one-call reorientation mechanism returning specific artifacts (current-task note, snapshot, gotchas). It uses a specific verb ('resume') and distinguishes from siblings like vectr_recall.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to call: 'at the start of a session or after a gap'. Also explains the benefit (avoid re-reading files) and contrasts with alternative vectr_recall.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_revokeA
Idempotent

Flag a stored note as WRONG without deleting it — use when you've confirmed a prior finding no longer holds (contradicted by newer evidence, or you got it wrong the first time). Unlike vectr_forget, the note is not erased: it stays visible on future vectr_recall/session-start as a deterrent — 'previously believed..., revoked..., do not re-derive this without verification' — instead of its original content, so nothing silently repeats the mistake. Reversible with vectr_reinstate. Prefer passing contradicts= directly to vectr_remember when you're recording the correction anyway; use this tool when you need to revoke without writing a replacement note.

ParametersJSON Schema
NameRequiredDescriptionDefault
reasonYesWhy this note is being revoked (shown verbatim in the deterrent framing).
note_idYesID of the note to revoke (the [#N] id from vectr_recall)

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations show destructiveHint=false and idempotentHint=true; description adds crucial behavioral context: note stays visible with deterrent framing, content replaced, reversible. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is front-loaded with purpose, then usage guidance, then alternatives. Every sentence earns its place; no fluff. Efficiently structured for agent comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, description fully explains behavioral effects (deterrent display, content change), reversibility, and how it differs from siblings. Complete and self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are already well-described in the schema (reason shown verbatim, note_id from recall). The description does not add new information beyond what the schema provides, so baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool flags a note as WRONG without deleting it, distinguishing it from vectr_forget (erases) and vectr_remember (prefer when writing correction). Verb and resource are explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says use when 'you've confirmed a prior finding no longer holds' and advises preferring vectr_remember when recording a correction. Also mentions reversibility with vectr_reinstate, providing clear when-to-use and when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_snapshotA

Seal all current vectr_remember() notes as a named checkpoint. Use when you've stored multiple notes and want to mark a milestone you can return to (e.g. 'auth-refactor-wip', 'segment-targeting-done'). The next time you work on this, vectr_recall will return these notes. NOT required if you only stored 1-2 notes — vectr_recall retrieves all notes regardless.

ParametersJSON Schema
NameRequiredDescriptionDefault
labelYesHuman-readable label for this snapshot (e.g. 'segment-targeting-wip')
session_idNoOptional session identifier

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that it creates a named checkpoint and that vectr_recall will return those notes later, but could mention if it overwrites existing snapshots or has other side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus an exception note, front-loaded with the action, and every sentence adds necessary context without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage, and relation to vectr_recall well; lacks detail on multiple snapshots or behavior of calling again, but adequate for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds value by explaining the label parameter's role and providing examples, while the schema already covers both parameters fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the tool's action (sealing notes as a named checkpoint) and distinguishes it from sibling tools like vectr_recall by explaining that vectr_recall retrieves all notes regardless of snapshots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use (when storing multiple notes for a milestone) and when not to use (if only 1-2 notes, vectr_recall suffices), with specific label examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_snapshot_listA
Read-onlyIdempotent

List all saved session snapshots for this workspace, newest first. Use at session start to find an existing checkpoint if vectr_recall returned nothing or if you want to resume a specific named session.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds ordering ('newest first') which is extra behavioral info beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose, second gives usage context. No redundancy, front-loaded with key action. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and rich annotations, the description is complete. It covers purpose, usage timing, and ordering. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters (0 params), schema coverage 100%. Baseline is 4 per instructions. Description correctly implies no input needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'list', resource 'saved session snapshots', scope 'for this workspace', and ordering 'newest first'. It distinguishes from siblings like vectr_snapshot (create) and vectr_resume (restore) by specifying usage context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use: 'at session start to find an existing checkpoint if vectr_recall returned nothing or if you want to resume a specific named session'. Provides clear conditions and reference to alternative tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_statusA
Read-onlyIdempotent

Returns index health (files, chunks, embed model) AND notes_count (number of notes stored — earlier in this session or in prior sessions). Call once at the start of any session to decide whether vectr_recall is worth calling: if notes_count > 0, call vectr_recall(query=...) to retrieve relevant notes. If notes_count == 0, skip recall entirely. If your session already shows auto-injected Working Notes (vectr hooks), those ARE the recall output — do not re-call vectr_recall for them. Also useful when vectr_search returns nothing and you suspect indexing is still running.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly and idempotent hints. Description adds decision-making context and clarifies return field semantics, enhancing transparency beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single paragraph, front-loaded with what it returns, then usage guidance. Every sentence provides value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, description fully explains return values and how to use them in context. Agent can determine when and how to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; schema coverage 100%. Description doesn't need to add parameter info. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it returns index health and notes_count. Specific verb 'Returns' and resource 'index health, notes_count'. Distinguishes from siblings by being the status/decision tool for vectr_recall.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (start of session), provides conditional logic (notes_count > 0 vs == 0), warns against re-calling for auto-injected notes, and mentions utility when vectr_search returns nothing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_supersedeA
Idempotent

Retire an ALREADY-STORED note as superseded, when you discover only AFTER writing its replacement that supersedes= was not passed on that write. The retired note stops appearing in default recall/session-start and renders with a factual '[superseded ...]' badge — it is NOT marked wrong and never shows the revoked deterrent (it was accurate when written; the world moved on). Use vectr_revoke instead when the note is actually FALSE. Pass superseded_by= to link the replacement if one exists; omit it to retire with no successor. Reversible with vectr_reinstate.

ParametersJSON Schema
NameRequiredDescriptionDefault
reasonNoOptional: why this note is being retired as superseded.
note_idYesID of the note to retire (the [#N] id from vectr_recall)
superseded_byNoOptional: ID of the replacement note that already exists (the write that should have carried supersedes=<this note>).

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the annotations by explaining the observable effects: the note stops appearing in default recall/session-start, renders a '[superseded ...]' badge, is not marked wrong, never shows the revoked deterrent, and is reversible. This gives the agent a clear model of what the operation does and does not do.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but economical: it fronts the core scenario, then explains behavioral consequences, contrasts with vectr_revoke, and closes with parameter guidance and reversibility. Every sentence contributes distinct information with no repetition of the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter, non-destructive state-transition tool with rich annotations and a fully documented schema, the description supplies everything needed to invoke it correctly: the triggering condition, the exact note to mutate, the optional link to the replacement, the post-condition behavior, and the alternative tool in case of actual falsity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers 100% of parameters with descriptions, establishing a baseline of 3. The description adds meaningful usage semantics—particularly that superseded_by links the replacement that should have carried supersedes=<old id> and that omitting it means retiring with no successor—which clarifies intent beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action—retire an already-stored note as superseded after a missed supersedes parameter—and clearly distinguishes it from vectr_revoke, whose purpose is for actually false notes. The description also ties to the tool's title phrase 'post-hoc' and names the note-identification convention from vectr_recall.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent when to use this tool (after writing a replacement without supersedes), when not to use it (use vectr_revoke when the note is actually false), and how to handle the superseded_by parameter, including omitting it when there is no successor. It also notes reversibility with vectr_reinstate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_traceA
Read-onlyIdempotent

Use when you know the SYMBOL NAME and need to understand its callers or callees before modifying it. Traverses the call graph in both directions. NOT when you don't know the symbol name yet — use vectr_search or vectr_locate first. NOT when you just want the definition location — use vectr_locate instead. Example: vectr_trace(name='EvaluateSegments') → 'Called by: RequestBid() in bidder/auction.go'

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesSymbol name to trace
limitNoMax results per direction (default: 20)
directionNo'callers' (who calls this), 'callees' (what it calls), or 'both' (default)both
include_builtinsNoInclude language builtins/stdlib in the 'calls' list (len, assert, Ok, Some, malloc, …). Default false — only repo-internal calls are shown, with a count of how many builtins were hidden.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond the annotations by explaining that the tool traverses the call graph in both directions and showing an example output format. While the annotations already indicate it is read-only and idempotent, the description adds the behavioral detail of bidirectional traversal. A small gap is that it does not explicitly state that results are textual, but the example compensates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it opens with the primary usage condition, then describes the action, followed by two 'NOT' conditions with alternatives, and ends with an example. Every sentence adds value, and the critical information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is quite complete given the tool's complexity, the presence of annotations, and full schema coverage. It covers purpose, when to use/not use, and provides an example. However, it lacks an explicit statement that the output is a textual listing, though this is implied by the example. Overall, it provides sufficient context for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 4 parameters with 100% description coverage, so the baseline is 3. The description does not add significant new information about parameters beyond what is in the schema, except for illustrating the 'name' parameter in the example. The schema already provides defaults, enums, and descriptions for 'limit', 'direction', and 'include_builtins', so the description is adequate but not exceptional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: traversing the call graph for a known symbol name to understand its callers or callees before modification. It uses specific language ('traverses the call graph') and provides an example. It also explicitly distinguishes from siblings by stating when not to use it and which alternative tools to use instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use the tool ('know the SYMBOL NAME and need to understand its callers or callees before modifying it') and when not to use it ('when you don't know the symbol name yet — use vectr_search or vectr_locate first' and 'when you just want the definition location — use vectr_locate instead'). This gives clear decision criteria for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vectr_unanchorA
Idempotent

Remove file paths from an EXISTING note's anchor set (UPG-ANCHOR-DETACH). The inverse of vectr_anchor: use it when you discover a note was anchored to the wrong file, or when the anchored file's relevance has gone away. A removed anchor simply stops being a candidate in the next staleness check — never a claim that the note is wrong. Idempotent — paths the note was never anchored to are reported back, not treated as failures. Path comparison is exact-string on the spelling the note was anchored with, matching vectr_anchor's contract.

ParametersJSON Schema
NameRequiredDescriptionDefault
anchorsYesWorkspace-relative file paths to detach this note from (at least one)
note_idYesID of the note to remove anchors from (the [#N] id from vectr_recall)

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the idempotentHint annotation, the description explains exactly what idempotency means here: never-anchored paths are reported back, not treated as failures. It also discloses the exact-string comparison contract and the effect on staleness checks, adding substantial behavioral detail beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: core action, inverse relationship, use cases, idempotency semantics, and comparison behavior. The most identifying information is front-loaded, and the phrasing is dense without being bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation tool with no output schema, the description covers all operational aspects an agent needs: what it does, when to use it, what to expect from idempotency, and how path matching works. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: anchors are workspace-relative paths, comparison is exact-string on the spelling used at anchor time, and note_id refers to an existing note from vectr_recall. This extra context helps the agent construct correct arguments without opening the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Remove'), a specific resource (file paths from an existing note's anchor set), and identifies the operation codename (UPG-ANCHOR-DETACH). It explicitly positions itself as the inverse of vectr_anchor, making sibling differentiation immediate and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete when-to-use conditions: discovering a note was anchored to the wrong file, or when the anchored file's relevance has gone away. It also clarifies what the operation does not mean (never a claim the note is wrong), which prevents misuse in unrelated correction scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.12.0
    • Addedvectr_unanchor
  2. 3 tool updatesv1.10.1
    • Addedvectr_anchor
    • Changedvectr_remember2 fields changed
      • changedInput schema / properties / kind / description
        Previous value: -"Memory kind, controlling how the note is injected (default 'finding'): 'directive' = a must-never-miss rule, injected unconditionally every session; 'task' = current-work context; 'gotcha' = a file/path-anchored caveat; 'finding' = a relevance-ranked learning; 'reference' = a pointer (URL/ticket); 'decision' = an architectural/design decision plus its why — not auto-injected, recall the group chronologically with vectr_recall(kind=\"decision\", sort_by=\"chronological\") for an ADR-style decision history; 'operational' = a build/env/process fact (a build quirk, a CI gotcha, feedback-loop knowledge — e.g. 'tests must run via ./.venv/bin/python'), not anchored to a single code file the way 'gotcha' is. By default surfaces via prompt-time semantic recall (equivalent to declaring triggers=[{'event': 'prompt-submit', 'semantic': True}]). An explicit triggers=[...] REPLACES that default rather than adding to it — declaring triggers=[{'command': '<verb-glob>'}] alone means the note fires ONLY right before a matching shell command and stops firing on prompt-submit. To keep both surfaces, declare both entries: triggers=[{'event': 'prompt-submit', 'semantic': True}, {'command': '<verb-glob>'}]. When a new kind='task' note replaces an earlier checkpoint (the work moved on, the old note is no longer the current state), pass supersedes=<old note_id> so the stale checkpoint stops firing at every future session-start instead of piling up alongside the new one."New value: +"Memory kind, controlling how the note is injected (default 'finding'): 'directive' = a must-never-miss rule, injected unconditionally every session; 'task' = current-work context (save checkpoints with priority=\"high\" — session-start/resume surfaces show only high-priority task notes); 'gotcha' = a file/path-anchored caveat; 'finding' = a relevance-ranked learning; 'reference' = a pointer (URL/ticket); 'decision' = an architectural/design decision plus its why — not auto-injected, recall the group chronologically with vectr_recall(kind=\"decision\", sort_by=\"chronological\") for an ADR-style decision history; 'operational' = a build/env/process fact (a build quirk, a CI gotcha, feedback-loop knowledge — e.g. 'tests must run via ./.venv/bin/python'), not anchored to a single code file the way 'gotcha' is. By default surfaces via prompt-time semantic recall (equivalent to declaring triggers=[{'event': 'prompt-submit', 'semantic': True}]). An explicit triggers=[...] REPLACES that default rather than adding to it — declaring triggers=[{'command': '<verb-glob>'}] alone means the note fires ONLY right before a matching shell command and stops firing on prompt-submit. To keep both surfaces, declare both entries: triggers=[{'event': 'prompt-submit', 'semantic': True}, {'command': '<verb-glob>'}]. When a new kind='task' note replaces an earlier checkpoint (the work moved on, the old note is no longer the current state), pass supersedes=<old note_id> so the stale checkpoint stops firing at every future session-start instead of piling up alongside the new one."
      • changedInput schema / properties / priority / description
        Previous value: -"Note priority: 'high' | 'medium' (default) | 'low'"New value: +"Note priority: 'high' | 'medium' (default) | 'low'. Session-start boot injection and the resume surface show only priority='high' kind='task' notes, so a checkpoint you want picked up at resume needs priority='high'."
    • Addedvectr_supersede
  3. 2 tool updatesv1.10.0
    • Addedvectr_pin
    • Changedvectr_remember5 fields changed
      • changedInput schema / properties / content / description
        Previous value: -"The note to store. Store whatever you would need to avoid re-reading the file later. If you found a function you'll call or modify — paste its signature and body. If you found a pattern you'll need to replicate — paste the pattern. If you found a location — include the file:line AND the relevant excerpt, not just the pointer. Prose descriptions send the next conversation back to the file; actual code does not."New value: +"The note to store. Store whatever you would need to avoid re-reading the file later. If you found a function you'll call or modify — paste its signature and body. If you found a pattern you'll need to replicate — paste the pattern. If you found a location — include the file:line AND the relevant excerpt, not just the pointer. Prose descriptions send the next conversation back to the file; actual code does not. Mutually exclusive with content_file (see below); pass exactly one."
      • addedInput schema / properties / content_file
        Added value: +{
+  "description": "Path to a UTF-8 file containing the note body — use instead of content for a body over ~2KB, especially code-heavy with quotes/escapes, so it never has to stream as a long JSON string argument. Absolute, or relative to the workspace root; rejected if it resolves outside the workspace. Mutually exclusive with content; pass exactly one.",
+  "type": "string"
+}
      • addedInput schema / properties / pin
        Added value: +{
+  "default": false,
+  "description": "Optional: pin this note into Tier 0 at write time — injected on EVERY future vectr_recall(query=...) call regardless of the query, same effect as a separate vectr_pin call right after this write. Bounded, so pin sparingly. Default false.",
+  "type": "boolean"
+}
      • addedInput schema / properties / user_quote
        Added value: +{
+  "description": "Optional: when this note transcribes something the USER said, the user's own words, verbatim. Bound only if that exact text also appears inside `content` (whitespace-insensitive substring check); a bound quote stores the note as provenance='user-stated' so it resurfaces as the user's statement rather than your own recollection. Paraphrase, or words the user did not actually write, will not bind — the note is stored as an ordinary 'agent' note and the reason is returned. Never fails the write.",
+  "type": "string"
+}
      • changedInput schema / required
        Previous value: -[
-  "content"
-]New value: +[]
  4. 18 tool updatesv1.7.0
    • Addedvectr_distill
    • Addedvectr_evict_hint
    • Addedvectr_fetch
    • Addedvectr_forget
    • Addedvectr_ingest_traces
    • Addedvectr_locate
    • Addedvectr_map
    • Addedvectr_map_save
    • Addedvectr_promote
    • Addedvectr_recall
    • Addedvectr_reinstate
    • Addedvectr_remember
    • Addedvectr_resume
    • Addedvectr_revoke
    • Addedvectr_snapshot
    • Addedvectr_snapshot_list
    • Addedvectr_status
    • Addedvectr_trace
  5. 2 tool updatesv1.4.0
    • Removedvectr_map_save
    • Addedvectr_search
  6. 1 tool updatev1.3.0
    • Removedvectr_forget
  7. 12 tool updatesv1.3.0
    • Removedvectr_evict_hint
    • Removedvectr_fetch
    • Removedvectr_ingest_traces
    • Removedvectr_locate
    • Removedvectr_map
    • Removedvectr_recall
    • Removedvectr_remember
    • Removedvectr_search
    • Removedvectr_snapshot
    • Removedvectr_snapshot_list
    • Removedvectr_status
    • Removedvectr_trace
  8. 14 tool updatesv1.2.0
    • First observedvectr_evict_hint
    • First observedvectr_fetch
    • First observedvectr_forget
    • First observedvectr_ingest_traces
    • First observedvectr_locate
    • First observedvectr_map
    • First observedvectr_map_save
    • First observedvectr_recall
    • First observedvectr_remember
    • First observedvectr_search
    • First observedvectr_snapshot
    • First observedvectr_snapshot_list
    • First observedvectr_status
    • First observedvectr_trace
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with detailed explanations that prevent overlap. For example, vectr_search (concept search), vectr_locate (symbol location), and vectr_trace (call graph) are distinct. No two tools can be confused.

Naming Consistency5/5

All tool names follow the consistent pattern 'vectr_' + imperative verb (e.g., vectr_fetch, vectr_search, vectr_locate, vectr_trace, vectr_remember). No mixing of conventions; the naming is predictable and uniform.

Tool Count4/5

With 19 tools, the set is comprehensive but slightly on the heavy side. However, each tool serves a specific and necessary function in code intelligence and note management, so the count is justified for the scope.

Completeness5/5

The tool set covers the full lifecycle of code understanding and memory management: indexing, semantic/symbol/trace search, content retrieval, note capture/recall, snapshot management, error correction, and even runtime trace ingestion. No obvious gaps are present.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/swapnanil/vectr'

If you have feedback or need assistance with the MCP directory API, please join our Discord server