What Is Agent Memory (and Why Does Your Agent Forget)?

Quick answer
Memory is state that survives a session: files the agent reads at startup, a database it queries, or notes it writes for later.
The context window is working memory for one session. When the session ends or the context is compacted, that state is gone unless something wrote it down.
Coding agents typically get memory from repository files such as AGENTS.md and skills, plus optional user-level notes.
Most forgetting is not a model failure: the agent never stored the fact, or stored it somewhere the next session does not read.
Memory that is not reviewed becomes stale instructions, which is worse than no memory.

What is the difference between context and memory?

Context is everything in the model’s window right now: the system prompt, the files it read, the conversation, the tool output. Memory is state outside that window which can be loaded into it later. A long conversation is not memory; it is a large context that will eventually be compacted.

That distinction explains most “the agent forgot” complaints. The fact may have been established in a session whose context was summarised, or in a session that never wrote the fact to a file the next session reads.

Where does a coding agent’s memory actually live?

Usually in files: AGENTS.md for standing rules, skills for procedures, a decisions document for the reasoning behind the architecture, and occasionally a user-level notes file for personal preferences. Some harnesses also add an automatic memory store, but the mechanism is the same — text retrieved at startup.

Anything not in one of those places is unavailable to the next session. If a constraint matters beyond today, it belongs in a file that is read every session, or it does not exist.

# What the agent will read in a new session
ls -la AGENTS.md .agent/ 2>/dev/null
find .agent -name 'SKILL.md' -maxdepth 3 2>/dev/null
# Add durable decisions where they are read, not in a chat thread

Why does the agent repeat mistakes it already fixed?

Because the fix was a conversation, not a rule. If the agent used the wrong test command three times, the lesson needs to be in AGENTS.md as the command to use. If it keeps editing generated files, the exclusion needs to be written down.

The second cause is stale memory. A notes file that says “use the v1 API” after the migration to v2 will cause the same mistake on purpose. Memory needs an owner and a date, like any other documentation.

How should you maintain it?

Keep memory short and current. Review it when the repository changes, delete entries that no longer apply, and prefer linking to a file over duplicating its content. A memory file that has grown for a year is a second codebase with no tests.

Treat additions as code changes: they go through review, they are committed with the work that motivated them, and they can be reverted. Memory that only one person can edit is a single point of failure for the whole team’s agent behaviour.

Where this bites vibecoders
The instinct is to solve forgetting by pasting more history into the prompt. That buys one session and makes the next worse, because the context fills with transcript instead of code. Write the fact into the rules file once, and stop repeating it.

Where AI coding assistants get this wrong

Treating a long conversation as durable memory.
Storing decisions only in chat, where the next session cannot read them.
Letting a memory file accumulate stale commands.
Duplicating documentation into memory instead of linking it.
Assuming the harness persists facts automatically.
Giving one person sole ownership of the rules file.

Checklist

Decide which facts the next session must know.
Put each in the file that is read at startup.
Delete entries that no longer apply.
Link to long documents instead of copying them.
Commit memory changes with the work that caused them.
Review memory on a schedule, not only after a failure.

FAQ

Does the agent remember my preferences between sessions?

Only if they are written somewhere the harness reads. Some tools keep a user-level notes file automatically, some require you to add it. A preference expressed once in a chat is available to that session and to nothing afterwards.

Is compaction the same as forgetting?

Effectively, yes, for the details it drops. Compaction summarises older context to keep the session running, and the summary preserves the gist rather than exact values. Anything that must survive precisely should be in a file.

Should memory live in the repository or with the user?

Team conventions belong in the repository, so everyone gets them and changes are reviewable. Personal ergonomics belong in user-level configuration. Mixing the two means one person’s shortcut silently governs everyone.

How much memory is too much?

When it stops being read in full or starts contradicting itself. Long instruction files are skimmed, and contradictions produce inconsistent behaviour. If the file needs a table of contents, it needs splitting.