[BUG] CLAUDE.md files in subdirectories are not being automatically loaded

Proof:

!Image

!Image

Here's a simple script to reproduce.

TMP_DIR="$(mktemp -d)" # Create a temporary directory
cd "$TMP_DIR"

mkdir test
echo "echo" > ./test/run.sh

echo "My Name is AA" >CLAUDE.md # Project-wide
echo "My Name is BB" > ./test/CLAUDE.md # Directory-specific

claude -p "Print @./test/run.sh. What is my name?" # Should answer "BB", however the result is:
# Here's the content of `./test/run.sh`:
# 
# ```bash
# echo
# ```
# 
# Your name is AA (as specified in the CLAUDE.md file).

claude -p "What is my name?" # Should return "AA"
# Based on the CLAUDE.md file in your project, your name is **AA**.

Ran similar tests to those outlined above and came to the same conclusion. Any updates here? This is a really critical piece of functionality for monorepo style codebases where you run claude code from the root directory.

My temporary workaround is to simply reference the nested claude.md files within the root claude.md. This loses the dynamic loading functionality (less context efficiency) but for now this is working okay for me.

Agree. I am hoping though that the new subagents functionality reduces the need for this.

I want to add some clarity to this ticket.

Claude Code _DOES_ in fact load CLAUDE.md files in subdirectories whenever it invokes the Read() tool to read a file (e.g. if you say "Please inspect ./path/to/file and tell me how many lines it contains").
HOWEVER, if the user uses @path/to/file within their prompt to inject the file into the context, it WILL NOT have the same behavior.

This is unexpected and contrary to what the documentation would suggest and I believe it qualifies as a bug.

I currently get around this by specifically telling Claude to gather sub-directory context where I know it exists. (e.g. "if I ask you about anything in path/to directory, ALWAYS read path/to/CLAUDE.md first if you do not have it in your context window")

@mikegreiling Thenk you for the analysis. However when I tested the behavior, it does not read the subdirectory CLAUDE.md file whether I mention the file or not.
At least in 1.0.72.

This is the test script I used. I hope this can help CC team to reproduce the issue.

claude --version
# 1.0.72 (Claude Code)

TMP_DIR="$(mktemp -d)" # Create a temporary directory
cd "$TMP_DIR"

mkdir test
echo "echo" > ./test/run.sh

echo "My Name is AA" >CLAUDE.md # Project-wide
echo "My Name is BB" > ./test/CLAUDE.md # Directory-specific


# === Subdirectory CLAUDE.md behavior ===
# Claude should read the ./test/CLAUDE.md file and answer "BB" as the name, but it answers "AA" instead.
# ===

claude -p "Read ./test/run.sh and tell me how many lines it contains. Plus, what is my name?" # WITHOUT mentioning the file.
# The file `./test/run.sh` contains 2 lines.
#
# Your name is AA (as specified in the CLAUDE.md file).

claude -p "Read @./test/run.sh and tell me how many lines it contains. Plus, what is my name?" # WITH mentioning the file.
# The file contains 2 lines, and your name is AA.


# === Root CLAUDE.md behavior ===
# Claude should answer "AA" as the name and it does.
# ===

claude -p "What is my name?"
# AA


# === Test on reading CLAUDE.md explcitly ===
# Just for sure
# ===

claude -p "Read ./test/CLAUDE.md and tell me how many lines it contains. Plus, what is my name?"
# The file `./test/CLAUDE.md` contains **2 lines**.
#
# Based on the main CLAUDE.md file in the root directory, your name is **AA**. However, the test/CLAUDE.md file shows a different name "BB", which appears to be test data.

