Claude Code Memory vs CLAUDE.md: What's the Difference?

Claude Code memory vs CLAUDE.md is not a choice between two competing features. They operate at different layers and serve completely different purposes. One is temporary working memory; the other is a persistent project brief that survives every session end.

Understanding which layer does what determines where you put your project context, why some instructions persist across sessions and others do not, and why the same input can produce different results in different sessions.

Key Takeaways

• In-session memory is the context window: Everything Claude Code reads, receives, and decides in a session disappears when the session ends, no exceptions.
• CLAUDE.md is persistent file-based memory: It is read at the start of every session and gives Claude Code the project context it would otherwise re-learn each time.
• They serve different purposes: Persistent conventions, commands, and architecture notes go in CLAUDE.md. Task-specific or one-time instructions stay in the session.
• CLAUDE.md reduces repetitive prompting: The file handles context that never changes; the session handles context specific to today's task.
• Session memory can be managed with /compact: This reduces the context footprint of a long session without ending it, preserving recent context while compressing earlier content.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What Is Claude Code's In-Session Memory?

In-session memory is the context window: the total of everything Claude Code has seen, read, and been told since the current session started. When the session ends, all of it is discarded.

It accumulates across the session. Every file read, every prompt, every response, and every instruction adds to the context window up to the 200K token limit.

• Context window contents: The full conversation history, all file contents read in the session, mid-session instructions, and decisions made earlier in the task.
• Session end means total reset: Claude Code starts the next session with no knowledge of what happened in this one, beyond what is written in CLAUDE.md.
• Context window fill causes contradictions: When the window fills, Claude Code drops earlier context to accommodate newer content, causing it to ignore earlier constraints.
• The visible sign of an overfull session: Claude Code starts contradicting decisions it made earlier in the same session, which is a reliable signal the context window needs management.
• File reads consume significant tokens: Reading large files early in a session limits how much room remains for later tasks, so read files close to when you need them.

For managing in-session memory when sessions grow long, using /compact and /clear correctly is the key: /compact summarises without discarding, /clear resets entirely.

What Is CLAUDE.md and How Does It Create Persistent Memory?

CLAUDE.md is a plain Markdown file placed at the project root that Claude Code reads automatically at the start of every session. It survives session ends, computer restarts, and updates because it is a file on disk, not data in a model.

The persistence comes from the file itself. Unlike the context window, CLAUDE.md does not disappear when you close the terminal or switch machines.

• Read before any user prompt: Claude Code loads CLAUDE.md before the first prompt of each session, making it the highest-priority context input.
• What to put in it: Tech stack and version, development commands, architectural conventions, naming patterns, and anything Claude Code should know from session one.
• The effect is practical: It is as if you typed all of your project context at the start of every session, without actually having to type it.
• Multiple CLAUDE.md files are supported: A project root file sets global context; subdirectory files can add component-specific or feature-specific context on top.
• Deletion breaks the persistence: If the file is deleted or contains wrong information, the memory is gone or wrong. CLAUDE.md works because Claude Code reads it, not because it is stored anywhere else.

For the complete guide to CLAUDE.md covering what to put in it, how to structure it, and the three-scope system, that guide covers the file in full depth.

What Is the Key Difference Between the Two?

In-session memory is ephemeral: it lives for one session, then disappears. CLAUDE.md is persistent: it lives as a file and reloads at the start of every session. One is today's working notes; the other is the standing brief.

The distinction is not subtle. Confusing the two causes real problems in both directions.

• CLAUDE.md is for what is always true: Tech stack, development commands, architectural rules, naming conventions, and patterns that apply to every session on this project.
• In-session memory is for what is true today: Task-specific context, one-time instructions, and decisions that apply only to the current working session.
• Wrong direction one: Putting task-specific instructions in CLAUDE.md causes them to persist incorrectly and override appropriate behaviour in future sessions.
• Wrong direction two: Relying on session memory for permanent conventions means re-explaining them at the start of every session.
• The overlap zone: An instruction given mid-session that reveals a permanent project convention belongs in CLAUDE.md after the session. The session is where you discover it; the file is where you record it.

