A claim about CLAUDE.md in Claude Projects has been going around AI carousels for the past few weeks: save a CLAUDE.md file with your brand rules in it, and Claude will re-read it at the start of your next session. The instruction usually sits at the end of a numbered workflow, right after the step telling you to sign up for Pro.
We ran it on September 7, 2026. The behavior it describes is real. The mechanism it describes is not, and the file name — the one thing the entire instruction hangs on — does nothing at all.
That gap matters more than it sounds. A setup that works for a reason you got wrong keeps working right up until the day you move it, and then it breaks in a way you cannot debug, because the model in your head predicts something the system never did.
What we tested: CLAUDE.md in Claude Projects, side by side
Two fresh projects on claude.ai, identical in every respect except the name of the uploaded file. Project instructions left empty in both, so we were testing the file and nothing else. Model: Opus 5 in every session.
| Project A | Project B | |
|---|---|---|
| File name | CLAUDE.md |
notes.txt |
| Size and type badge | 141B, MD | 138B, TXT |
| Codename inside | Falconridge | Kestrelbank |
| Rule inside | End every reply with TOKEN-A7Q2 | End every reply with TOKEN-B4M8 |
Each file held four lines: a heading, a codename, a hex color, and one behavioral rule telling Claude to end every reply with a specific token. The token is the whole point of the design. It is a rule that nothing in an ordinary question would ever call for, so if it shows up anyway, the file is being applied as an instruction rather than consulted as reference material. Those are two different things, and the difference is the article.
Three prompts per project. First, a question with no connection to the file: write two sentences on why checklists reduce errors. Second, in the same chat: what is the internal codename of this project? Third, the checklist question again, word for word, in a brand new chat inside the same project.
The predictions, written before the first prompt
We write predictions down first because otherwise the explanation quietly reshapes itself around whatever happened, and you end up with a story instead of a result. Ours were:
- File name and extension are irrelevant; both projects behave identically.
- The codename is retrieved correctly in both, with a visible search step.
- The behavioral rule is not applied to a question that does not call for it.
- A new chat behaves like the first, with no accumulation between them.
Prediction 3 was the interesting one, and it was wrong.
What happened
The token appeared in six replies out of six. Two projects, four chats, every single answer — including the checklist question, which contains no reference to tokens, codenames, brand rules, or the file itself.
notes.txt. The second question retrieves the codename from that same file. Neither reply shows a search step, only a thinking indicator.| Prediction | Result |
|---|---|
| Name and extension irrelevant | Confirmed |
| Codename retrieved, with a visible search step | Half wrong: retrieved, no search step |
| Rule not applied to an unrelated question | Wrong: applied 6 times out of 6 |
| New chat behaves like the first | Confirmed |
The codename came back correctly in both projects: Falconridge in A, Kestrelbank in B. And the two files behaved identically, despite one being Markdown named exactly as the advice prescribes and the other being a plain text file with an unremarkable name.
Prediction 2 was half wrong in a way worth recording. The fact was retrieved, but there was no visible search step in any of the six replies. No line announcing a lookup in project knowledge, nothing. Only a short thinking indicator, which is reasoning, not retrieval. At 141 bytes and 1% of project capacity, the file was almost certainly loaded whole rather than searched — though that part is inference, and we are flagging it as inference rather than smuggling it in.
Prediction 4 held. In the second chat of each project, the token reappeared and the wording of the answer was different from the first chat. Not a cached response: the file entered context again, in a session that had never seen the previous one.
One confounder, ruled out on screen
Claude’s memory is on by default, and each project keeps its own, separate from your non-project chats. That is a genuine alternative explanation for the second-chat result, so we checked it instead of arguing around it: at the end of the whole run, the memory panel in both projects still said the project memory would appear there after a few chats. Empty, in both. The behavior came from the file.
notes.txt, 138 bytes, plain text. Two separate chats sit under Recent, and memory is still empty — so nothing here came from project memory.What this proves, and what it does not
It proves that a file sitting in a project’s context is applied as an instruction, not merely offered as reference material, and that this survives into sessions that share no history with each other. It proves that the file name and extension are decorative on claude.ai.
It does not prove that anything you write in a project file will always be followed. We used a single rule, stated in unmistakable imperative form, trivial to execute and impossible to misread. A page of nuanced style guidance is a different test with a different answer, and we have not run it.
It also tells you what the system does, not how it does it. We can see the effect. We are inferring the loading mechanism from file size and from the absence of a search step, and those are two clues, not a proof.
So the advice is right after all?
About the outcome, yes. About the reason, no — and the reason is the part that will eventually cost someone an afternoon.
On claude.ai the file is loaded because of where it sits. Anything you upload to a project’s knowledge is used across every chat in that project, and context does not otherwise carry from one chat to another inside the same project unless you put it in there. That is stated plainly in Anthropic’s help center article on projects. The name on the file is a label for you. Call it pippo.txt and nothing changes, which is exactly what Project B showed.
In Claude Code, the name is the entire mechanism. Claude Code reads CLAUDE.md and it does not read AGENTS.md; the memory documentation tells repositories that already use the latter to create a CLAUDE.md that imports it, precisely because the file name is what causes the content to load at all.
Same file, same four lines inside, two opposite rules about what makes it load. Anyone who learned the behavior on claude.ai and carries the explanation into a repository is holding a model that predicts the wrong thing, and they will find out on the day it matters.
The question nobody’s carousel answers
Here is what actually matters once your setup contains more than one file: what happens when you change machines, hand the repository to someone else, or move between surfaces.
Anthropic publishes this, and it is the most useful table in the whole documentation set — it lives in the page that walks through the .claude directory file by file, with a column stating which files you commit. For Claude Code, project-scope files live in your repository — at the root for CLAUDE.md and .mcp.json, otherwise under .claude/ — while global-scope files live in ~/.claude/ and never leave the machine they were written on.
| What | Where it lives | Travels with the repo |
|---|---|---|
| Project instructions | CLAUDE.md or .claude/CLAUDE.md |
Yes |
| Topic rules | .claude/rules/*.md |
Yes |
| Permissions and hooks | .claude/settings.json |
Yes |
| Team MCP servers | .mcp.json, at the repo root |
Yes |
| Skills | .claude/skills/<name>/SKILL.md |
Yes |
| Subagents | .claude/agents/*.md |
Yes |
| Subagent memory, project scope | .claude/agent-memory/<name>/ |
Yes |
| Your personal overrides | .claude/settings.local.json |
No, gitignored |
| Your personal MCP servers | ~/.claude.json |
No |
| Auto memory | ~/.claude/projects/<project>/memory/ |
No, machine-local |
Bookmark that one. It answers the migration question in a single glance, which is more than most threads on the subject manage in twenty slides.
“Memory” is three different addresses
One widely shared infographic listed six pieces of a Claude Code project — CLAUDE.md, settings.json, .mcp.json, commands/, skills/, agents/ — and then added “memory” in the caption, with no path, as though it were a seventh file everyone had forgotten to draw.
It is not one thing. It is three, and they have opposite fates:
- Auto memory, the notes Claude writes for itself, stored under
~/.claude/projects/. An index file is loaded at the start of every session, capped at the first 200 lines or 25KB, whichever comes first, with topic files read on demand. It is machine-local, and the documentation is explicit that these files are not shared across machines or cloud environments. Your colleague will never see it. - CLAUDE.md, the instructions you write yourself. Already in the list, under its own name. There is no separate “project memory” system hiding behind it.
- Subagent memory, a separate directory per subagent, switched on by a frontmatter field. At project scope it lives inside
.claude/and is meant to be shared with the team; at local or user scope it goes somewhere that is not committed.
So the infographic is accidentally half right. Auto memory genuinely has no place in a repository tree, which is why it could not be drawn there. Subagent memory does have a place there, and it was the one worth showing.
The part about skills that keeps getting left out
A separate post making the rounds promotes a collection of open-source skills — 148 of them, by the poster’s count, which we have not verified independently — with the pitch that they are free and you can install the lot.
Free to download is not free to run. Anthropic documents the loading model plainly in its skill authoring guidance: at startup, only the name and description from every installed skill’s frontmatter are pre-loaded into the system prompt, and the body of a skill is read only when it becomes relevant. That design is genuinely efficient, and it is the reason large skill libraries are viable at all. It is also the same design that governs the skills already sitting in your account before you install anything, which we counted in an earlier guide.
But “only the metadata” is not “nothing.” The description field is capped at 1,024 characters. At that ceiling, 148 descriptions come to roughly 150,000 characters, which lands somewhere near 38,000 tokens before you have typed a single word. Written tightly — the examples in Anthropic’s own guidance run around 150 to 200 characters — the same 148 come to something closer to 7,000. We are giving you a range because a range is what the documentation supports. We did not measure a live installation, and we are not going to dress a calculation up as a measurement.
The stronger argument is not the token bill anyway. That same page says outright that the description is what Claude uses to choose the right skill from potentially more than a hundred available, and it warns that your skill shares the context window with every other skill’s metadata. Install 148 and you have not simply added weight. You have made the selection problem harder for every request you make, including the ones no skill should ever touch.
Install the ones you use. The library is a catalog, not a starter pack.
What to do with this
If you work on claude.ai, put your standing rules in the project’s instructions field or in a file in the project’s context, and stop worrying about what the file is called. Both work. Neither depends on a magic name. Keep in mind that memory is a third mechanism running alongside those two, on by default, kept separately for each project — and that projects themselves are available on the free plan, up to five, alongside artifacts, so the paid upgrade some of these workflows open with is not the prerequisite they claim it is.
If you work in Claude Code, the name is load-bearing, and the committed-versus-local split above is the thing to internalize before your setup grows large enough to hurt.
If you move between the two, nothing carries over. Not the file, not the memory, not the skills. They are different systems that happen to share a vocabulary, which is exactly why the carousels keep blending them into one. The same confusion shows up in what people expect connectors to cost and to cover, which is why we keep a running account of what these setups really cost and why we counted the connector directory instead of trusting the summaries.
How we sourced this
We separate three registers, and we label them, because “we tested” has become a decorative phrase in this corner of the internet.
Proved — run on September 7, 2026, screenshots above: the six-out-of-six token result across two projects and four chats; the identical behavior of CLAUDE.md and notes.txt; the repeat in a fresh chat with different wording; the absence of a visible search step; the empty memory panel in both projects at the end of the run.
Documented — read from Anthropic’s own documentation and help center on the same date, and linked above where each claim is made: how project knowledge is shared across the chats of a project and how context is not otherwise shared between them; that projects are available on the free plan up to five; that Claude Code reads CLAUDE.md rather than AGENTS.md; the committed-versus-local file table; the three memory locations and their loading limits; and the skills metadata model with its 1,024-character description cap.
Reasoned — the 7,000-to-38,000 token range for 148 installed skills, and the inference that a 141-byte file is loaded whole rather than searched.
One closing note on the same workflow that started this. It names Opus 4.7 as the model to use. That model is real — it appears in Anthropic’s documentation under legacy models — but the current Opus-tier model is Opus 5, released in July 2026. Two generations of drift in a post from last week is its own kind of tell, and a useful one: it tells you when the workflow was actually written, whatever date it was posted.
The MCP Playbook
One page per connector: what it does, what it really costs, what breaks. Plus the decision tree for choosing between an MCP server, a skill, or neither, and complete stacks for a solo creator, a small shop, a consultant, and a small agency.
You Might Also Like
More guides on what Claude’s tooling actually does, counted and checked rather than repeated.
Related Posts
