How Claude Code Remembers Things: A Guide for Developers

Three layers that control what Claude knows, how it behaves, and what it remembers across sessions.

When you start working with Claude Code in your projects, you’ll notice it can be configured at different levels. Understanding the distinction between these three layers will save you from configuration headaches and help your team get the most out of the tool.

1. The .claude Folder: The Plumbing

This folder lives in your project root and is created automatically when you first use Claude Code. Think of it as tooling configuration—it tells Claude Code how to operate, rather than what to know.

• Contents: MCP (Model Context Protocol) server definitions, permission settings, and event hooks.
• Analogy: It is in the same category as .vscode or .editorconfig.
• Team Impact: It should be committed to your repository so the whole team benefits from the same tool integrations.

For standard use cases, this folder requires little manual intervention; it works quietly in the background.

2. CLAUDE.md: The Team Briefing

This is the most important file for day-to-day team use. It is a plain Markdown file placed in the root of your project that Claude reads automatically at the start of every conversation.

Think of it as a permanent briefing document. You write it once, and every time a developer opens Claude Code in that project, the AI is already up to speed on your specific rules.

Best used for:

• Workflow rules: Such as always running a build after making changes.
• Communication: Like posting a GitHub issue comment after every push.
• Standards: Following specific naming conventions or avoiding deprecated patterns.

Because it sits in the root like a README.md, it is visible, obvious, and version-controlled. The whole team owns it.

3. The Memory Folder: Personal Experience

This layer is different. It lives not in your project, but in your local user profile:

~/.claude/projects/<project-identifier>/memory/

Claude manages this folder itself. During a session, if Claude learns something worth remembering—a recurring pattern, a specific bug fix, or an architectural decision—it can write that to a file here to recall in future sessions.

• Personalization: This memory is personal to your machine and isolated per project.
• Isolation: If you switch repositories, Claude accesses a completely separate memory folder. Nothing "leaks" between projects.
• Structure: The file names are flexible. You might see a MEMORY.md for general notes or specific files like patterns.md for more detailed technical context.

How They Work Together

To keep things simple, categorize the layers by the questions they answer:

• .claude answers: "How does the tool behave?" This is where the plumbing lives.
• CLAUDE.md answers: "What should Claude always know about this project?" This is where you set team standards.
• The Memory Folder answers: "What has Claude learned from working here over time?" This is where Claude builds experience.

Configuring Claude Code is straightforward once you know where things go: put your rules in CLAUDE.md, let the memory folder handle the learning, and only touch .claude when you need advanced integrations.