Complete Guide to Claude Code User Memory vs @import Usage

Introduction

When developing with Claude Code, have you ever felt frustrated explaining the same rules repeatedly or wished for unified rules across your team?

Claude Code offers two powerful features to solve these problems:

• User Memory (~/.claude/CLAUDE.md)
• @import feature (project-specific configuration loading)

This article explains the differences between these features and how to use them effectively with practical examples.

What is User Memory?

Overview

User Memory is where you record your personal development style and work rules. Stored in ~/.claude/CLAUDE.md, it's automatically applied to all projects.

Features

• Auto-loading: Applied to all projects without configuration
• Private: Personal settings not committed to Git
• Instant reflection: Update once, apply everywhere
• Location: ~/.claude/CLAUDE.md

Suitable Content

# Examples suitable for User Memory

## Work Management Rules
- 'Mid-close': Document update + daily report update
- 'Close': Mid-close + git commit + push

## Personal Development Style
- Principles of question-based AI collaboration
- Prefer concise answers within 4 lines
- Don't use emojis

## Daily Report Format
- Session management format
- Work time recording method

What is @import Feature?

Overview

The @import feature loads shareable rule sets from separate files. Used by writing in the project's CLAUDE.md.

Features

• Explicit: Selectively load only needed rules
• Shareable: Use same rules across team
• Version controlled: Manage history with Git
• Modular: Manage rules in small units

Suitable Content

# Examples suitable for @import

## Project Type Settings
- SaaS common settings
- Landing page settings
- E-commerce site settings

## Technical Standards
- Coding standards
- Security practices
- Git operation rules

## Framework-specific Settings
- Next.js development standards
- Vue.js development standards

Practical Usage Patterns

Ideal Directory Structure

Your Development Environment/
├── .claude/
│   └── CLAUDE.md          # Personal work style
├── shared-rules/          # Shared rule library
│   ├── saas-common.md     # SaaS common settings
│   ├── landing-page.md    # LP common settings
│   ├── ecommerce.md       # E-commerce settings
│   ├── nextjs-rules.md    # Next.js standards
│   └── security.md        # Security standards
└── projects/
    ├── project-a/
    │   └── CLAUDE.md      # Combine rules with @import
    └── project-b/
        └── CLAUDE.md

Project Combination Examples

For SaaS Projects

# project-a/CLAUDE.md

# SaaS Project Settings

## Load Common Rules
@import ../../shared-rules/saas-common.md
@import ../../shared-rules/nextjs-rules.md
@import ../../shared-rules/security.md

## Project-specific Settings
- API Authentication: JWT
- Deployment: Vercel
- DB: PostgreSQL + Prisma

For Landing Pages

# project-b/CLAUDE.md

# Landing Page Settings

## Load Common Rules
@import ../../shared-rules/landing-page.md
@import ../../shared-rules/nextjs-rules.md

## Project-specific Settings
- Static generation only
- Animation: Framer Motion
- Forms: Resend integration

Decision Criteria

When to Choose User Memory

1. Personal Work Habits

   • Work management terms like 'mid-close', 'close'
   • Daily report writing style
   • AI interaction style

2. Rules Used in Every Project

   • Preference for concise answers
   • Error handling methods
   • Personal coding style

3. Private Information

   • Personal notes
   • Specific client information

When to Choose @import

1. Team-shared Rules

   • Coding standards
   • Git commit message format
   • PR creation rules

2. Project Type-specific Settings

   • SaaS-specific settings
   • LP-specific optimization rules
   • E-commerce security settings

3. Tech Stack-specific Settings

   • Framework best practices
   • Library usage guidelines
   • Deployment environment settings

Implementation Best Practices

1. Hierarchical Structure

Personal Settings (User Memory)
└── Common Tech Settings (@import)
    └── Project Type Settings (@import)
        └── Project-specific Settings (Direct in CLAUDE.md)

2. Rule Granularity

• Not too big, not too small: About 1 theme per file
• Consider reusability: Can it be used in other projects?
• Maintainability: Consider update frequency

3. Naming Rules

# Good Examples
saas-common.md         # Clear purpose
nextjs-rules.md        # Clear technology
security-practices.md  # Clear content

# Avoid
rules1.md             # Unclear content
misc.md               # Unclear scope
temp.md               # Temporary impression

Troubleshooting

Q: User Memory not applying?

A: Check if CLAUDE memory feature is enabled and verify the file path is correct.

Q: @import not working?

A: Check if relative paths are correct and files exist. Pay attention to the number of ../.

Q: What if rules conflict?

A: Later-loaded rules take precedence. Order: Project-specific > @import > User Memory.

Conclusion

By properly using Claude Code's User Memory and @import features:

1. Improved Personal Productivity: Auto-apply frequently used rules
2. Team Consistency: Easily share common rules
3. Maintainability: Easy rule updates
4. Flexibility: Optimal settings per project

Leverage these features for more efficient AI-assisted development!

Related Resources

• Claude Code Official Documentation
• Interactive Refactoring with AI
• The Design System Paradox AI Falls Into