The Agent Memory Problem: What Persists and What Should Not

Every agent tool added memory in 2025. Most implementations are too aggressive. After a year of running agents with persistent memory on real projects, I have strong opinions about what should persist and what absolutely should not.

What Should Persist

Project structure and key file locations
Decisions with explicit rationale (why, not just what)
User preferences that change rarely (coding style, brand rules)
Credentials and API endpoints (with care)

This set is small on purpose. Persistent memory is useful only when the recall rate is high.

What Should Not Persist

Specific bug fixes (they become outdated as the code changes)
Temporary workarounds (they get applied after the workaround is no longer needed)
User frustration (you do not need the agent to remember you were annoyed)
Failed attempts (let them die with the session)

The trap is thinking more memory is better. More memory means more stale context bleeding into new work.

The Half-Life Principle

I think about memory in terms of half-life. How long until this information is more likely to mislead than help?

Project structure: six months
Architectural decisions: one year
Bug fixes: one week
Coding preferences: two years

Any memory system that does not have decay is going to accumulate garbage.

My Current Setup

I keep two levels of memory:

MEMORY.md in my home directory: long-half-life facts about me and my workflow
Project CLAUDE.md: project-specific decisions, structure, and constraints

Everything else lives in session state and dies with the session. The discipline is refusing to commit fresh details to memory unless they will still be true in a month.

The Review Ritual

Every two weeks I read both memory files and delete anything stale. Takes ten minutes, prevents the slow accumulation of wrong facts. Agents with dirty memory are worse than agents with no memory, because they are confidently wrong.

Anthropic's memory tool documentation is worth reading once you have decided what should persist.

The Team Dimension

On solo projects the memory problem is solvable by discipline. On team projects it becomes political. Whose decisions get committed to the shared memory? Whose preferences override whose? Year two I started treating shared memory like shared code: pull request reviewed, documented, owned. The same review rigor applies and the same benefits accrue.

The Dirty-Memory Symptom

You can spot dirty agent memory from outside. The agent gives confidently wrong answers that contradict the current code. It repeats workarounds that are no longer needed. It references files that have been deleted. When I see these symptoms, I stop using the agent until I have cleaned the memory. Continuing is worse than starting fresh.

What I Tell Other Builders

Memory is power. Memory is also a footgun. Treat it with the same care you treat environment variables and secret keys. Small, curated, reviewed, pruned. The payoff is an agent that gets better over time instead of confidently worse.