D3 · Claude Code › Cluster 1 · Memory & CLAUDE.md

1.2 · The Memory Hierarchy

Enterprise · project · user · local

CONCEPT Four scopes, loaded broadest → most specific

CLAUDE.md isn't one file — it's a hierarchy of scopes, each living in a fixed location and serving a different audience. All discovered files are concatenated into context (they don't override one another). They load in order from broadest scope to most specific, so more-specific instructions appear later in context — which is how the effective precedence works out for conflicting guidance.

ScopeLocationShared withUse for
Managed policy (enterprise) macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md
All users on the machine Org standards, security & compliance
User~/.claude/CLAUDE.mdJust you (all projects) Personal prefs, tooling shortcuts
Project./CLAUDE.md or ./.claude/CLAUDE.md Team, via source controlArchitecture, standards, workflows
Local./CLAUDE.local.md (gitignore it) Just you (this project)Sandbox URLs, personal test data
🔑 Load order is managed → user → project → local. Managed policy is deployed via MDM / Group Policy / Ansible and cannot be excluded by individual settings — org instructions always apply.

CONCEPT Two things that map onto the same layers — but aren't the same

The scope names mirror the settings.json hierarchy (managed / user / project / local), and it's easy to conflate them. Keep them straight: settings enforce; CLAUDE.md guides.

Enterprises can also inject org-wide memory without a separate file by putting a claudeMd key inside managed-settings.json. That key is honored only in managed/policy settings — setting claudeMd in user, project, or local settings has no effect.
⚠️ Don't confuse precedence directions. For settings.json, managed wins outright (highest priority, can't be overridden). For CLAUDE.md everything is concatenated; there's no hard override — more-specific files simply load later. Managed CLAUDE.md is special only in that it can't be excluded.

DIAGRAM Concatenation order in context

flowchart TD M["Managed policy CLAUDE.md
/Library/... or /etc/... (org-wide)"] --> U["User
~/.claude/CLAUDE.md"] U --> P["Project
./CLAUDE.md or ./.claude/CLAUDE.md"] P --> L["Local
./CLAUDE.local.md (gitignored)"] L --> CTX["🟢 All concatenated into context
broadest first → most specific last"] classDef pol fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef mid fill:#e2e3f3,stroke:#6c63ff,color:#2a2a6a; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; class M pol; class U mid; class P mid; class L mid; class CTX ok;

CODE What lives where

A typical layout across the four scopes on one developer's machine.

# Managed policy — deployed by IT, applies to everyone, can't be excluded
/Library/Application Support/ClaudeCode/CLAUDE.md

# User — your personal preferences across every project
~/.claude/CLAUDE.md

# Project — checked into git, shared with the whole team
my-repo/CLAUDE.md            # (or my-repo/.claude/CLAUDE.md)

# Local — your private per-project notes; add to .gitignore
my-repo/CLAUDE.local.md

# Org-wide memory injected via managed settings instead of a file:
# managed-settings.json
{ "claudeMd": "Always run `make lint` before committing.\nNever push to main." }

TRADE-OFFS Project CLAUDE.md vs. CLAUDE.local.md

✅ Project CLAUDE.md

  • Committed → shared with the team
  • One source of truth for conventions
  • Reviewed like any other code
  • Best for standards, architecture, workflows

⚠️ CLAUDE.local.md

  • Private, gitignored — only on your machine
  • Good for sandbox URLs, personal test data
  • Doesn't travel across git worktrees
  • Being superseded by home-dir imports (see 1.3)

EXAM TRAPS

Trap: "User memory lives in the project's .claude/." → User memory is ~/.claude/CLAUDE.md in your home dir. The project's .claude/CLAUDE.md is a project-scope file shared via git.
Trap: "Managed policy CLAUDE.md can be turned off with claudeMdExcludes." → Managed policy CLAUDE.md cannot be excluded. Excludes only skip ancestor project/team files.
Trap: "Project CLAUDE.md overrides user CLAUDE.md by replacing it." → Files are concatenated, not replaced. Project just loads after user, so it wins on conflicts by ordering, while both remain in context.
Trap: "Set claudeMd in project settings for team-wide memory." → The claudeMd settings key is honored only in managed/policy settings. For team memory, commit a project CLAUDE.md.

PRACTICE

Q1 · List the four CLAUDE.md scopes in load order and give each location.

Managed (/Library/Application Support/ClaudeCode/CLAUDE.md, /etc/claude-code/CLAUDE.md, or C:\Program Files\ClaudeCode\CLAUDE.md) → User (~/.claude/CLAUDE.md) → Project (./CLAUDE.md or ./.claude/CLAUDE.md) → Local (./CLAUDE.local.md). Broadest first, most specific last.

Q2 · Two files conflict: user says "use tabs," project says "use 2 spaces." Which wins?

Project, effectively — it loads after user (more specific = later in context). Both stay in context; ordering resolves the conflict. Cleaner still: remove the contradiction.

Q3 · How does an org push a rule to every repo on every machine, unremovable by users?

A managed policy CLAUDE.md at the platform path, or a claudeMd key in managed-settings.json. Both load before user/project memory and cannot be excluded by individual settings.