vectr_remember
Save key code findings, file paths, gotchas, and task progress, then recall them in under 50ms—even after context compaction or in a new session. Avoid re-reading files and losing context.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pin | No | 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. | |
| kind | No | 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. | finding |
| tags | No | Topic tags for later recall (e.g. ['segment-targeting', 'wip']) | |
| agent | No | Optional: 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. | |
| scope | No | Advanced: 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). | |
| title | No | Short 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. | |
| anchors | No | Optional: 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. | |
| content | No | 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. | |
| priority | No | 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'. | medium |
| triggers | No | Advanced: 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. | |
| provenance | No | How 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 |
| supersedes | No | Optional: 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_quote | No | 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. | |
| contradicts | No | Optional: 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_file | No | 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. | |
| distilled_from | No | Optional: 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. |