What is CLAUDE.md? Persistent Memory That Transforms Claude Code Sessions

One of the most powerful—and underused—features of Claude Code is the CLAUDE.md file. It's the difference between a frustrating session where you constantly repeat yourself and a productive flow where Claude already knows your stack, your conventions, and your preferences.

When you open Claude Code without a CLAUDE.md file, it's like hiring a new contractor every single day. Claude has to:

• Re-explore your codebase from scratch
• Make assumptions about your dependencies
• Guess at features you've already implemented
• Figure out your coding style and preferences

But with CLAUDE.md, Claude gets an onboarding script that runs automatically every session.

The Core Problem CLAUDE.md Solves

Every time you start a new Claude Code session without persistent memory:

1. Context is lost - Claude doesn't remember you're using Next.js 15 with App Router
2. Assumptions are made - Claude might suggest REST endpoints when you use server actions
3. Time is wasted - You spend the first 5 messages explaining your stack
4. Corrections repeat - You tell Claude "use Tailwind, not inline styles" for the 10th time

CLAUDE.md fixes this by appending its contents to your prompt automatically at the start of every session.

What Goes Inside CLAUDE.md

A well-structured CLAUDE.md acts as semantic context that shapes how Claude understands and works with your codebase.

Here's a real-world example from a Next.js 15 project:

# Project Context

## Stack
- Next.js 15 (App Router)
- TypeScript
- Tailwind CSS
- Drizzle ORM
- PostgreSQL

## Commands
- Dev server: `npm run dev`
- Run tests: `npm test`
- Lint: `npm run lint`

## Code Style
- Use two-space indentation
- Prefer named exports over default exports
- All API routes go in `app/api/`
- Use server actions instead of API routes where possible

## Architecture Decisions
- Authentication uses NextAuth.js v5
- Database migrations run via Drizzle Kit
- Client components marked with "use client" only when necessary
- Prefer server components by default

If Claude Code reads this at session start, it immediately knows:

• How to run your dev server
• What CSS framework to use for styling
• Where API routes live
• When to use server actions vs API endpoints

The Memory Hierarchy: Project vs User Level

Claude Code supports two levels of CLAUDE.md files depending on who they're for:

Project-Level CLAUDE.md

Lives in the root directory of your repo alongside README.md and package.json.

What to include:

• Project stack and dependencies
• Dev/build/test commands
• API conventions
• Architecture decisions
• File structure and organization
• Team-wide coding standards

Example:

# ExplainX.ai Project

