Use when you know WHAT you're looking for but not WHERE it is or WHAT it's called. Hybrid semantic + BM25 search — finds code by concept, behaviour, or description. Returns function/class bodies with file paths and line numbers. NOT when you already know the symbol name — use vectr_locate instead. NOT when you want call relationships — use vectr_trace instead.

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.

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.

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.

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.

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'

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'

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'). Retrieve with vectr_recall(query='what you need') — any time, same session or later.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.