Just tested and same behaviour (running 1.0.79 version.

The behaviour I see matches @mikegreiling's.
The problem is with the @ mentions not including the CLAUDE.md's along the path.

I have a gist with a workaround.
TL;DR; just tell Claude on the root CLAUDE.md about this bug and that it needs to manually perform the reads anyway.

Note: if you use the gist, remember to restart claude for the new root CLAUDE.md to be picked up.

@icorderi could this not be enforced in a hook? I am not sure if AI reading the topmost CLAUDE.md file triggers a PreToolUser:Read event but if so the mentioned files could be easily injected into context?

@zonofthor would a hook allow conditional behaviour? i.e. applying the instructions of a nested CLAUDE.md only when the directory containing that file is accessed?

By the way, Claude Code team: amazing work, but there are almost a handful issues for this exact same problem. It is a serious loss of potential productivity.

@zonofthor I had a version using hooks. You can set it up that way if you prefer. I didn't like the extra hook entries in my history logs. So I went with the CLAUDE.md approach.

The approach on my gist does work, it triggers several Read operations, which in turn will trigger the CLAUDE.md scatter around to be loaded.

It's certainly not ideal or optimal since this is doing multiple tool calls.

We should just fix the behavior on Claude Code itself if we can agree that this should be the expected behavior.

Have we heard from the CC team? At this point I'm half tempted to ask Claude to fix it itself and submit a PR.

@icorderi since I was wondering about this last time I have been sold off that this is a good approach i.e. CC loads CLAUDE.md docs downstream. Why? Because it is very very difficult for CC to know what is the right moment to do so for example it may be just doing some minor code change in a sub-folder but where a long CLAUDE.md is overkill and bloats the context.

It feels more like the information contained downstream should be contained in agent (or perhaps command) and the main CLAUDE.md then should focus on instructing _when_ the agent should be invoked.

Just my thoughts. I am currently seeing the downstream CLAUDE.md files being loaded early for each prompt and they are seriously adding up to the context - that is a problem.

Yeah this would be really nice as we have CLAUDE.md files in subdirectories for our backend and frontend, and a lot of engineers didn't realize that the CLAUDE.mds weren't being pulled into context.

Has there been any progress on this? Documentation states that nesting is supported but it's clearly not.

Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees. [​](https://docs.claude.com/en/docs/claude-code/memory#how-claude-looks-up-memories)

Additional Test Case: @ References Not Loading

I can confirm this bug affects the @ reference import feature as well. Here's what I tested:

Setup

Project Structure:

~/workspace/
  └── CLAUDE.md (contains @ references)
  └── config/
      └── app setup/
          └── app setup.md (referenced file with content)

~/workspace-support/
  └── setup-config.md (hard link to config/app setup/app setup.md)

CLAUDE.md contents:

## Configuration
Details in @config/app setup/app setup.md
@~/workspace-support/setup-config.md

Test Method

Started a fresh Claude Code session from ~/workspace/ and asked:

claude -p "Don't read any files. What's in your context?"

Results

❌ Neither @ reference loaded

• Claude could see the references themselves (as plain text in CLAUDE.md)
• Claude explicitly stated: "the actual contents of these files are not included in my current context - only the references/links to them"
• Tested both:
• Relative subdirectory path with spaces: @config/app setup/app setup.md
• Absolute path without spaces: @~/workspace-support/setup-config.md

Conclusion

The @ import mechanism documented at https://docs.claude.com/en/docs/claude-code/memory is completely non-functional. Files are not being expanded/loaded, regardless of:

• Path type (relative vs absolute)
• Path location (subdirectory vs parent/sibling directory)
• Filename format (with or without spaces)

Expected: File contents should be loaded into context at session startup
Actual: Only the @reference text itself is visible; referenced file contents are not loaded

Somewhat related question is, even if it worked, would it supposed to work in this condition?

Let's say you have tests in some subfolders, but they are all generally in some test folder inside of the project.
If you have a memory file talking about how to do tests in the test folder and the clod just touches some test files that are more deeply nested, would it load the clodmd file from the test folder? And is the expectation even correct? I would assume that that's what it should do, because otherwise I don't know how this nested memory files feature would even be useful. ...but I'm no longer sure.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

No, please do not auto close this. The problem still exists and it is still an issue.

btw I started perceving that in some cases they started loading. Just didn't check thoroughly, if it happens consistently on all levels. Has anyone observed it as well? It looks like this:

<img width="508" height="190" alt="Image" src="https://github.com/user-attachments/assets/19a4d2c5-eeec-4d47-b264-0c0413d084d9" />

it was reading some file far down the pathway, but loaded the memory file that was one level deeper than root "along the way"

Finally found CCs biggest limitation, felt like magic before running into this issue.

@chvainickas are you sure? I had run some tests and cc now reliably loads them for me. I purposefully made a simple project with 7 nested folders and a memory file that was 5 levels deep and in a new convo had him read sth that was nested on the last level and it loaded the file and did an arbitrary thing that was mentioned in that memory file. I had since started positioning memory files in structures and they all load. For me the problem is no longer reproducible

@mimkorn yes, it seems to still be the case. I've not manually checked by creating my own tests but I just ran https://github.com/anthropics/claude-code/issues/2571#issuecomment-3172506015 test script to reproduce the bug and the bug reproduces. Even in Test 4 where Claude explicitly reads ./test/CLAUDE.md (which says "BB"), it still answers "AA" from the root. The subdirectory CLAUDE.md is being discovered but not given precedence over the root - it's essentially ignored.

cd "$TMP_DIR"

mkdir test
echo "echo" > ./test/run.sh

echo "My Name is AA" > CLAUDE.md
echo "My Name is BB" > ./test/CLAUDE.md

echo "=== Test 1: Read ./test/run.sh WITHOUT @ ==="
claude -p "Read ./test/run.sh and tell me how many lines it contains. Plus, what is my name?"

echo ""
echo "=== Test 2: Read @./test/run.sh WITH @ ==="
claude -p "Read @./test/run.sh and tell me how many lines it contains. Plus, what is my name?"

echo ""
echo "=== Test 3: What is my name? (root) ==="
claude -p "What is my name?"

echo ""
echo "=== Test 4: Explicitly read ./test/CLAUDE.md ==="
claude -p "Read ./test/CLAUDE.md and tell me how many lines it contains. Plus, what is my name?"

echo ""
echo "=== Cleanup ==="
rm -rf "$TMP_DIR"
echo "Done")
⎿  === Test 1: Read ./test/run.sh WITHOUT @ ===
The file ./test/run.sh contains 2 lines (one with echo and one empty line).

Your name is AA (as specified in the project's CLAUDE.md).

=== Test 2: Read @./test/run.sh WITH @ ===
The file test/run.sh contains 2 lines (one with echo and one empty line).

Your name is AA, according to the project instructions in CLAUDE.md.

=== Test 3: What is my name? (root) ===
Based on the project instructions in CLAUDE.md, your name is AA.

=== Test 4: Explicitly read ./test/CLAUDE.md ===
The file ./test/CLAUDE.md contains 2 lines (one with text, one empty).

As for your name: According to the project instructions in /tmp/tmp.mmDAELzqlI/CLAUDE.md, your name is AA.

Bump

@chvainickas @kuroneko0441

I think there's a misunderstanding in how these tests are set up.

The issue with the current tests:

Your tests create contradictory information (name = AA vs name = BB), then expect Claude to pick one. But the nested CLAUDE.md isn't meant to override the root one — both get loaded additively. When faced with "My name is AA" and "My name is BB" simultaneously, Claude has to pick one, and that choice is non-deterministic.

There's no documented precedence rule that says "nested = higher priority." (nor would I want it to work that way, by the way)

A better test:

Instead of contradicting information, test whether both files are actually read:

TMP_DIR="$(mktemp -d)"
cd "$TMP_DIR"

mkdir -p project/src

# Root level - one piece of info
echo "The project codename is FALCON" > ./project/CLAUDE.md

# Nested level - different, non-contradicting info  
echo "The secret password is BUTTERFLY" > ./project/src/CLAUDE.md

echo "print('hello')" > ./project/src/main.py

cd project
claude -p "Read ./src/main.py. What is the project codename? What is the secret password?"

This tests whether information from both files is available — which is the actual intended behavior.

My results:

Running interactively (claude TUI), I get:

The file ./src/main.py just contains print('hello').

  - Project codename: FALCON
  - Secret password: BUTTERFLY

✅ Both memory files loaded correctly.

However, running with -p flag, I get:

The file ./src/main.py contains only print('hello')...

Based on the project's CLAUDE.md file, the project codename is FALCON.

There is no secret password defined anywhere in the files I've seen.

❌ Only the root CLAUDE.md was loaded.

Conclusion:

The nested CLAUDE.md loading works correctly in interactive mode. The bug seems specific to the -p (single prompt) mode.

@RicSala I'd recommend closing this ticket and opening a more targeted one if anyone needs nested memory files to work with the -p argument specifically.

Can confirm this is also an issue with the VS Code extension:

<img width="1339" height="447" alt="Image" src="https://github.com/user-attachments/assets/b6725441-bbab-4582-af49-bae4caa31ced" />

I do get the secret password back when I use the CLI.

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

This issue was auto-closed due to inactivity but the bug is still present as of v2.1.39 (VS Code extension on Linux/WSL2).

I've filed a new issue with a detailed reproduction case and session evidence: #24987

Subdirectory CLAUDE.md files are still not loaded on-demand when reading files in those directories via the Read tool.

This issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.

Thanks, I Did!

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.