Notes an agent can read
An agent reads differently from you: it searches by file name, reads the beginning first and cannot ask what was meant. Six rules for notes that humans and machines understand equally well.
Boaz Lichtenstein
Your notes work for you because you were there. You know that “the call with M.” means Martina at the supplier and that the third bullet is the important one. An agent does not know that – and it does not ask, it fills the gap.
How an agent reads
An agent with access to your notes does not read everything. It lists file names, searches for terms from your question, opens the hits and reads from the top. If the beginning is enough, it stops. Six rules follow from that.
1. One note, one subject, one descriptive name
Supplier-payment-terms.md gets found. Note 14.md does not. The file
name is the most important search term you assign. If you cannot think
of a name for a note, it contains more than one subject.
2. The first sentence summarises
Write one sentence at the top saying what the note contains and what it applies to. An agent decides on that whether to read on – and so will you in six months.
3. Date and origin come with it
Every statement that can change needs a date and a source. Cleanest in a small header at the start of the file:
---
type: operations
updated: 2026-11-10
source: framework agreement of 3 Feb 2026, section 4
---
# Supplier payment terms
Which payment period is agreed with which supplier.
Applies to all orders from February 2026.Without a date, an agent treats a three-year-old note like one from yesterday.
4. References are spelled out
“See above” and “as discussed” lead nowhere. Link the other note by name
and say in half a sentence what is there: “The contacts are in
Supplier-contacts.md.” That way the agent does not have to open every
linked file to know whether it needs it.
5. One fact, one place
If the payment period is in three notes, two of them are wrong after the next change – and the agent happens to find one of the wrong ones. Fix one place for each statement and point to it from everywhere else.
6. Text, not image
Tables as Markdown tables, procedures as numbered lists, numbers as numbers. A screenshot of a table is, to an agent, an image it first has to decipher – with reading errors precisely on the digits.
The stranger test
Imagine a new colleague is handed just this one note, without explanation. Can she answer the question the note is meant for? If so, an agent can too. If she would have three questions, the three answers are not in it yet.
You do not have to rewrite your whole archive for this. Start with the ten notes you are asked about most often – by people or machines. Which tool those notes are best kept in is the subject of the next station.