← Back to Blog

My AI Has a Memory, and It Needs a Hygiene Routine

A stale memory stops being a note and becomes an instruction

The first time an AI agent remembered something I had told it a week earlier, it felt like a small miracle. The first time it acted on something that had stopped being true, it felt like a bug I had written myself. Both of those were the same feature.

I work with AI coding agents every day, interactively and in the background. All of them lean on memory. What I have learned is that a memory system for an agent behaves less like a notebook and more like a codebase. It accumulates. It drifts. It needs maintenance, or it starts quietly steering work in the wrong direction.

How the memory is built

Claude Code's file-based memory is plain markdown on disk. The convention I follow is one fact per file. Each file has a short header with a name, a one-line description, and a type. There are four types, and the type tells the agent how to treat the content.

A user memory is about me: my role and working preferences. A feedback memory is a correction or a preference I gave the agent, something like "never run this expensive job automatically." A project memory is the current state of something I am building. A reference memory is a lookup: where a runbook lives, how a tool behaves, which quirk to work around.

On top of those files sits a small index. It is one line per memory: a link and a sentence of summary. The index is what the agent reads first, so it has to stay short. The full files are only opened when the summary suggests they matter. The agent carries the table of contents, not the whole book.

Why one fact per file instead of one big notes document? Because facts change at different speeds. A preference about commit messages might hold for years. The status of a project changes weekly. When they share a file, updating one means rewriting the other, and the agent cannot tell which sentence is fresh. Small files give each fact its own lifecycle.

The convention I care about most is how feedback memories are written. Each one carries two extra sections, Why and How to apply. A rule without its reason gets applied too broadly, or dropped the first time it is inconvenient.

A good example is a feedback memory titled, roughly, "never assume unknown terminology." The rule says: when you hit an abbreviation or a domain term you are not certain about, ask before you use it. The Why records the incident behind it: an agent once guessed what an abbreviation meant, guessed wrong with total confidence, and wrote the wrong expansion into a document as if it were settled. The How to apply section says to ask even when a term looks obvious, and to save the correct definition so the next session does not have to ask again.

That one incident is the whole case for the Why section. Without it, a later session reads "ask about unknown terms" and decides that a term it has seen twice is no longer unknown. With it, the session knows the failure was confident guessing, not unfamiliarity, and it behaves accordingly.

What goes wrong: stale facts become instructions

Here is the failure mode that matters most. A memory written as a fact ("this project belongs to that client, this service runs on that provider") does not read as history to an agent. It reads as the present. And because the agent is helpful, it acts on the present.

Picture the day a whole category of facts expires at once. You drop a vendor. You retire a product. A client engagement ends. Your memory directory is full of entries about that context: its tools, its conventions, the way its systems fit together. None of those entries were wrong on the day they were written. All of them become wrong on the same day.

Leave them alone, and every new session wakes up believing the old world still exists. It suggests the retired tool. A memory system that is good at recall is exactly as good at recalling the wrong thing.

The fix is a single pass, done deliberately. Put a status line at the very top of the index stating what changed and that every entry about the old context is historical. Group those entries together under one clearly labelled line, instead of leaving them scattered between current projects where they can be mistaken for live work.

The lesson: memory needs a way to say "this was true." If your only states are "remembered" and "forgotten," you will either lose history you need or keep instructions you don't.

Two quieter failures

Duplication. The same fact gets written twice, in two sessions, with slightly different wording. Then one copy gets updated and the other does not. The agent picks whichever it reads first. The fix is to merge them, keep the newer one, and say in the text which ruling it replaces and when.

Dangling references. A memory names a file, a model, or a service that no longer exists. Software moves underneath memory constantly. Models get retired, repositories get archived, services get replaced, and the memory that pointed at them keeps pointing. The agent then confidently explains how to use something that is gone. A memory that names a thing should get re-checked whenever that thing changes.

The same rot happens below the content, in whatever pipeline feeds a memory store. If you index notes into a search system, an extraction step can start failing without anything crashing: the store simply stops growing, and every query still returns plausible results from the old data. Pipelines can fail quietly, so watch a health signal that reports dead components instead of assuming they work.

Memory is an attack surface

There is a security side to this that most teams skip. Anything an agent treats as memory, it treats as trusted context. If an agent can write to its own memory based on something it read in an email, a web page, or a pull request from a stranger, then that stranger can write instructions into every future session.

The principle is simple and worth stating plainly: untrusted input should never be the direct source of a memory write. Corrections from the person who owns the agent are fine. Content the agent merely encountered is not. Treat a memory write like a code change. It should be reviewable, it should be attributable, and anything that came from outside should require a human to approve it before it becomes part of what the agent believes.

A team I've seen got this half right. They reviewed every change to their agent's instructions file carefully, then let the agent append "lessons learned" to a separate memory store on its own. The instructions file was locked down. The memory store, which the agent read with the same trust, was wide open.

The routine

None of this is solved by a smarter model. It is solved by maintenance on a schedule, like dependency updates.

A manual consolidation pass. I use a consolidation skill that scans the memory directory, scores its health, and looks for duplicates, stale entries, misplaced scope, and an index that no longer matches the files. It is not cheap: a full consolidation reads everything and costs real tokens, which is why I would never let it run from a hook or a cron job. A reasonable cadence is a light analysis pass when memory starts to feel cluttered, and a full consolidation after a big project ships or a context changes. If the health check comes back clean, skip the consolidation. The tool should tell you what it will cost and ask before it starts.

Save corrections with the reason. Every time you correct an agent, turn the correction into a feedback memory with its Why and How to apply. This is the habit with the best return.

Convert relative dates to absolute ones. "Yesterday," "last week," and "next Thursday" are meaningless the moment the session ends. Write the calendar date, never "today."

Never store what the repository already records. If a fact lives in the code, the commit history, or the project's own docs, the memory should point there or say nothing. A second copy of the truth is a future contradiction. Memory is for what is written down nowhere else: why a decision was made, what you prefer, what bit you last time.

The objections

The first objection I hear is that this is too much ceremony, and that a bigger context window will make memory unnecessary. I don't buy it. A bigger window lets the agent read more, but it does not tell the agent which of the things it read are still true. Staleness is a property of the facts, not of the reader.

The second is that a vector database or a managed memory product will handle it. Those tools are good at recall. Recall is not the hard part. The hard part is retirement: knowing when a fact has expired and marking it so. No retrieval system can infer that your vendor contract ended last week unless someone writes it down.

The third is that one shared memory across every agent is better than one per machine. Sometimes it is, because agents that know the same things contradict each other less. But a shared store multiplies the cost of a bad entry: one poisoned or stale fact now reaches every agent at once. If you centralise, centralise the hygiene with it.

If you're starting a memory system

If you are giving an agent memory, start with the hygiene, not the storage.

Write one fact per file and keep the index short enough to load every time. Give every correction a Why and a How to apply. Write dates as dates. Do not copy into memory what the repository already says. Never let untrusted input write to memory without a human in the loop.

Then plan for the day a whole category of memories becomes false at once. A retired product, a vendor you stopped using. Decide now how you will mark those entries as historical in a single pass, because you will not want to do it one file at a time while agents keep acting on them.

Finally, schedule the cleanup and run it yourself. Look when memory feels noisy, consolidate after big changes, and never make it automatic. A memory you never audit will eventually tell your agent something that stopped being true, and the agent will believe it.