Claude Code Memory Files: Global vs Project Level.md files
You’ve set up Claude Code. You’re running it from the terminal or the Desktop App’s Code tab. Things are working. But then you hear about something called CLAUDE.md — a file that lets Claude remember things about you and your projects between sessions.
Sounds great. But here’s where most people get stuck: there are actually two types of CLAUDE.md files, and they work very differently.
Let’s break it down.
Learn Claude, Clawd or Molt can wait
What Is a CLAUDE.md File?
Think of CLAUDE.md as a cheat sheet you write for Claude. Every time Claude Code starts a new session, it reads this file first — before you even type anything.
It’s where you put things like your preferences, your project rules, your folder structure, or lessons you’ve learned from past sessions. Instead of repeating yourself every time, you write it once, and Claude just knows.
The catch? There are two places you can put this file, and each one has a different scope.
The Global CLAUDE.md
Location: ~/.claude/CLAUDE.md
This is your master file. It sits in your home directory and applies to every single Claude Code session, no matter what project folder you’re working in.
This is the right place for things that are true across all your work. Your general preferences. How you like explanations broken down. Your folder structure. Your formatting style. The kind of developer you are.
For example, you might put something like this in your global file:
“Always explain code step by step. I store active projects in ~/projects/active/ and experiments in ~/projects/playgrounds/. I prefer Tailwind CSS over custom stylesheets.”
Every time you open Claude Code — whether you’re working on your personal website, a client project, or a random experiment — Claude will already know these things about you.
The Project Level CLAUDE.md
Location: Inside a specific project folder, like ~/projects/active/my-website/CLAUDE.md
This file only loads when you’re working inside that particular folder. Claude ignores it completely when you’re in any other project.
This is where you put context that only matters for one project. The tech stack. What broke last time. Which files are sensitive. Deployment instructions. Project specific lessons you’ve learned the hard way.
For example, a project level file might say:
“This site uses Next.js with Tailwind. The header component is fragile — don’t change its display or position properties. Last time we edited the nav, it broke the mobile layout. Always test on mobile before committing.”
That kind of detail is gold when you’re deep in a project, but it would just be noise in every other session.
The Key Differences at a Glance
Feature
Global CLAUDE.md
Project Level CLAUDE.md
Location
~/.claude/CLAUDE.md
Inside any project folder
When it loads
Every Claude Code session
Only when working in that folder
Scope
All projects, all sessions
One specific project only
Best for
Personal preferences, general rules, folder structure, coding style
Project specific context, tech stack, past bugs, deployment notes
Example content
“I prefer step by step explanations”
“This site uses Next.js with Tailwind”
Shared with Code tab?
Yes — same engine, same file
Yes — if opened from the same folder
Who should use it
Everyone using Claude Code
Anyone with recurring projects
So Which One Should You Use?
The honest answer? Both.
Your global file is where you put the things that make Claude feel like it already knows you. Your preferences, your style, your working habits. This file turns Claude from a stranger into a colleague who remembers how you work.
Your project level files are where you put the things that make Claude effective inside a specific codebase. The context. The history. The “don’t touch that” warnings that save you from repeating past mistakes.
Here’s a simple rule of thumb: if the information is about you, it goes in global. If the information is about the project, it goes in the project folder.
Can You Use Both at the Same Time?
Yes. Claude Code reads both files when you start a session inside a project folder. The global file loads first, then the project level file layers on top of it.
So if your global file says “always explain things step by step” and your project file says “this site uses WordPress with a custom theme,” Claude will do both. It’ll explain things your way while also knowing the specific tech stack you’re working with.
A Practical Example
Let’s say you have two projects: a personal blog and a client’s e‑commerce site.
Your global ~/.claude/CLAUDE.md might include:
You prefer concise code comments
You store active projects in ~/projects/active/
You like Montserrat font for documents
You want Claude to always confirm before running destructive commands
Your blog’s ~/projects/active/my-blog/CLAUDE.md might include:
Built with Astro and Markdown
Deployed via Netlify
The RSS feed template is custom — don’t overwrite it
Images go in /public/images/blog/
Your client’s ~/projects/active/client-store/CLAUDE.md might include:
Built on Shopify with a custom Liquid theme
Never push directly to main branch
The checkout flow was customised — check with the client before modifying
Staging URL and credentials for testing
Each project gets its own brain, while your global preferences carry across everything.
The Most Important Thing to Remember
These CLAUDE.md files only work with Claude Code (terminal) and the Code tab in the Desktop App. They share the same engine and read the same files.
The Chat and Cowork modes in the Desktop App? They have their own separate .claude folder and do not read your CLAUDE.md files. That’s the same “gotcha” from the previous article — and it still catches people out.
Getting Started
If you haven’t created a CLAUDE.md file yet, start with the global one. Open your terminal and run:
nano ~/.claude/CLAUDE.md
Write a few lines about how you work. Your preferences. Your folder structure. Save it.
Next time you open Claude Code, it’ll feel like picking up a conversation with someone who already knows you. That’s the whole point.
And when you start a new project, drop a CLAUDE.md file into the project folder with the specifics. Future you will thank present you for it.