## Stack
- Turborepo monorepo
- Next.js 15 (App Router) in apps/web
- Tailwind + shadcn/ui components
- Drizzle ORM + PostgreSQL
- Deployed on Vercel

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`

## Conventions
- Use server actions for mutations (not API routes)
- Components live in `apps/web/components/`
- Shared utilities in `packages/utils/`
- Database schema in `apps/web/db/schema.ts`

User-Level CLAUDE.md

Lives in ~/.claude/CLAUDE.md (your Claude Code config folder).

What to include:

• Your personal coding style preferences
• Formatting rules you always want
• Tools and libraries you prefer
• Your preferred comment style
• Personal shortcuts and aliases

Example:

# Personal Preferences (Yash)

## Coding Style
- Always use functional components (never class components)
- Prefer const arrow functions over function declarations
- Use descriptive variable names, avoid abbreviations
- Add JSDoc comments for exported functions only

## Libraries I Prefer
- Date handling: date-fns (not moment)
- Forms: react-hook-form + zod
- State: React Query for server state, Zustand for client state
- Testing: Vitest + Testing Library

## Never Do
- Don't use any/unknown without explicit reason
- Don't add console.logs (use proper logging)
- Don't create barrel exports (index.ts re-exports)

This travels with you across all your projects and keeps your personal style consistent.

The /init Command: Auto-Generate Your CLAUDE.md

Don't want to write CLAUDE.md from scratch? Claude Code has you covered.

Run this command in any Claude Code session:

/init

Claude will:

1. Analyze your codebase - detect framework, dependencies, file structure
2. Infer conventions - understand your testing setup, API patterns, styling approach
3. Generate CLAUDE.md - create a comprehensive file based on what it found

You can then review and refine it before committing to your repo.

Best Practices for Using CLAUDE.md

1. Start Without One (Then Add It)

Counter-intuitive but effective: when starting a new project, don't create CLAUDE.md immediately.

Instead:

• Work with Claude Code for a few sessions
• Notice when you repeatedly correct Claude
• Track what context you keep re-explaining

Then create CLAUDE.md with only the necessary information.

Why? This keeps your CLAUDE.md compact and high-signal. You avoid bloating it with assumptions that may not matter.

2. Explicitly Ask Claude to Save to Memory

When you have to course-correct Claude during a session, say:

"Always use server actions instead of API routes. Save this to memory."

Claude will update your CLAUDE.md file with this preference so it persists across sessions.

3. Reference Docs with the @ Symbol

If you have project docs you want Claude to always reference, add them to CLAUDE.md:

## Documentation References

- API conventions: @/docs/api-guide.md
- Component patterns: @/docs/component-library.md
- Database schema: @/docs/database-schema.md

When Claude sees this, it knows to pull context from those files when relevant.

4. Keep It Focused and Scannable

CLAUDE.md isn't a dump of every possible detail. Think of it as a cheat sheet for Claude.

Good:

## Stack
- Next.js 15 (App Router)
- Tailwind CSS
- Drizzle ORM

Bad:

## Stack
We are using Next.js version 15 which was released in October 2024
and includes many new features such as improved caching, better image
optimization, and support for React 19 canary. We chose Next.js because...
[500 more words of rationale]

Claude doesn't need the history lesson—just the facts.

5. Update It as the Project Evolves

CLAUDE.md is living documentation. When you:

• Adopt a new library
• Change an architecture decision
• Add a new convention

Update CLAUDE.md immediately. This keeps it accurate and prevents Claude from working with stale assumptions.

CLAUDE.md vs Other .md Conventions

The .md ecosystem has exploded in 2026. Here's how CLAUDE.md fits in:

Use them together:

• CLAUDE.md tells Claude how to work on your codebase
• DESIGN.md tells Claude how to apply your design system
• SKILL.md tells Claude what reusable workflows are available
• README.md tells humans how the project works

Real-World Example: Before and After CLAUDE.md

Without CLAUDE.md (Session 1)

You: "Add a form to create a new blog post" Claude: "I'll create an API route at /api/posts..." You: "No, we use server actions, not API routes" Claude: "Got it, let me create a server action..." You: "Also, use Tailwind for styling, not inline styles" Claude: "Updated to use Tailwind..."

Without CLAUDE.md (Session 2 - Next Day)

You: "Add validation to the blog post form" Claude: "I'll create an API route to handle validation..." You: [sighs] "We use server actions, remember?"

With CLAUDE.md (Every Session)

You: "Add a form to create a new blog post" Claude: "I'll create a server action in app/actions/posts.ts with zod validation and use Tailwind for the form styling..." You: "Perfect."

That's the power of persistent memory.

When NOT to Use CLAUDE.md

CLAUDE.md isn't always necessary. Skip it for:

• Quick prototypes - If you're just testing an idea for an hour
• Tutorial projects - Following a guide that provides all context
• Single-file scripts - No need for project memory on a standalone script

But for any project you'll work on more than once, CLAUDE.md pays for itself immediately.

Getting Started Checklist

Ready to add CLAUDE.md to your workflow? Here's your action plan:

• Run /init in your current project
• Review the generated CLAUDE.md and refine it
• Commit project-level CLAUDE.md to Git
• Create user-level CLAUDE.md in ~/.claude/ for personal preferences
• During your next session, notice what Claude remembers vs what you need to explain
• Update CLAUDE.md when you correct Claude on conventions
• Add doc references with @ symbol for key project files

Related Reading on ExplainX

• What is MEMORY.md? The Long-Term Brain for AI Agents - Deep dive on the broader agent memory pattern
• DESIGN.md: the open spec that teaches AI design intent - How to give Claude semantic design system knowledge
• What are agent skills? A complete guide - Understanding SKILL.md and reusable workflows
• What is MCP? Model Context Protocol explained - How agents connect to tools and data

Bottom Line

CLAUDE.md is the difference between treating Claude Code as a chatbot and treating it as a teammate.

Without it, every session starts from zero. With it, Claude remembers your stack, follows your conventions, and works the way you work.

The investment is 5 minutes to run /init and refine the output. The return is never having to re-explain your project again.

If you're using Claude Code on a real project, you owe it to yourself to add CLAUDE.md today.

Explore CLAUDE.md in action: Check out explainx.ai's open-source codebase to see how we use project-level and user-level memory files in production.