Agent memory

These two words get mixed up, so it helps to separate them early.

• Context is what the model sees on a single call. It is temporary. When the task ends, it is gone.
• Memory is something your harness keeps outside the model, so it can be loaded back in later. It is persistent.

The model itself never remembers. A session is one stretch of work. When a new session starts, the conversation begins empty, and the only thing carried across is whatever the harness chose to write down and read back.

That makes memory a feature you build, with two halves: a write path that decides what to save, and a read path that decides what to load. Both can go wrong, and they go wrong in different ways.

The simplest useful memory is a key-value store: a set of entries, each with a name (the key) and a piece of text (the value). It works much like a Python dictionary that survives after the program ends.

1memory.write("user.preferred_meeting_time", "Mornings, before 11:00. Mentioned on 3 March.")2memory.write("project.orion.owner", "Priya Nair (confirmed by Priya herself).")3 4memory.read("project.orion.owner")   # -> "Priya Nair (confirmed by Priya herself)."

More elaborate systems add search by meaning, expiry dates, and summaries. They are all variations on the same job: put the right thing in, and get the right thing out later.

The temptation is to save everything. It feels safe: nothing is lost. But a memory full of everything is nearly as useless as no memory.

Compare two ways of saving what happened in a long planning conversation.

• A dump. Paste the whole transcript into one entry.
• Facts. Write a few small entries, each holding one thing that will matter later.

The dump has the information, but whoever reads it later has to read it all and sort it out again. If you load it in the next session, you spend the context window on noise, and the original problem of working out what is relevant is back.

Good entries are:

• Small. One fact each.
• Self-explanatory. Readable without the conversation it came from. "Deploy window: Tuesdays 14:00 UTC" makes sense alone. "Same as before" does not.
• Specific. Names, numbers, and dates, not vague summaries.
• Selective. Only what could plausibly be needed again. Throw away greetings, dead ends, and filler.

When you read memory back, the key is usually how you look something up. If the keys are vague, retrieval will be vague.

• notes1, misc, and session_2_stuff tell you nothing.
• deploy.window and team.oncall.primary can be found by anyone who knows what they need.

Pick a consistent scheme, such as topic.subtopic.detail, and stick to it. A reader, which is usually your own code a day later, should be able to guess the key for a fact without listing everything.

If you cannot predict the key, you will end up fetching many entries and hoping. That leads to the failure covered below.

Facts go out of date, and some were never reliable. A good entry carries a little context about its own trustworthiness.

• Source. "Confirmed by the owner" is different from "heard in passing".
• Date. "As of 3 March" lets a reader judge whether it is still current.
• Status. Mark things as tentative or superseded, so that an old value is not mistaken for the current one.

Memory also collects decoys: old notes, rumors, and near-duplicates that look like the answer and are not. A store that has been used for a while will have several entries about the same subject, some current and some stale. Without metadata, a reader cannot tell them apart.

The read path is where a lot of agents go wrong, in the opposite direction from writing. The harness fetches everything "just in case", loads it all into context, and lets the model sort it out.

That brings back all the problems from the context engineering guide. Irrelevant entries are noise. Stale entries are misleading. The decoys get to vote. And you pay for every token of it.

A better read path works from the question:

1. Work out what the question needs. Which fact would answer it?
2. Look it up by key. If you named things consistently, you can often compute the key directly.
3. Fetch a few, not all. If you are unsure, list the keys, which is cheap, and choose from the names. Then fetch only those.
4. Check what came back. Does the value match what was asked? Does its source or date look right?
5. Put only that in context. Pass the relevant entries to the model, labeled with their sources.

Some systems restrict how many entries you can read. That restriction is a hint about the right design, and not only a rule to avoid.

A useful exercise is to imagine the next session before you write anything. In the future, a fresh agent will start with no conversation, no tools that were available today, and a different question. What will it wish it knew?

Then work backward.

• What questions are likely to be asked?
• What facts answer them?
• Under what names would they be easiest to find?
• What did the current session make clear that the next one cannot rediscover?

This is the same habit as writing good documentation, or leaving good notes for a colleague taking over your shift.

You cannot judge memory from inside the session that wrote it, because the agent still remembers everything. The test is a cold start: begin a new session with nothing but the store, and see whether the agent can answer.

When it fails, work out which half failed.

• The fact was never written. Fix the write path.
• It was written but under a vague or inconsistent key. Fix the naming.
• It was written well and the agent fetched the wrong entry. Fix the read path.
• It fetched the right entry and was also given a decoy. Fetch less, or filter by source and date.

Problem 09 splits a task into two sessions. In the first you can see the material and use tools. In the second the material is gone and only memory remains, along with entries that look right and are not. Before you write any code, decide what a person with a perfect memory of session one would want to hand to a stranger doing session two.