CLAUDE.md Files

The Memory Hierarchy

CLAUDE.md files are Markdown documents that provide high-quality context to the LLM with every request. They exist at multiple levels and form a hierarchy that Claude Code uses to build its understanding of your project.

Upward Discovery

Claude Code automatically discovers CLAUDE.md files by traversing upward from the current working directory. If you are working in a subfolder, it uses the most specific context available while also pulling from parent folders. This means project-level context is always available, and subfolder-specific context is added on top.

Dynamic Memory Imports

CLAUDE.md files can reference other memory files using the @ symbol syntax. This enables modular context that is loaded on demand rather than always being present:

# In any CLAUDE.md file
@path/to/memory/file.md
@./relative/path/context.md
@~/global/user/context.md

Dynamic Context Switching

You can build scripts that dynamically update which context is loaded based on the current Git branch or user query. A hook connected to the UserPromptSubmit event can inject branch-specific or topic-specific context files automatically.

# context-switcher.sh — load context based on git branch
branch=$(git branch --show-current 2>/dev/null)

case $branch in
  "feature/auth-"*)
    add_context "@./context/auth-system.md"
    ;;
  "feature/payment-"*)
    add_context "@./context/payment-flow.md"
    ;;
  "hotfix/"*)
    add_context "@./context/production-hotfix.md"
    ;;
esac