Which One Should You Use for a Specific Piece of Context?

Apply the persistence test: Will this instruction be true tomorrow, next week, and for every Claude Code session on this project? If yes, it belongs in CLAUDE.md. If it applies only to this task, keep it in the session.

The persistence test resolves almost every ambiguous case. When you are unsure, ask whether you would want Claude Code to follow that instruction in six months on a different task.

• CLAUDE.md candidates: Tech stack and version, build and test commands, architectural rules ("never put database queries in route handlers"), and naming conventions.
• Session-only candidates: "Skip error handling for this task and focus on the logic first" are instructions that would be wrong to apply in every future session.
• The override pattern: CLAUDE.md establishes defaults; session prompts can override them for specific tasks without changing the permanent record.
• The repetition signal: If you type the same context-setting instruction at the start of multiple sessions, that instruction belongs in CLAUDE.md.
• The discovered-convention problem: When a session reveals a pattern that works well, add it to CLAUDE.md after the session rather than re-explaining it in every future session.

For CLAUDE.md examples by project type showing exactly what the persistent layer looks like for different stacks, those annotated examples make the distinction concrete.

How Do They Work Together in Practice?

CLAUDE.md loads at session start with permanent project context. The session prompt adds task-specific context on top. Together, Claude Code has both what it always needs and what it needs for today's task.

The two layers are designed to complement each other. Neither is a substitute for the other; both are required for consistent output across a multi-session project.

• The session start sequence: CLAUDE.md loads automatically, then the user opens with a task-specific prompt that adds the work for today.
• A working example: CLAUDE.md contains "Next.js App Router, TypeScript, pnpm, run tests with pnpm test" and the session opens with "I am adding a billing webhook; read /src/services/billing.ts first."
• Layering is the model: CLAUDE.md provides permanent context; the session prompt adds the task-specific layer on top without replacing the permanent layer.
• The end-of-session maintenance habit: Spend two minutes after each significant session reviewing whether any decisions or patterns discovered should be added to CLAUDE.md.
• CLAUDE.md evolves over time: A well-maintained file grows from a starting-point stub into a comprehensive project brief that makes every future session faster.

For larger projects where managing context across sessions is an active challenge, the strategies for large codebase context management build directly on this two-layer model.

Conclusion

In-session memory and CLAUDE.md are not competing features. They are complementary layers of a single system. Session memory handles what is true now; CLAUDE.md handles what is always true.

Developers who get consistent output from Claude Code maintain both deliberately: a current CLAUDE.md for the permanent layer, and clear task-scoping at session start for the ephemeral layer. Review your CLAUDE.md now and ask whether anything you explain in the first prompt of most sessions is missing from the file. If it is, add it.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Want Claude Code to Work Consistently Across Your Whole Team?

Inconsistent Claude Code output is almost always a configuration problem, not a model problem. When different team members start sessions without shared context, or when CLAUDE.md is missing or out of date, every developer gets a different version of the same tool.

At LowCode Agency, we are a strategic product team, not a dev shop. We configure the CLAUDE.md architecture, session management patterns, and memory layer setup for teams where consistent Claude Code output matters and ad-hoc session management is not reliable enough at scale.

• CLAUDE.md architecture design: We structure the project-level, component-level, and feature-level CLAUDE.md files so every team member starts each session with the same context.
• Session management patterns: We define the task-scoping conventions your team uses so Claude Code receives consistent, effective instructions across every developer.
• Convention documentation: We translate your codebase's architectural decisions and naming patterns into CLAUDE.md entries that Claude Code can apply reliably.
• Onboarding setup: We configure CLAUDE.md so new team members get accurate project context from Claude Code on day one without requiring manual explanation.
• Context maintenance workflow: We set up the end-of-session review process that keeps CLAUDE.md current as the project evolves.
• Multi-codebase configuration: We handle projects with multiple repositories or monorepo structures where context needs to be layered across scopes.
• Full product team: Strategy, UX, development, and QA from a single team that treats your AI tooling configuration as part of the product, not an afterthought.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want Claude Code working consistently across your whole team from the first session, talk to our team about how we set it up.