Enhance Memory System to Discover `CLAUDE.md` Context in Subdirectories

Title: Enhance Memory System to Discover CLAUDE.md Context in Subdirectories

Labels: enhancement, feature-request, memory-system

Problem Statement

Currently, Claude Code's memory system (CLAUDE.md) discovers context by recursing up the directory tree from the current working directory (CWD). As stated in the documentation (en/docs/claude-code/memory.md):

Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory / and reads any CLAUDE.md or CLAUDE.local.md files it finds.

This is effective for loading project-level and parent-level context. However, it does not automatically discover and load contextual information defined in subdirectories below the CWD.

In large projects and monorepos, it's common to have specific context (CLAUDE.md files) located within individual component, service, or package directories. To load this context, a user must currently start the CLI from within that specific subdirectory, which is not always practical. The current system discovers context in subtrees only when the agent actively reads a file within that subtree, rather than proactively loading it based on the user's location.

Proposed Solution

We propose enhancing the memory system to traverse downward into subdirectories from the CWD, creating a truly hierarchical and adaptive context. As a user navigates into a specific component's directory within a monorepo, Claude Code would automatically load that component's local CLAUDE.md in addition to the parent and project-level context files.

This would make the agent significantly more intelligent and context-aware in large projects, as its knowledge would automatically become more specific without requiring the user to restart the CLI or manually reference files with @.

Reference Implementation

A great example of this behavior exists in the Google Gemini CLI. Its documentation (google-gemini-gemini-cli/docs/cli/configuration.md) describes a hierarchical loading system that includes sub-directory discovery:

3. Sub-directory Context Files (Contextual/Local): The CLI also scans for the configured context file in subdirectories _below_ the current working directory... This allows for highly specific instructions relevant to a particular component, module, or subsection of your project.

Their implementation appears to use a Breadth-First Search (BFS) to efficiently scan subdirectories, as seen in google-gemini-gemini-cli/packages/core/src/utils/bfsFileSearch.ts and orchestrated by memoryDiscovery.ts.

Suggested Implementation Details

1. Retain Upward Traversal: The system should continue its current behavior of searching upwards from the CWD to the project root to load parent context.
2. Implement Downward Traversal: From the CWD, a downward search (e.g., BFS) should be initiated to find CLAUDE.md files in subdirectories.
3. Combine Context: The contents from all found files (global, upward from CWD, CWD, and downward from CWD) should be concatenated and provided to the model, perhaps with headers indicating the source file for clarity.
4. Performance: The downward search should be optimized for performance by:

• Ignoring common large/irrelevant directories (e.g., .git, node_modules, dist, build).
• Potentially implementing a configurable maximum search depth (memoryDiscoveryMaxDirs).

This enhancement would be a powerful improvement to Claude Code's contextual understanding and would greatly improve the developer experience in complex codebases.