A monthly clean-up of your AI agent's files

An outdated note doesn’t stand out. The entry “the price list is in price-list-2025.xlsx” looks exactly the same in Claude Code’s memory whether the file is still in the folder or has been gone for three months. Nothing turns red, nothing throws an error – the AI simply starts getting things wrong, looking for prices in a file that isn’t there any more, for instance, and it’s hard to guess why.

That’s why the clean-up is worth putting in your calendar, rather than waiting for something to break.

Start with /doctor

One command gives you the first list. Start Claude Code in the folder you usually work in and type:

/doctor

The /doctor command is a built-in check-up of the whole of Claude Code. It checks whether the program is installed twice and whether an old installation has left anything behind. It also looks for skills, MCP servers and plugins you don’t use, and shows how much room they take up in the context, meaning what the AI has in front of it in every chat.

Before it changes anything, /doctor shows you what it found and asks for your permission. So you can read the result without worrying, and every proposal is yours to decide on. A skill you use once a quarter can safely stay, even if /doctor counts it as unused. If you’re not sure what a proposal is about, ask Claude Code about it in the same chat.

/doctor can also shorten your CLAUDE.md file, but only in a folder that is a git repository. If you don’t know what a git repository is, don’t worry – Claude Code will check the CLAUDE.md file as well during the memory review in the next step and suggest what to fix in it.

If /doctor only shows a diagnostics screen and suggests nothing, you have an older version of the program. Close Claude Code, type claude update in the terminal and start claude again.

The command /doctor prompt-audit (from version 2.1.283) checks CLAUDE.md files and skills for outdated or contradictory instructions. You can run it after the regular /doctor, but it doesn’t look at auto memory, so you’ll do that part anyway, with the request described below.

Ask Claude Code to review its memory

Ask Claude Code for the memory review in the same folder where /doctor has just run. Every folder has its own memory, so the review covers the notes from your work in that folder. The exception is a git repository: the whole repository shares one memory, so a single review in its main folder is enough. If the term means nothing to you, the exception doesn’t apply to you. Paste this request into the chat:

Review your auto memory for this folder. Read the MEMORY.md file and all the memory files next to it, the CLAUDE.md file in this folder and my global CLAUDE.md file. Look for entries that are no longer true, entries saved twice, entries in the wrong place and references to files or folders that no longer exist. Check every entry that can be checked: does the file, folder, skill or command it mentions still exist? Don't change or delete anything. Give me a list of proposals split into three groups: change, merge, delete. For each item, say how you know. At the end, ask me what to do with the list: just show it, fix it one item at a time, or fix everything at once. Only delete an entry after I've confirmed it separately.

The sentence “Don’t change or delete anything” is your safety catch. Because of it, the first review leaves your files untouched, even if Claude Code comes across something it thinks should be fixed straight away.

If Claude Code asks for permission to read one of the files, you can say yes. Reading on its own changes nothing.

Sometimes the list is empty or has only two items. That can mean your memory is in good order, but check with one question: “How many memory files did you read, and what are they called?” If the files it read are only MEMORY.md and CLAUDE.md, ask Claude Code to read the other memory files too and finish the review.

What Claude Code looks for

In the review, Claude Code looks for four kinds of fault: outdated entries, entries saved twice, entries in the wrong place and references to files that no longer exist. This is what its list might look like in a folder of quotes and price lists after two months of work:

Change

1. The entry “the price list is in price-list-2025.xlsx” – the folder now only has price-list-2026.xlsx. I suggest correcting the file name.
2. CLAUDE.md says “this week I’m finishing the quote for the wholesaler” – that’s work in progress from five weeks ago. I suggest moving it to memory or deleting it.
3. The rule “never send a quote without my approval” sits in one of the memory files, not in CLAUDE.md. I suggest moving it to CLAUDE.md.

Merge

4. The rule “I sign quotes with my full name, without the company name” is both in memory and in CLAUDE.md. I suggest keeping it only in CLAUDE.md.

Delete

5. An entry points to a contract-templates folder that no longer exists. I don’t know whether the templates went somewhere else – I’ll ask before doing anything.

Item 4 is a duplicate, and duplicates drift apart easily: you correct one copy and the other keeps the old wording.

