Memory & State
15 min read
Every time your agent runs, it starts from nothing. It is handed the student's message, a few recent turns, and whatever files are in the workspace - and then it is gone. That is the honest starting point for this chapter: an agent has no memory unless something outside the model keeps it.
There are exactly two places that memory can live, and the difference between them is the whole design. One is the conversation: the last few messages, kept in the browser, lost when the page reloads. The other is state: a small object your assistant owns, saved with the student's work, loaded again at the start of the next run - in a new tab, on a new day, in a new session.
Getting the split right is what makes an assistant feel like it knows you rather than like a search box. A booking agent needs the conversation and nothing more. A study coach that forgets your weak topics between sessions is not a coach. And both need the same discipline: decide what is kept, write down how it changes, and be able to show what changed.
Two kinds of memory
The conversation is the easy half. Your app keeps the messages, sends the last handful to the agent, and the agent reads them as `history`. It is enough to hold a thread - 'we were booking the study room, you said four people' - and it costs nothing to set up. It also has a hard limit: eight turns is a working memory, not a memory, and a reload erases it.
State is the half that lasts. It is a small object - two or three keys, not a transcript - that your assistant reads at the start of a run and writes at the end. Because it is stored as part of the student's work, it survives the reload, the new tab, and the next day. In the exercises it is literally a file you can open (`state.json`), which makes the lesson visible: what you see there is what the assistant knows.
The useful question to ask about any fact is *how long should this last?* The room booking for Thursday lasts one conversation. The fact that the student is called Sam, or struggles with fractions, should last until they say otherwise. Putting the first in state is clutter; putting the second in history means it disappears at the worst moment.
export default async function run({ input, history, files }) {
const state = loadState(files); // lasts across sessions
const recent = history.slice(-6); // lasts for this conversation
const change = await llm({ system: MEMORY_PROMPT, user: JSON.stringify({ input, state }) });
const next = applyState(state, change.patch, change.clear);
return { reply, card: { type: "memory", retrieved: state, saved: next } };
}javascriptThe two halves, side by side. The history arrives with the turn; the state is read from a file and written back afterwards.
A state is a small object with rules
A state that is just a bag of whatever the model felt like remembering becomes unusable within a week: three spellings of the same topic, two contradictory preferences, and no way to tell which is current. The fix is to decide the shape up front and give every key a rule.
Two rules cover almost everything. A patch *replaces* the key - the newest thing the student said about a topic is the true one, which is what makes a correction work instead of accumulating. And a clear *removes* the key, because a memory you cannot delete is a memory you cannot trust. If a key needs something cleverer - a list that grows, a value with a timestamp - that is a deliberate decision, and it belongs in the same file as the other rules.
The third rule is less obvious: the run has to be able to say what changed. 'I saved that' is only believable if the assistant can show the before and the after, and it is also how you debug a state that has quietly gone wrong.
Asking the model for a change, not a transcript
The model's job in a memory turn is narrow: read the message, say what changed. Asking it for anything more is how a state turns into an unmanageable transcript.
A request with no shape
Remember everything important about this student and use it when you answer.
MESSAGE: I keep getting fractions wrongjavascriptYou maintain a small JSON state. Reply with JSON only:
{ "patch": { "<key>": <new value> }, "clear": ["<key>"], "say": "<one short sentence>" }
MESSAGE: I keep getting fractions wrongjavascriptThe weak version asks for a judgement with no shape, so you get prose you have to parse - and prose cannot be merged into a state. The improved version names the three fields the turn needs: what to write, what to remove, and one sentence for the student. The merge rules stay in your code, where you can test them.
A state the model cannot see
The student said something. Remember it.javascriptThe student said something. Here is the state as it stands: {"weakTopics":["fractions"]}. Reply with what changes.javascriptA model that cannot see the current state cannot tell a first fact from a correction, so it either duplicates or overwrites blindly. Hand it the state, and let it answer the only question that matters: what is different now?
Corrections are replacements
The hardest turn in a memory assistant is the correction. "Actually, I am fine with fractions now, it is algebra" mentions two topics and only one of them is true. If your merge appends, the state now says both, and every future answer is a coin toss between them.
So a patch replaces. The newest thing the student said about a key is the value of that key, full stop. That one rule turns the awkward sentence above into a single, correct fact - and it is why the exercises put the merge in a file you write rather than in the prompt: it is a decision, and decisions belong in code.
The same rule makes forgetting easy. A clear removes the key, and it wins over a patch in the same turn, so "forget my preferences, I like short answers" ends with one short preference and nothing else. Clearing is not an edge case to bolt on later; a memory without a delete key is a memory nobody trusts.
Building the study coach, step by step
The exercise's coach remembers two things - the topics a student struggles with, and the work they have not finished - in a file called state.json. The starter never reads it, so the card reports that nothing is remembered.
1. Prove the problem before you fix it
Send "I keep getting fractions wrong" twice. Both cards say nothing was saved, because the starter's loadState returns an empty object and applyState returns its input unchanged. The second run is the interesting one: the state file exists, and the agent still knows nothing.
2. Load the state from the workspace
The state is a file in the workspace, so loading it is finding a path and parsing JSON - with a fallback, because a student who edits state.json by hand will eventually break it. Read the file, return an object, and log what you found.
const file = files.find((entry) => entry.path === STATE_PATH);
try {
return JSON.parse(file.content) || {};
} catch {
return {}; // a hand-edited state file is normal, not a crash
}javascript3. Merge the patch, and let it replace
Apply the patch key by key, then remove the cleared keys. Return a new object rather than mutating the loaded one, so the diff in the next step can compare the two. Now the correction turn works: "it is algebra" replaces the weak topic instead of adding to it.
4. Say what changed
diffState compares the two objects key by key and returns which were updated and which were cleared. That is what the memory card shows, and it is what makes the assistant's "noted" believable: the card lists the key, the new value and the old one.
5. Check it survived
Open state.json in the editor. Reload the page and send "What should I practise?". The answer comes from what the file held - not from the conversation, which the reload erased. That is the difference the whole section is about, and you can watch it happen in two clicks.
Showing your work
A memory assistant has a trust problem that a stateless one does not: the student cannot see what it kept, so they cannot correct it, and they will not trust it with anything important. The answer is to put the state on screen - what was retrieved, what was saved, what was updated, and what was cleared - every single turn.
That is what the memory card does in the exercises, and it is worth copying even when nobody is watching: a run that says 'saved weakTopics: fractions' is a run you can debug. When a state goes wrong - a key that keeps reappearing, a preference that will not stick - the card tells you which turn did it.
Showing the state also settles the argument about scope. Two panels, side by side: the conversation, which lasts until the page reloads, and the state file, which lasts until something changes it. A student who can see both stops asking the assistant to remember things it was never built to keep.
Mistakes worth catching early
| What goes wrong | What it looks like | What to do instead |
|---|---|---|
| Putting everything in history | The booking survives the conversation and vanishes on reload. | Decide what should outlive the conversation and write it to state. |
| Putting everything in state | A state file that grows a key per turn, most of them useless next time. | Keep the state to the handful of facts that change future answers. |
| Appending instead of replacing | Two contradictory weak topics, and no way to tell which is current. | A patch replaces the key. The newest value wins. |
| No way to forget | A preference the student cannot remove, so they stop trusting the memory. | Support a clear list, and let it win over a patch in the same turn. |
| Saving silently | The assistant says 'noted' and the student has no idea what was noted. | Return what changed and show it: key, new value, old value. |
| Assuming the model wrote the state | The model returns prose, and the state silently stays empty. | Parse defensively, and treat a missing patch as 'nothing changed'. |
Debugging memory
- Send the same message twice. If the second card is identical to the first, the write-back is not happening - or the load is not reading what the write produced.
- Open the state file. It is the ground truth, and reading it beats inferring it from the card.
- Check the scope before the code. A fact that 'disappeared' may simply have lived in the conversation, which a reload clears by design.
- When a correction does not stick, log the patch. The merge is usually fine and the model is usually returning both the old and the new value.
- Watch for state that only ever grows. It is the surest sign that a merge is appending where it should be replacing.
- Reset deliberately: empty the state file, or add a 'forget everything' path. Being able to get back to nothing is what makes the rest testable.