Claude Code has two distinct context systems, and mixing them up leads to confusion: instructions that seem permanent get lost, or context you expected to be fresh is still carrying over from an earlier session.
This guide explains exactly what each system does and how they work together.
Session Memory: Temporary Context
Session memory is everything Claude Code learns and builds up during a single conversation. This includes the files it has read, the instructions you have given, the decisions made mid-session, and the conversation history itself.
Session memory is temporary. It exists for the duration of the session and is discarded when you run /clear or start a new Claude Code session.
It does not persist to disk. It lives only in the context window.
Think of session memory as a whiteboard. Everything you write on it is visible during the meeting. When the meeting ends, the whiteboard is erased.
What Session Memory Contains
- Every prompt you have sent and every response Claude Code has given
- The contents of files Claude Code has read during the session
- In-session instructions like “for this session, prefer functional style”
- Errors encountered, files created, and changes made during the session
- Context built up through agentic turns (when Claude Code calls tools and processes results)
Session Memory Limits
Session memory is bounded by the context window. As a session grows, older content gets pushed out of the window, which is why long sessions produce less accurate output.
Running /compact compresses the session history into a summary to reclaim context space without losing the important thread.
CLAUDE.md: Persistent Context
CLAUDE.md is a markdown file on disk that Claude Code reads at the start of every session. It is not session memory. It is permanent project context that survives every /clear, every session restart, and every new terminal window.
Because CLAUDE.md is a file, it is always available. The information in it does not age out of a context window.
Every session starts with the same baseline context from CLAUDE.md, which is what makes it the right place for conventions, constraints, and permanent instructions.
CLAUDE.md is the contract you write once that applies to every future session. Session memory is the working notes for the current task.
Two Levels of CLAUDE.md
CLAUDE.md exists at two levels, and understanding which level applies when is important for getting predictable behavior.
Global CLAUDE.md
Location: ~/.claude/CLAUDE.md
The global CLAUDE.md applies to every Claude Code session on your machine, regardless of which project directory you are working in. This is where you put preferences and constraints that should apply universally.
Examples of what belongs in global CLAUDE.md:
- Preferred response format. Concise vs. verbose output style.
- Universal security rules. For example:
never hardcode secrets. - Personal style preferences. For example:
I prefer functional programming patterns. - Cross-project instructions. Anything that applies to all projects you work on.
Project CLAUDE.md
Location: [repo-root]/CLAUDE.md
The project CLAUDE.md applies only to sessions started in that project directory. It is where project-specific context lives: the stack, the conventions, the file structure, and what not to touch.
Claude Code reads the global CLAUDE.md first, then the project CLAUDE.md.
If the two conflict, the project CLAUDE.md takes precedence.
The /memory Command
The /memory command lets you view and edit your persistent memory (CLAUDE.md) without leaving the active session. When you run /memory, Claude Code opens the CLAUDE.md for the current project so you can review and update it in place.
This is most useful when you are mid-session and realize that a convention you have just established, or a mistake Claude Code keeps making, should be captured as a permanent rule.
You update CLAUDE.md via /memory and it takes effect for future sessions without interrupting the current one.
Changes made through /memory are saved to the CLAUDE.md file on disk. They are permanent immediately.
How the Two Systems Interact
The order of operations every session is:
- Claude Code reads the global
CLAUDE.md(~/.claude/CLAUDE.md) - Claude Code reads the project
CLAUDE.md([repo-root]/CLAUDE.md) - Claude Code reads any additional
CLAUDE.mdfiles in parent directories - The session begins and session memory starts accumulating
Session memory is built on top of the CLAUDE.md context. If CLAUDE.md says use CommonJS and you say in the session use ESM for this task, the session instruction takes precedence for this session.
The CLAUDE.md instruction will apply again in the next session.
This layering is intentional. CLAUDE.md sets the default. Session instructions let you override defaults temporarily without changing the permanent context.
When to Use Each
| Situation | Use |
|---|---|
| Your team’s coding conventions | Project CLAUDE.md |
| Your preferred response style | Global CLAUDE.md |
| Files that should never be modified | Project CLAUDE.md |
| A one-off instruction for this task only | Session prompt |
| A convention you just established and want to keep | /memory to add to project CLAUDE.md |
| A security practice for all your projects | Global CLAUDE.md |
| Context specific to this session’s debugging work | Session memory (no action needed) |
The decision rule is simple: if you will need this context again in a future session, put it in CLAUDE.md.
If it only matters for the current task, keep it in the session.
Memory Type Comparison Table
| Memory Type | Persistence | Scope | How to Edit | Lost When |
|---|---|---|---|---|
| Session memory | Temporary | Current session only | Naturally builds up during conversation | /clear or session ends |
| Project CLAUDE.md | Permanent | One project | Edit file directly or via /memory | Never (until you delete it) |
| Global CLAUDE.md | Permanent | All projects on your machine | Edit ~/.claude/CLAUDE.md directly | Never (until you delete it) |
Common Mistakes
Treating session instructions as permanent. If you tell Claude Code use tabs, not spaces in a session and do not add it to CLAUDE.md, the next session will not know this. Instructions given in a session are session memory.
They disappear when the session ends.
Putting session-specific context in CLAUDE.md. If you are debugging a specific issue and add a temporary workaround instruction to CLAUDE.md, it will apply to every future session. Use in-session instructions for temporary context. Use CLAUDE.md only for permanent rules.
Forgetting that /clear also clears session-level instructions. When you run /clear, you lose all in-session instructions. If you gave Claude Code specific instructions at the start of a session, you will need to give them again after clearing.
If those instructions are important enough to need after a clear, they belong in CLAUDE.md.
Using global CLAUDE.md for project-specific rules. If you add a project-specific convention to your global CLAUDE.md, it will apply to all your projects, potentially causing Claude Code to apply inappropriate conventions in the wrong context.
Project rules go in the project CLAUDE.md.
Practical Pattern: Capturing Session Discoveries in CLAUDE.md
A productive workflow that many experienced Claude Code users follow: at the end of a long session, run /memory and review whether any decisions made during the session should be permanently recorded.
The Claude Code course walks through how to build and maintain effective CLAUDE.md files as part of a complete workflow.
- New error handling pattern? Adding it to
CLAUDE.mdtakes 2 minutes and means every future session starts knowing about it. - Fragile file that should not be touched lightly? Add it to a
Do Not Touchsection. - Convention you just standardized? Record it so it does not have to be re-established next session.
The session was the discovery. CLAUDE.md is the record.
This pattern, applied consistently, means your CLAUDE.md gets better with every session rather than staying static.
Get More from Both Systems with Expert Guidance
Phos is a CCA-F certified Claude partner with 400+ AI engagements.
We help engineering teams set up Claude Code effectively, including building CLAUDE.md files that accurately capture your conventions and constraints from day one.
Talk to the Phos team to learn how we help teams use Claude Code’s context systems to their full potential.
FAQ
Does session memory persist if I close the terminal and reopen it?
No. Session memory is lost when the session ends, which includes closing the terminal. When you reopen Claude Code, it reads CLAUDE.md fresh but has no memory of what happened in previous sessions.
Use the --continue (-c) flag when starting Claude Code to resume the most recent session if it ended recently.
Can I see what is currently in my session memory?
Not directly as a dump, but you can run /status for a summary of the current session state, or /compact to see what Claude Code summarizes as the key context from the current session.
The compact summary is a good approximation of what is considered important in the session memory.
If I edit CLAUDE.md mid-session, does Claude Code pick up the changes immediately?
Changes to CLAUDE.md made via /memory apply to future sessions. During the current session, Claude Code has already read CLAUDE.md at startup, so mid-session edits do not automatically update what Claude Code knows in this session.
You can tell Claude Code about the change in your next prompt: I just updated CLAUDE.md to add X. Apply that rule for the rest of this session.
How does /compact interact with CLAUDE.md?
/compact compresses session memory (the conversation history and accumulated context). It does not touch CLAUDE.md. After running /compact, Claude Code continues the session with the compressed summary plus the original CLAUDE.md context it read at startup.
The two systems are independent. Compressing session memory never affects your persistent CLAUDE.md files.