Items 2 and 3 are entries in the wrong place. CLAUDE.md works like a note stuck to your monitor: Claude Code reads the whole of it at the start of every chat, so every sentence on that note takes up room in the context. That’s why the note holds what should apply always, not this week’s plan, which a month from now is just dead weight.

Memory is more like a binder. Its table of contents, the MEMORY.md file, sits on top, and Claude Code reads it at the start, though only up to a certain length. The other memory files are the sections inside the binder: Claude Code only opens them when it decides it needs them. A rule tucked away in one of those sections may therefore never get loaded in a given chat – hence the suggestion to move it onto the note.

What to do with the list of proposals

The list from Claude Code is a set of proposals, not a verdict. The last sentences of the request tell Claude Code to ask you at the end of the review what to do with the list, and to give you three options:

1. Just show it – the list stays in the chat, the files stay as they are.
2. One at a time – Claude Code proposes the changes one after another, and you accept or reject each one.
3. Fix everything – Claude Code makes all the changes on the list straight away.

For your first review, choose “just show it”. Read the list calmly and answer in your own words, for example: “Do items 1, 3 and 4 the way you suggest, move item 2 to memory, and for item 5 fix the path – the templates are now in the contracts folder”. If you’re not sure whether an entry is still current, simply leave it and tell Claude Code so. In a month you’ll have a chance to come back to it.

Always confirm deleting an entry separately, even when you choose “fix everything”. An old entry is sometimes the only trace of why something is set up the way it is, and once it’s deleted, nobody can reconstruct that.

Save the date of the review

Once you’ve decided on every item on the list, ask Claude Code to save the date:

Save the date of today's memory review at the very top of the MEMORY.md file in your auto memory. Add one sentence to the CLAUDE.md file in this folder: if more than a month has passed since the last memory review, remind me of it in your first reply in a chat.

The date goes at the very top of MEMORY.md, because Claude Code reads that part of the file at the start of every chat, even once the memory has grown long. The reminder sentence goes into CLAUDE.md – it’s a standing rule, so it belongs on the note by the monitor, not in the binder.

The reminder only appears in a chat you open – Claude Code won’t get in touch with you on its own. If you want to be sure the review doesn’t slip your mind, put it in your calendar, for example for the first Friday of the month.

Turn the review into a skill

Next time you don’t have to paste all the requests again. A skill is a file of instructions that Claude Code carries out when you type a single command. The memory review makes a good skill, because every time it has the same steps, the same list and the same ban on changes without your approval. You don’t have to write the skill yourself – ask Claude Code for it:

Create a skill called memory-review. The skill should review the auto memory in the folder I run it in: read the MEMORY.md file and the memory files next to it, the CLAUDE.md file in this folder and my global CLAUDE.md file, then find entries that are outdated, saved twice or in the wrong place, and references to files that no longer exist. It should check every entry that can be checked. It splits the list of proposals into three groups: change, merge, delete, and for each item says how it knows. It changes and deletes nothing until I choose what to do with the list: just show it, fix it one item at a time, or fix everything. It only deletes an entry after I've confirmed it separately. At the end it writes the date of the review at the very top of the MEMORY.md file, replacing the previous one. Save it as a global skill, available in every folder of mine.

The skill reviews the memory of the folder you run it in, so one skill covers the review in every folder where you work with Claude Code.

In a month, open a chat in your folder, type /doctor first and then /memory-review. From the second review on, these two commands are all it takes.

What to take away from this lesson

• An outdated memory entry looks the same as a current one, which is why the clean-up happens once a month, not only once the AI starts getting things wrong.
• Claude Code reviews the memory files and CLAUDE.md. You only read its list and decide.
• Your first review is always “just show it” – the files change only once you’ve said what to take from the list.
• What should always apply belongs in CLAUDE.md, the current state of work in memory. An entry in the wrong place either takes up room in the context of every chat or may never get loaded at all.
• Confirm deletions separately, because an old entry is sometimes the only trace of a decision.

Tasks

Tick each one off when you’ve done it. Your progress is saved in the browser, so you can come back to this list tomorrow.

• /doctor run, the result read, a decision made on every proposal
• Memory review requested in the folder you usually work in
• List of proposals read in “just show it” mode
• An answer for every item: change, merge, delete or leave
• Every deletion confirmed separately
• Review date saved in MEMORY.md
• Reminder sentence added to CLAUDE.md
• memory-review skill saved and visible after you type a slash
• Next review put in your calendar