Memory Is Not a Bigger Context Window

The easiest way to misunderstand agent memory is to treat it as a transcript that never ends.

Keep every message. Keep every tool call. Keep every correction. Eventually the agent will know everything that happened.

It will also have to search through everything that happened before making a simple decision, and it will not know which old decision is still valid. That is not memory. It is an attic.

Memory is not everything the agent has seen. It is what the next run needs to know without making the same mistake again.

A transcript records; memory changes the baseline

A transcript is valuable for audit and debugging. It tells you what the agent did, what tools returned, and where the run went wrong. But a future session does not need the whole conversation. It needs the durable result.

The branch convention belongs in memory. The abandoned approach probably does not. The decision to ask before estimating an unclear ticket belongs in memory. The five speculative alternatives discussed before that decision probably do not.

This distinction matters because a transcript is chronological while a working memory should be organized around use. The agent needs current facts, active constraints, decisions, and lessons. It does not need to relive every path that led there.

Four useful kinds of memory

I would keep project memory small and explicit.

Facts describe stable reality: where the application lives, which command runs the checks, which service owns an endpoint, which branch is the production branch.

Decisions record choices that future work must respect: why one workspace contains several repositories, why a boundary is intentionally strict, why a tool is read-only.

Lessons capture failures and their prevention: update main before branching, do not use a broad mutation tool, stop when the same check fails repeatedly.

Tasks describe what is active now. They should expire. A completed task is not a fact about the project and should not remain forever just because it once mattered.

The categories are useful because they give old information an expiration policy. Facts change slowly. Tasks change quickly. Lessons should be revisited when the workflow changes.

Current beats historical

The hardest memory bug is stale truth. An agent reads an old instruction that sounds authoritative and follows it after the codebase has moved on.

Every durable memory item needs an owner and a way to become obsolete. Keep dates where they help. Prefer one current entry over a pile of corrections. Remove a rule when the system no longer needs it. A memory store that only grows becomes another source of context pollution.

This is the same principle as code. Dead code is not harmless because it is still readable. Dead instructions are not harmless because an agent can still follow them.

Write memory at the correction point

The most useful time to update memory is immediately after a mistake has been understood. Not after a month of similar failures. Not as a quarterly cleanup exercise.

The entry should be short and operational: what happened, why it happened, and what rule prevents it. "The build failed" is not a lesson. "The sitemap imports every post, so an unescaped backtick in any content field breaks the build" is a lesson because it changes the next action.

This is how the agent improves without pretending the model itself has permanently changed. The next session inherits the correction because the environment carries it forward.

Memory needs boundaries too

Not every project should share the same memory. A global preference can be useful. A repository-specific deployment rule can be dangerous when applied elsewhere. Scope matters: user memory, workspace memory, project memory, and task memory should not all be one undifferentiated folder.

The agent should know where a rule came from and how far it applies. A local convention is not a universal law. A temporary workaround is not architecture.

The reframe

A bigger context window lets an agent carry more text. Good memory lets it carry the right lessons.

Those are different capabilities. One delays forgetting. The other improves the starting point.

When I add something to agent memory now, I ask whether it will change a future decision. If not, it probably belongs in a log, a document, or nowhere. Memory is a control surface for behavior, not a museum of conversations.

Open your current agent instructions and find one paragraph that no longer changes what the agent does. Delete it. Then find the last correction you repeated twice and turn it into one short rule. That is a better memory system than a thousand more lines of transcript.

The final question is how to know whether these rules actually improve the agent. Good intentions are not an evaluation strategy.