How does Claude Code remember project instructions across a session?

Claude Code documentation explains that Claude Code uses a combination of persistent instruction files and conversation context to remember project-specific guidance during a session.

Here's how it works:

1. CLAUDE.md files (Project Memory)

Claude Code automatically looks for CLAUDE.md files in your project directory. These files act as persistent instructions that are loaded into the model's context.

Typical contents include:

• Coding standards and style guides
• Build and test commands
• Project architecture notes
• Team conventions
• Preferred workflows

For example:

# CLAUDE.md

## Commands
- npm test
- npm run lint

## Conventions
- Use TypeScript strict mode.
- Prefer functional React components.

## Architecture
- API routes live under src/api.
- Shared utilities are in src/lib.

As long as you're working inside that repository, Claude Code continues using these instructions across prompts in the same session.

2. Conversation Context

Within a session, Claude Code also remembers information that has already appeared in the conversation, such as:

• Previous code changes
• Decisions you made
• Temporary instructions you gave
• Files it recently inspected

This memory is bounded by the model's context window. If the session becomes very long, older details may eventually be compressed or dropped.

3. Hierarchical Instruction Loading

Claude Code can load instructions from multiple locations, typically with more local instructions overriding broader ones. For example:

~/CLAUDE.md           ← personal defaults
project/CLAUDE.md     ← repository instructions
project/subdir/CLAUDE.md ← feature-specific instructions

When working in a subdirectory, Claude Code combines the applicable instruction files to build its understanding of the project.

4. Session vs Persistent Memory

It's important to distinguish between two kinds of memory:

If you close Claude Code and reopen it later, the conversation history is gone, but the CLAUDE.md files are loaded again, so project instructions remain available.

5. Best Practice

Many teams treat CLAUDE.md like a repository configuration file:

repo/
├── CLAUDE.md
├── README.md
├── package.json
└── src/

This makes project conventions explicit, version-controlled, and automatically available to Claude Code whenever someone works in that repository.

In short, Claude Code doesn't have unlimited long-term memory of your project. It "remembers" instructions primarily by reloading CLAUDE.md files into the context and maintaining conversational state during the active session.