Agent memory: five fields you can empty

Agents do not need a diary. They need a few named facts that survive the next step: the user job, the last tool result, the fail count. That is memory. A dumped chat log is not.

This post teaches what to keep, what to throw away, and how memory goes stale.

Memory is fields

Write the object you will pass from step to step.

- job: one sentence
- chunks: list of { title, text }
- draft: string
- fail_count: number
- last_error: string or empty

If a later step needs it, it is a field. If you are keeping it “just in case”, it will be used as if it were true.

A transcript is a pile. The model will pick a friendly sentence from turn three and treat it as the spec.

If you cannot name the field, you are not storing memory. You are storing leftovers.

Three kinds, three jobs

Working memory. The current job and the last result. Lives for this run. Dies when the run stops.

Session memory. The user’s name, the file they chose, the style they asked for. Lives while the tab is open. Clear it when they say “new question.”

Long memory. Facts you are willing to load next week: “this folder is the internship report.” Write those as records you can delete. Do not silently grow a novel.

Most student projects need the first kind, a little of the second, and none of the third.

If you are answering from a PDF, the chunks belong in working memory for this question. They do not belong in long memory unless you have a reason to search them tomorrow.

How memory goes stale

You retrieve chunks for question A. The user asks question B. If you keep the old chunks, the draft will cite a heading that does not apply.

You store fail_count and never reset it. The next job starts already at two, and you stop before you begin.

You store a tool result that failed, then a later step reads it as success because the field is still there.

Rule: when the job changes, reset working memory. Keep session facts only if the user still wants them.

Emptying the chunk slot is a feature. A full slot from the last question is a bug.

What never goes in

Passwords, API keys, other people’s phone numbers, a client dump.

A “memory” feature that can recall those is a leak, not a product.

Also leave out: the model’s chain of thought, the reviewer’s pep-talk, every search you ever ran. Those belong in a debug log you can turn off, not in the object the next node reads.

If you use MCP or a file tool, the folder you attach should already be a folder you would show a classmate. Memory does not make a secret safer.

A small design that works

For a notes Q&A agent:

1. On a new question, clear chunks, draft, fail_count, last_error.
2. Keep folder if they did not change it.
3. Retrieve into chunks.
4. Draft into draft.
5. Check. If fail, increment fail_count and write last_error as the failing sentence, not as an essay.
6. Repair reads last_error and chunks only.

That is enough to recover. It is also enough to explain when someone asks why the second answer ignored their new question: you forgot to clear chunks.

Common mistakes

Embedding the whole chat “for context.” You will not know which line won.

Memory that only grows. Add a delete. Add a “new question” that wipes working fields.

Storing summaries of summaries. After three wraps, the job has changed and nobody noticed.

A vector store as a junk drawer. If you cannot list what is in it, you cannot trust a hit.

Treating memory as personality. “Remember I am witty” is not a field you can test. Skip it.

Practise

1. Write the five fields on paper.
2. Run two questions in a row on the same folder. After the first, print the object. After the second, confirm chunks are about question B.
3. Force a check fail. Confirm last_error is one sentence.
4. Click “new question.” Confirm working fields are empty and folder is still there.
5. Try to put a secret in a field. Remove the field instead.

If both answers share the same chunk titles, your memory did not reset.

Checklist

• Memory is a short object you can print.
• A new question clears working fields.
• last_error is one sentence, not a transcript.
• Nothing in the object would embarrass you on a shared screen.
• You have a two-question test that proves the reset.

The next step is five fields you can empty, not a longer history.