Claude Code Best Practices - Memory Management

TLDR;

1. Keep CLAUDE.md minimal - Only include what’s needed in EVERY session
2. Use /clear for new tasks - Don’t use /compact unless you really need the context
3. Iterate over small changes - When done, /clear
4. Store project knowledge in docs/ - Reference with @docs/filename.md when needed
5. Memory Bank? - Probably not worth it. Use docs/ instead.
6. Track tasks with checkboxes - Use [ ] in markdown files instead of complex memory systems

Memory Management

Cascaded Memory Files

Claude Code uses a cascaded system to manage memory files.

The memory files are read in the beginning of each coding session. That’s why it’s important to keep them lean as they take up the context window space.

In these files, you typically want to include things like:

• Engineering principles and best practices
• Folder structure and file naming conventions
• Things you don’t want Claude Code to do, such as “Don’t create excessive comments”

Be Specific Just Enough

When writing instructions, it’s important to strike a balance between being specific and not overwhelming Claude Code with too many details (a.k.a wasting tokens). Obviously, things like “follow best practices” are too vague and can lead to confusion.

For example, instead of saying

Follow SOLID principles

you can say

Follow SOLID principles:
- Single Responsibility Principle: A class or function should have one purpose only.
- Open/Closed Principle: Classes should be open for extension but closed for modification.
- Liskov Substitution Principle: Imagine a function that expects a Bird. You should be able to pass in a Sparrow or a Duck, and it should just work.
- Interface Segregation Principle: Don't make a big, fat interface with a bunch of unrelated methods. Instead, split large interfaces into smaller, more specific ones so that classes only implement what they actually need.
- Dependency Inversion Principle: A design rule that says high-level code should depend on abstractions, not concrete implementations.

SOLID is a widely known acronym, so Claude Code will understand it. But the idea is that you will still want to be specific enough to avoid confusion. By doing this, you can also add your personal touch to the instructions.

Don’t overdo it, though. Too many details can waste tokens, and worse, can confuse the LLM.

Q&A

Should I put a lot of details in the project memory file?

A project memory file ( <project root>/CLAUDE.md ) is a good place to put things like:

• Project-specific guidelines, the ones you can’t share with other projects.
• Anything that you need Claude Code to know in every single coding session.

For anything that’s only needed on an ad-hoc basis, it’s better to put them in the docs/ folder and refer to them using the file reference tool @docs/filename.md.

This way, you don’t load a bunch of stuff you don’t need in every coding session, i.e., saving tokens.

Should I compact often?

First of all, you need to know what /compact does. The command asks Claude to summarize the current coding session and make it more concise (shorter).

It sounds good, so why don’t I just do it all the time?

• It’s slow, it can take a minute or more. When you compact, you are not coding. If you do this 60 times, that’s an hour or more time lost.
• You lose the context fidelity of the current coding session. What I mean is that the summary is not as good as the original chat content.

When should I compact?

The context window is almost full and you want to keep the context of the current coding session. If you don’t need the context of the current coding session, it’s better to run /clear or start a new coding session.

If you want to keep the context for future reference, you can ask Claude Code to save the current session to a MD file in docs/.

Do you recommend using a “memory bank”?

If you mean the memory bank concept from Cline, no, I don’t recommend it. It’s just too complicated.

What you can do instead is to use the docs/ folder to store your knowledge. You can use markdown’s checkboxes [ ] to keep track of what’s done and what’s not. Tip: Claude Code can check off the boxes for you.

A typical development workflow would look like this:

1. Brainstorm ideas with an AI. My recommendation is OpenAI’s ChatGPT with Canvas.
2. Create a docs/architecture.md.
3. Ask Claude Code to create a detailed implementation plan based on the architecture document. Ask Claude to add a [ ] before each action item so they can be checked off.
4. Use the magic word ultrathink to trigger the highest level of extended thinking.

Ultrathink: Please create a detailed implementation plan 
based on @docs/architecture.md. The plan should have an 
MVP section and a Future Enhancement section. Under each 
section, create milestones. Under each milestone, create 
action items. Prepend `[ ]` to each action item so they 
can be checked off. For each milestone, add an action 
item for writing unit tests.

Whenever you need extra memory, just create an MD file with [ ] checkboxes. When you need to refer to the file, use @docs/filename.md.

Should I include MCP tool descriptions in CLAUDE.md?

It depends. If the model can use the tools effectively, then no. If the model struggles to use the tools, then add minimal instructions to the memory file.

Conclusion

Memory Bloat

• Don’t: Fill CLAUDE.md with generic instructions like “write clean code” or “follow best practices”
• Do: Only include specific, project-unique instructions

Overusing /compact

• Don’t: Compact after every few messages
• Do: Use /clear for new tasks, compact only when context is critical

Overly generic or specific instructions

• Don’t: Tell Claude things that are overly generic, like “Be thorough”
• Do: Focus on your specific preferences and project requirements

MCP Tool Overload

• Don’t: Document every MCP tool’s usage in CLAUDE.md
• Do: Let Claude figure out tool usage; only document if it struggles

That’s for now. If you have more questions, feel free to leave a comment below.