vestige-record-note

Record a project note

Capture useful project knowledge that doesn't fit a more specific type. Notes are the catch-all bucket — lower-signal than decisions, but still worth keeping. Aha moments, TILs, gotchas, code smells, and durable TODOs all live here.

When to fire

• You discovered a non-obvious thing about the codebase ("cargo test --workspace triggers FTS triggers in tmpdir-shaped tests").
• You found a workaround for a tool quirk.
• You hit an "aha" — surprising behaviour, broken assumption, root cause after debugging.
• You're flagging a code smell or refactor candidate that should outlive this session.
• The user said "jot this down" / "note that" / "worth recording" without naming it a decision.

Tie-breakers vs siblings:

• Note vs decision — does it carry a commitment with a why? If yes, vestige-record-decision.
• Note vs preference — is it a user opinion / convention? If yes, vestige-record-preference.
• Note vs question — is the answer known? If no, vestige-record-question.

How to invoke

vestige note add "<the fact, in one or two sentences>" \
  --importance 0.5 \
  --json

• body (positional, required): the fact itself, written so it stands alone — assume future-you reads it cold.
• --importance (optional, default 0.5): drop to 0.3 for trivia; raise to 0.6 for code smells / root causes worth keeping in front of the agent; 0.7 only if losing this would actually hurt.
• --source (optional): when the note came from a specific file/PR/URL, attach it.
• --source-content (optional): inline snippet, capped at 2 KiB by the CLI.

After invocation

The JSON envelope returns { "id": "mem_<ULID>", ... }. Surface a one-liner: "Noted mem_…." No need to read the body back.

Idempotence & dedup

Every call is a fresh write. Before capturing a note that feels familiar, dedup with:

vestige recall "<key phrase>" --json --limit 3

Skip the write if the top hit is the same fact at a comparable importance. If you're capturing because something changed, capture the new note and vestige-forget the stale one — don't leave both active.

Don't note conversational acknowledgements, things already in code (a comment serves better), or anything that's actually a decision/preference/question in disguise.