Memory and state

Kinds of memoryCopy Anchor Link

Working memory is the current context. Session memory is a log or summary of what happened so far. Long-term memory is facts and preferences stored outside the window, usually as files, a database or a vector index, and retrieved when relevant. Procedural memory is instructions and skills that tell the agent how to do things.

Practical designCopy Anchor Link

Start with plain files: a progress notes file, a decisions log and the project memory file. They are readable, diffable and easy to edit. Add retrieval only when the notes outgrow the window. The hard problems are choosing what to write down, avoiding stale or wrong facts, and forgetting on purpose. Anything the agent writes to memory can be wrong, so treat it as a hypothesis to verify.

A worked example: a notes fileCopy Anchor Link

After each session the agent appends to notes.md: "User prefers metric units. Project uses PostgreSQL 15. Decision 3 May: use queue for emails." At the next session it reads the file first. Plain text, readable by you, editable by you. Later, if the file grows, add search over it.

How a note gets back into the windowCopy Anchor Link

The model does not read your notes file by itself. At the start of each session your harness reads the file and pastes it into the prompt, so the text is in the window again.

That has a price. Invented numbers: the file is 2,000 tokens and grows by 200 tokens a session. Every call carries it. After 40 sessions it is 10,000 tokens on every call, even when most lines are irrelevant. That is the point where search over the notes starts to pay for itself.

What goes wrong: stale memoryCopy Anchor Link

A note says "The project uses PostgreSQL 15." The team has since moved to 16. The agent reads the note, trusts it, and writes code for the old version. The symptom is an agent acting confidently on a fact that was once true. Confirm it by asking the agent where it got the fact, then checking the date on that note. Fix it by dating every entry and having the agent check anything it can look up, such as a version, before acting on it.

When memory is the wrong toolCopy Anchor Link

Do not copy into notes what the agent can read from the source. A list of files in the repo goes out of date on the next commit, while the repo itself is always right. Use memory for what cannot be recovered: what the user prefers, which approach was chosen and why, and which attempts already failed.

Common mistakeCopy Anchor Link

Building a complicated memory system before trying a notes file.