Memory System

Claude Code includes a persistent memory system that remembers your preferences, patterns, and context across sessions. This guide explains how to configure and use CLAUDE.md files for consistent project context.

Learn more: For detailed memory capabilities, visit Claude Code Memory Documentation

What is Memory

Memory in Claude Code works through CLAUDE.md files that provide persistent, project-specific instructions. These files shape how Claude understands your codebase and applies consistent patterns across all interactions.

Two levels of memory:

• User-level (~/.claude/CLAUDE.md) - Personal preferences across all projects
• Project-level (./CLAUDE.md) - Project-specific conventions and context

How It Works

Claude Code reads CLAUDE.md files in priority order:

1. Project root (./CLAUDE.md) - Highest priority
2. Parent directories - Inherited configuration
3. User home (~/.claude/CLAUDE.md) - Personal defaults
4. System defaults - Claude's base behavior

Project-level configuration can override user preferences for specific contexts.

When to Use Memory

CLAUDE.md files excel for information that stays consistent:

• Project conventions - Coding standards, file organization, naming patterns
• Technology choices - Frameworks, libraries, architectural decisions
• Team preferences - Review processes, documentation style, commit formats
• Domain context - Business rules, terminology, compliance requirements
• Development workflow - Testing approach, deployment process, tooling

Basic Configuration

Create Your First CLAUDE.md

# In your project root
touch CLAUDE.md

Basic project configuration:

# Project Name

## Tech Stack
- Frontend: React 18 with TypeScript
- Backend: Node.js + Express  
- Database: PostgreSQL
- Testing: Jest

## Conventions
- Use functional components
- Use async/await for API calls
- Keep components under 100 lines
- Follow REST API naming conventions

## File Structure

src/ components/ # React components services/ # API integration utils/ # Helper functions types/ # TypeScript definitions

User-Level Configuration

Create personal preferences that apply across all projects:

# Create if it doesn't exist
mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

Personal preferences example:

# Personal Coding Preferences

## Style Preferences  
- Always use TypeScript when possible
- Prefer const over let
- Use descriptive variable names
- Add comments only for complex logic

## Communication Style
- Be direct and professional
- Code examples before explanations
- Point out potential issues

Configuration Examples

Team Standards

# Team Configuration

## Code Quality Standards
- ESLint: @company/eslint-config-strict
- Test coverage: minimum 85%
- All public functions need JSDoc
- No TODO comments in main branch

## Git Workflow
- Branch naming: feature/TICKET-123-description
- Commit format: "type(scope): description"
- PR requires 2 reviewer approval

## Architecture Patterns
```typescript
// Controllers: thin, delegate to services
export class UserController {
  constructor(private userService: UserService) {}
  
  async createUser(req: Request, res: Response) {
    const result = await this.userService.create(req.body)
    res.json(result)
  }
}

### Domain-Specific Context
```markdown
# FinTech Payment System

## Compliance Requirements
- PCI DSS Level 1 compliance required
- Never log sensitive card data
- Encrypt PII at rest and in transit
- Audit log all transactions

## Business Rules
1. Transactions over $10,000 require additional verification
2. Daily limit per customer: $50,000
3. Retry failed payments max 3 times with exponential backoff

## Integration Points
- Stripe: Primary payment processor
- Plaid: Bank account verification

Best Practices

Keep Instructions Clear and Actionable

✅ Good: "Use functional React components with TypeScript"
❌ Bad: "Try to write good React code"

✅ Good: "Throw custom errors with error codes"
❌ Bad: "Handle errors properly"

Focus on Stable Conventions

✅ Include: Technology stack, coding standards, architecture patterns
❌ Avoid: Current sprint tasks, temporary workarounds, feature-specific notes

Include Pattern Examples

## API Response Format
```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0"
  }
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [...]
  }
}

### Structure for Scannability

```markdown
# Project Overview
[Brief description]

## Tech Stack
[Technologies used]

## Conventions
### Coding Standards
### File Structure
### Naming

## Patterns
### Common Patterns
### Anti-patterns to Avoid

## Workflow
### Development Process
### Testing Requirements

Common Anti-Patterns

❌ Don't Include Sensitive Information

Wrong: API keys, passwords, or secrets
Right: Reference environment variables or secret management

❌ Don't Over-Constrain Claude

Wrong: Specifying every minor detail
Right: Focus on important patterns and conventions

❌ Don't Make It Too Long

Wrong: 1000+ line configuration files
Right: Focus on essential patterns (aim for <200 lines)

Quick Reference Template

# [Project Name]

## Identity
[Claude's role in this project]

## Tech Stack
- Language: [...]
- Framework: [...]
- Database: [...]

## Conventions
### Coding Standards
[Key standards]

### File Structure  
[Organization pattern]

## Patterns
### Use These Patterns
[Preferred approaches]

### Avoid These Anti-patterns
[What not to do]

## Examples
[Code examples showing desired patterns]

Next Steps

• Learn Prompting Techniques with CLAUDE.md context
• Combine with Thinking Modes for complex analysis
• Set Output Styles in your configuration
• Master everything with Advanced Steering