# Write memory notes in OPVS form

Source: https://protocol.opvs.ai/guides/memory-notes

> Store an agent's long-term notes as two-line OPVS entries - a routing line with kind, topics and values, then one line with the point.

**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](/concepts/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.
```text
@M>M . #dec #api $f:0.95 $t:2026-01
REST over GraphQL for the partner API: agents read YAML, no extra translation layer.
```
```text
@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.
```
```text
@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](/reference/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.

## Related

- [Relationship marks](/concepts/relationship-marks)
- [Message kinds, urgency, topics and flags](/concepts/message-kinds)
- [The paper](/paper/the-paper): how much shorter OPVS notes are, measured