CLAUDE.md & Memory

Knowledge

The Project Memory of Claude Code

Imagine working with a brilliant colleague who forgets everything every morning. You have to explain to them every day: "We use pnpm instead of npm. Tests run with Vitest. No semicolons, please." Frustrating, right?

That is exactly the problem CLAUDE.md solves. It is the project memory of Claude Code -- a simple Markdown file where you record once what Claude needs to know about your project. At the start of every new session, Claude reads this file automatically and immediately knows your rules, conventions, and quirks.

Two Memory Systems

Claude Code has two complementary memory systems:

CLAUDE.md -- You write for Claude. Here you consciously define rules and context: build commands, code conventions, architecture decisions. You have full control over the content. Think of it like an onboarding document for a new colleague.

Auto Memory -- Claude writes for itself. During work, Claude takes notes about things it has learned: debug strategies that worked, your preferences, recurring patterns. Claude automatically saves these notes in a separate memory file and loads them in future sessions.

The 4-Level Hierarchy

CLAUDE.md does not exist just once. There are four levels that build on each other -- from global to local. The more specific a rule is, the higher its priority. A rule in a subdirectory overrides a global rule, just like CSS specificity.

In the following sections, we will look at each level in detail, explore the Auto Memory system, and develop best practices for effective CLAUDE.md files.