majiayu000 Memory Design Skill
This skill provides decision frameworks for organizing Claude Code's 4-tier memory hierarchy, modular rules system, and path-specific loading patterns.
Fundamentals
Prerequisites: This skill builds on box-factory-architecture. Load that skill when choosing between memory vs skills vs other component types.
Core principles of Claude Code memory:
- 4-tier hierarchy: Enterprise → Project (CLAUDE.md) → Project Rules (.claude/rules/) → User (~/.claude/CLAUDE.md) → Project Local (CLAUDE.local.md)
- Recursive discovery: Claude searches up from cwd to root, reading all CLAUDE.md files found
- Progressive disclosure: Memory is "always loaded", Skills are "load when relevant"
- Knowledge delta: Only document what Claude doesn't know about your specific project/workflow
Deep dive: box-factory-architecture skill (Progressive Disclosure, Knowledge Delta Filter sections). Traverse when: choosing between memory vs skills, understanding component selection. Skip when: clear that content belongs in memory.
Workflow Selection
| If you need to... | Go to... |
|---|---|
| Use path-specific conditional rules | path-specific-rules.md - Traverse when: implementing conditional loading, frontend/backend split. Skip when: simple monolithic setup |
| Set up file imports with @syntax | file-imports.md - Traverse when: importing existing docs, user-specific instructions. Skip when: using .claude/rules/ directory |
| Choose an organization pattern | organization-patterns.md - Traverse when: structuring new project, refactoring memory. Skip when: clear pattern already |
| Avoid common mistakes | anti-patterns.md - Traverse when: reviewing existing setup, debugging issues. Skip when: creating new setup from scratch |
| Validate your setup | Quality Checklist below - Traverse when: finalizing memory organization. Skip when: still in design phase |
Official Documentation
Fetch when organizing memory (post-training knowledge):
- https://code.claude.com/docs/en/memory.md - Complete memory hierarchy, rules directory, path-specific rules, import syntax
The 4-Tier Memory Hierarchy (Official Specification)
Claude Code loads memory in this order (highest to lowest priority):
- Enterprise policy - Organization-wide (system location, managed by IT)
- Project memory - Team-shared via git (
./CLAUDE.mdor./.claude/CLAUDE.md) - Project rules - Modular team-shared (
./.claude/rules/*.md) - User memory - Personal cross-project (
~/.claude/CLAUDE.md) - Project local - Personal project-specific (
./CLAUDE.local.md, gitignored)
Key insight: Higher tiers provide foundation, lower tiers add specificity. All files load automatically at session start.
Memory Lookup Behavior
Recursive search: Claude starts in cwd, recurses UP to root, reading all CLAUDE.md and CLAUDE.local.md files found.
Nested discovery: CLAUDE.md files in subtrees under cwd are discovered but only loaded when Claude reads files in those subtrees.
The Rules Directory
Location: ./.claude/rules/ (project level) or ~/.claude/rules/ (user level)
Behavior: All .md files discovered recursively, loaded with same priority as .claude/CLAUDE.md
When to Use Each Memory Location (Best Practices)
Use Project Memory (CLAUDE.md) when:
- Instructions apply to all team members
- Knowledge should be version-controlled
- Content is project architecture, conventions, workflows
- Single file is sufficient (<200 lines)
Use Project Rules (.claude/rules/) when:
- Project memory would exceed ~200 lines
- Multiple independent topics (testing, API design, security)
- Want modular organization by domain
- Need path-specific conditional rules
Use User Memory (~/.claude/CLAUDE.md) when:
- Personal preferences across ALL projects
- Your coding style, preferred tools
- Not project-specific, shouldn't be in version control
Use Project Local (CLAUDE.local.md) when:
- Personal preferences for THIS project only
- Sandbox URLs, test credentials, local paths
- Experimental or temporary instructions
- Must not be committed to git (auto-gitignored)
Monolithic vs Modular Decision
Keep single CLAUDE.md when:
- Total content < 200 lines
- Topics are interconnected
- Project is small/simple
Split into .claude/rules/ when:
- Total content > 200 lines
- Clear independent topics
- Different team members own different domains
- Want path-specific rules
Memory vs Skills vs CLAUDE.md (Best Practices)
| Put In... | When... |
|---|---|
| Memory (rules/) | Always relevant in this project, loads at session start |
| Skills | Loads progressively when topics arise, 20+ lines expertise |
| Single CLAUDE.md | Simple project, <200 lines, interconnected content |
The boundary: Memory is "always loaded context", Skills are "load when relevant"
Quality Checklist
Before finalizing memory organization:
Memory location:
- Project-wide rules in CLAUDE.md or .claude/rules/ (version-controlled)
- Personal preferences in ~/.claude/CLAUDE.md or CLAUDE.local.md
- Secrets/credentials only in CLAUDE.local.md (gitignored)
- Chose monolithic vs modular based on size/complexity (monolithic <200 lines, modular >200 lines)
Rules directory:
- Each file focuses on one cohesive topic (can describe purpose in one sentence without "and")
- File has >20 lines of substantive content
- Subdirectories used for logical grouping by domain
- No duplicate rules across multiple files (single source of truth)
Path-specific rules:
-
pathsfield only when rules truly specific to file subset - Glob patterns are clear and maintainable (no overly complex patterns)
- No overly broad (
**/*) or overly narrow (single file) patterns - No competing/overlapping path patterns across files
File imports:
- Import syntax only in CLAUDE.md content (not in code blocks)
- No import cycles (design like dependency tree)
- Import depth < 3 hops (well under 5 limit)
- Imports point to stable, maintained files
Documentation References
- https://code.claude.com/docs/en/memory.md - Official memory documentation
- box-factory-architecture skill - Understanding when memory vs skills
- plugin-design skill - Organizing plugin-level CLAUDE.md files