8 / 13My First AI Agent — Part II · 20 min read

Making it remember

Today’s chat disappears when you close it. What you want kept has to be written down.

Three memory floors
Cap is a feature · writes often load next session
1 · The notebook
SOUL · MEMORY · USER
Read every chat · kept small
2 · Past chats
Old conversations
Searchable, word for word
3 · Your notes
Your notes folder
Next lesson

Where it keeps things

Part II starts here because an agent that forgets your preferences every morning makes you repeat yourself forever. Your agent keeps things in three places, and it is worth knowing which is which.

WhereWhat it holdsHow much
1 · The notebookSOUL.md, MEMORY.md, USER.md — read at the start of every chatSmall on purpose
2 · Past chatsOld conversations it can search back throughAs much as your disk allows
3 · Your notesA folder of your own notes it can read (next lesson)As much as you write

It writes now, it reads next time

The agent reads its notes once, when a chat starts. So if it writes something down mid-conversation, asking “do you remember?” in that same chat can still come up blank — the file is right, it just has not re-read it. Check the file, then start a new chat to see it in action.

If MEMORY.md has the line and this session ignores it — close and reopen before blaming the agent.

`MEMORY.md` and `USER.md`

MEMORY.md is the agent notebook — your setup, your conventions, what it learned. USER.md is your card: name, preferences, things to avoid. The agent writes both; you can edit them in any text editor. Anything it never writes down, it never keeps.

Both are deliberately small, because they are read at the start of every chat — every line you add is a line the agent carries around forever. Keep decisions, preferences and corrections; never transcripts. When they fill up: merge lines, shorten them, delete what is stale.

Remembering everything is remembering nothing. Prefer dense facts.

That makes three files in your Hermes home, all loaded every chat, so it is worth being precise about which is which:

FileHoldsWho writes it
SOUL.mdWho the agent is — role, tone, hard limitsYou, once — it rarely changes
MEMORY.mdWhat it learned — your setup, conventions, decisionsThe agent, as you work; you can edit
USER.mdWho you are — name, preferences, avoid-listThe agent, from what you tell it
A preference like “keep answers short” belongs in USER.md, not SOUL.md. Identity is what the agent is for everyone; memory is what it knows about this setup and this person.
File over app: closed chat products do not offer this honesty.

Prove it remembers

The one way to fool yourself here: if you do not fully close the chat, the fact is still on screen and the agent will repeat it back without ever reading the file. A half-closed session always passes. Close it properly.
Steps · tap the number to check0/4
  1. Tell the agent: “Remember that project codename is HARNESS-01 and I prefer short answers.”
  2. Ask it to write that to durable memory.
  3. Open MEMORY.md / USER.md on disk and check the lines are really there.
  4. Fully close the chat. Open a new one. Ask: “What is my project codename and answer length preference?”
Go further

Memory vs hallucination

Without memory the model fills gaps with confidence. With memory and sources it consults first. Still fallible — but checkable by you and by the agent.

Checklist · this device0/2
Exercise · Check yourself

Where do durable preferences live?

Pick one — the answer is revealed straight away.

Exercise · Check yourself

File updated but chat “forgets” now?

Pick one — the answer is revealed straight away.

Go further

You are done when

Proof · this device0/1

Stored on this device only — not sent anywhere.

Part II begins
You already have an agent. Now give it durable memory and ownership habits.

← PreviousFirst agencyNext lesson →Data vault
All lessons