Write memory notes in OPVS form

Updated 3 min read
View as Markdown
On this page

Who this is for: agent builders who keep long-term notes for an agent (decisions, lessons, preferences) and want them short.

What this does: turns a note into two lines that any OPVS parser can read: a routing line that says what kind of note it is and what it is about, and one line with the point.

Before you begin

  • A place where the agent keeps its notes, such as a MEMORY.md file.

  • An idea of the topics the agent's notes are about.

Steps

  1. Address the note to the agent itself. Use a short name for the person or system the note is about, and send it to itself: @M>M for a note about Martin, @sys>sys for a system note. Names follow the address rules: ASCII letters, digits, _ and -.

  2. Say what kind of note it is with a tag. Use one of a small set and keep to it:

    Tag

    Kind of note

    #dec

    a decision

    #lrn

    a lesson learned

    #pat

    a pattern

    #prf

    a preference

    #fct

    a fact

    #sum

    a summary

  3. Add topics, and what the note is not about. More tags for topics (#api, #deploy), and /#tag to rule something out.

  4. Link it. <-ref names the cause (an incident, an earlier note). != ref says this note replaces an older one. See Relationship marks.

  5. Add values on the routing line. Inline values keep the note on two lines. For example $f:0.95 for how sure the agent is, and $t:2026-01 for when.

  6. Write the point on line 2. One line, plain words, the part that matters: the reason for a decision, the fix for a lesson.

    @M>M . #dec #api $f:0.95 $t:2026-01
REST over GraphQL for the partner API: agents read YAML, no extra translation layer.
    @sys>sys . #lrn #deploy +fix <-incident-215 $f:0.95 $t:2026-02
Deploy the code before running the migration, or old code crashes on new columns.
    @M>M . #prf #reports != m_4f1 $t:2026-03
Weekly reports go out on Monday morning, not Friday.

Verify it worked

Parse a note with either library (see Parser libraries). You get the kind tag and topics in tags, the values in context, the cause in caused_by, the replaced note in contradicts, and the point in body. If from_agent is empty, the address line is wrong.

Troubleshoot

  • The parser returns no sender? Check the first token: @name>name with no spaces, and names that start with a letter or digit.

  • A value came back as a number when I wanted text? 2026 becomes a number; 2026-01 stays text. Write dates with a -, and keep ids with leading zeros as they are (007 stays text).

  • The note lost detail? Two lines are short on purpose. Shortening a note can leave out something that mattered later, such as how long an outage lasted. Keep that detail in line 2, or in a longer note.

Protocol homeLLM? Read llms.txtAbout the Protocol
Write memory notes in OPVS form | OPVS