Memory Files

Memory files are the bedrock of persistent context in Claude Code. Think of them as your AI's long-term memory, a durable layer that outlives the fleeting nature of chat history. The primary example is CLAUDE.md, a markdown file living at your project root or nested within subdirectories. This isn't just another text file; it's a direct channel to Claude's understanding, a place where you engrave the fundamental truths of your project or design system. When you issue a /clear command, wiping the conversational slate clean, or a /compact command, summarizing the chat to free up tokens, the contents of your memory files are not lost. They are reloaded after a clear and re-injected after a compact, ensuring Claude always has access to these core directives. You interact with and edit these files using the /memory command, which opens them for direct modification or allows you to manage auto-memory entries. This mechanism is critical for maintaining consistency across sessions, especially in complex design projects where specific brand guidelines, technical constraints, or user experience principles must be adhered to without constant re-explanation. Auto-memory entries, generated by Claude itself from recurring patterns or explicit instructions, also fall under this umbrella, serving as a dynamic, persistent knowledge base that evolves with your work. They are the ultimate "don't forget this" mechanism, a silent partner ensuring your AI stays on track with your core requirements, even as the conversation shifts and evolves.

Memory files are not your chat history. They are not a temporary scratchpad for fleeting ideas or one-off instructions. If you're telling Claude to "make this button red for now," that's a chat instruction, not a memory file entry. Memory files are also not a substitute for effective, in-the-moment prompt engineering. You still need to guide Claude actively, but memory files handle the invariants, the things that don't change. They aren't a dumping ground for every piece of documentation you've ever written; they're for the high-leverage, frequently referenced, and non-negotiable facts. They won't magically solve all your context management problems if your project structure is chaotic or your instructions are contradictory. They're a tool for stability, not a fix for poor organization. Furthermore, memory files, especially CLAUDE.md, are not a secure vault for sensitive, proprietary information that should never leave your local machine or be exposed to an LLM. While they persist, they are part of the context Claude processes, so treat them with the same caution you would any other input to an AI. They are for durable, foundational context, not transient or confidential data.

Imagine you're a lead designer at "PixelForge," working on a new sustainable packaging initiative for "EcoCycle," a startup focused on biodegradable products. EcoCycle has a strict brand guideline: "All UI elements must use the hex color #34A853 (EcoGreen) for primary actions, and typography must adhere to Inter font family, 16px for body text, with a line height of 1.5." Instead of typing this out in every new chat session or after every /clear, you'd place these rules directly into your project's CLAUDE.md file using the /memory command. You might add: "Invariant: Primary action buttons use EcoGreen (#34A853). Invariant: Body text is Inter, 16px, line-height 1.5." Now, whether you're asking Claude to design a new checkout flow or refactor an existing component, it implicitly understands these core constraints. Another example: your team uses a specific component library, "TerraUI," and every component must be imported from `@terra-ui/components`. You could add: "Rule: All component imports must originate from `@terra-ui/components`." This prevents Claude from generating code that uses a different, non-approved library. Or consider a complex API structure for a legacy system from the early 2010s, say, "LegacyConnect v1.2," which requires a specific authentication header `X-Auth-Token` and returns data in a unique XML format. You could document this in CLAUDE.md: "API Spec: LegacyConnect v1.2 requires `X-Auth-Token` header. Responses are XML, not JSON. Always parse XML with `fast-xml-parser`." These are facts that don't change often, are crucial for correct output, and would be tedious to re-state repeatedly. This direct injection of foundational knowledge saves countless tokens and ensures consistent, on-brand, and technically accurate outputs, making Claude an extension of your team's institutional knowledge.

The golden rule for memory files, particularly CLAUDE.md, is simple: "If you typed it twice, it belongs in CLAUDE.md." This isn't just about saving keystrokes; it's about establishing a stable, consistent baseline for Claude's understanding. Use memory files for invariants: rules that rarely change, core project requirements, brand guidelines, technical specifications, or preferred coding styles that apply across an entire project. If your design system mandates specific spacing units or a particular approach to accessibility, that belongs in memory. If your backend uses a proprietary data format, document it there. When you're onboarding a new designer to your team, they don't re-explain the company's core values every day; those are understood. Memory files serve the same purpose for Claude. You should also use them for auto-memory entries that Claude generates itself, especially when you want to reinforce a specific learning or pattern it has identified. Conversely, do not use memory files for transient information. A bug report you're actively debugging, a temporary workaround, or a specific user story for a single sprint are all too fluid for memory files. These belong in the active chat context, where they can be discussed, resolved, and then allowed to be summarized or cleared. Do not use memory files for personal notes or internal team discussions that are not directly relevant to Claude's task execution. Overloading memory files with irrelevant data can dilute their effectiveness and still contribute to context bloat, albeit in a more persistent way. Also, avoid putting sensitive authentication tokens or highly confidential data directly into memory files if those files are stored in a way that could be exposed. While they persist, they are part of the context Claude processes, so exercise good judgment regarding data sensitivity. The goal is to distill the unchanging essence of your project, not to replicate your entire documentation repository.

Memory files are your AI's permanent instructions, ensuring foundational knowledge persists across every conversation reset and context summary.