# Claude Code Memory Management & Context Optimization Guide

## How Claude Code Memory Works

Claude Code uses a simple but powerful file-based memory system centered around `CLAUDE.md` files. These are automatically loaded into context when Claude Code starts, providing persistent memory across sessions.

### Memory File Hierarchy

```
~/Developer/
├── CLAUDE.md                    # Global project memory
├── Projects/
│   ├── my-app/
│   │   ├── CLAUDE.md           # Project-specific memory
│   │   ├── src/
│   │   │   └── CLAUDE.md       # Module-specific memory
│   │   └── tests/
│   │       └── CLAUDE.md       # Test-specific memory
│   └── api-service/
│       └── CLAUDE.md           # Another project's memory
└── ~/.claude/
    └── my-preferences.md        # Personal preferences (imported)
```

**How it loads**: Claude recursively reads CLAUDE.md files from your current directory up to (but not including) root `/`.

## 1. Setting Up Efficient Memory Structure

### Project Root CLAUDE.md

Create `~/Developer/Projects/my-app/CLAUDE.md`:

```markdown
# My App - E-commerce Platform

## Tech Stack
- TypeScript 5.x with strict mode
- Node.js 20.x, Express 4.x
- PostgreSQL 15 with Prisma ORM
- Redis for caching and rate limiting

## Architecture Decisions
- Hexagonal architecture with clear boundaries
- Repository pattern for data access
- Use cases in `/src/usecases/`
- Domain models in `/src/domain/`

## Coding Standards
- NO classes unless absolutely necessary
- Prefer pure functions and const exports
- Use Zod for runtime validation
- Error handling: Result<T, E> pattern

## Common Commands
- `npm run dev` - Start with hot reload
- `npm run test:watch` - Run tests in watch mode
- `npm run db:migrate` - Apply migrations

## Key Files
- `/src/config/` - All env and config
- `/src/middleware/auth.ts` - JWT implementation
- `/docs/API.md` - API documentation

## Current Sprint Focus
- Implementing checkout flow
- Performance optimization for product search
- Adding Stripe payment integration

# Import personal preferences
@~/.claude/my-preferences.md
```

### Personal Preferences File

Create `~/.claude/my-preferences.md`:

```markdown
# Personal Coding Preferences

## Communication Style
- Be direct and concise
- Skip explanations unless asked
- Focus on implementation

## Code Style
- TypeScript: Use type inference where obvious
- Prefer const arrow functions
- Use early returns for guard clauses
- Comments only for complex logic

## Git Workflow
- Conventional commits: feat/fix/chore
- Branch naming: feature/JIRA-1234-description
- Squash commits before merge

## Testing Approach
- Test behavior, not implementation
- Use test.each for similar scenarios
- Mock external dependencies
```

## 2. Quick Memory Addition During Sessions

Use the `#` character to add memories on the fly:

```bash
claude
> implement user authentication
> # Auth uses JWT with 24h expiry, refresh tokens in Redis with 7d expiry
> # Password hashing: bcrypt with 10 rounds
> # Rate limit: 5 login attempts per 15 minutes per IP
```

Claude will prompt you to choose which memory file to save to.

## 3. Token-Optimized Memory Strategies

### Strategy 1: Hierarchical Context Loading

Structure memories by specificity:

```
CLAUDE.md (root) - 200 tokens - General project info
├── src/CLAUDE.md - 150 tokens - Source code conventions
├── tests/CLAUDE.md - 100 tokens - Testing patterns
└── docs/CLAUDE.md - 50 tokens - Documentation style
```

**Token Savings**: Only relevant memories load based on working directory.

### Strategy 2: Import-Based Composition

Instead of one large CLAUDE.md:

```markdown
# Main CLAUDE.md - Keep minimal
## Project: E-commerce API

For detailed information:
@docs/architecture.md - System design
@docs/api-patterns.md - API conventions
@docs/database.md - Schema and queries
@docs/testing.md - Test strategies
```

**Token Savings**: ~60% reduction by loading only needed docs.

### Strategy 3: Dynamic Memory Templates

Create task-specific memory files:

#### `.claude/memory-templates/feature.md`
```markdown
# Feature: $FEATURE_NAME

## Requirements
- [ ] $REQUIREMENT_1
- [ ] $REQUIREMENT_2

## Technical Approach
- 

## Files to Modify
- 

## Test Scenarios
- 

## Edge Cases
- 
```

Use during development:
```bash
# Copy template when starting new feature
cp .claude/memory-templates/feature.md .claude/current-feature.md
# Edit and import in CLAUDE.md
echo "@.claude/current-feature.md" >> CLAUDE.md
```

## 4. Memory Optimization Patterns

### Pattern 1: Decision Log

```markdown
# Architectural Decisions

## 2024-12-15: Chose PostgreSQL over MongoDB
- Reason: Strong consistency requirements
- Impact: Use Prisma for type-safe queries

## 2024-12-10: Adopted Result<T,E> pattern
- Reason: Explicit error handling
- Example: `Result<User, AuthError>`
- Location: `/src/lib/result.ts`
```

**Why it works**: Provides context without implementation details.

### Pattern 2: Code Patterns Library

```markdown
# Common Patterns

## Service Pattern
```typescript
export const createUserService = (deps: Dependencies) => ({
  async createUser(data: CreateUserDto): Result<User, Error> {
    // validation → business logic → persistence
  }
})
```

## Repository Pattern
```typescript
export const userRepository = {
  async findById(id: string): Promise<User | null> {
    return prisma.user.findUnique({ where: { id } })
  }
}
```
```

**Token Savings**: Reference patterns instead of explaining each time.

### Pattern 3: Context Bridges

For complex features, create temporary context files:

```markdown
# Current Context: Payment Integration

## What's Done
- ✓ Stripe SDK integrated
- ✓ Webhook endpoint created
- ✓ Payment intent creation

## Current Task
- Implementing webhook signature verification

## Blockers
- Need to update CSP headers for Stripe.js

## Next Steps
- Add idempotency keys
- Implement retry logic
```

## 5. Reusing Memory Effectively

### Create Semantic Shortcuts

In CLAUDE.md:
```markdown
## Shortcuts
- "standard auth" = JWT + refresh tokens + rate limiting
- "api pattern" = validate → use case → repository → response
- "test pattern" = arrange → act → assert with test.each
```

Usage:
```bash
claude
> implement login endpoint using standard auth and api pattern
```

### Build Command Memories

`.claude/commands/implement-endpoint.md`:
```markdown
Implement a new API endpoint for $ARGUMENTS following these steps:
1. Check existing patterns in /src/routes/
2. Use standard validation with Zod
3. Implement use case in /src/usecases/
4. Add repository methods if needed
5. Write integration tests
6. Update API documentation

Follow the patterns in CLAUDE.md strictly.
```

### Version Your Memories

```bash
# Before major refactoring
cp CLAUDE.md CLAUDE.md.backup-2024-12-15

# After refactoring
diff CLAUDE.md.backup-2024-12-15 CLAUDE.md > memory-changes.log
```

## 6. Advanced Memory Techniques

### Technique 1: Contextual Imports

```markdown
# CLAUDE.md
## Dynamic Imports Based on Task

Working on auth? @docs/auth-deep-dive.md
Working on payments? @docs/payment-flows.md
Working on search? @docs/search-architecture.md
```

### Technique 2: Memory Compression

Use `/compact` to summarize long sessions into memory:

```bash
claude
> [long implementation session]
> /compact Create a summary focused on decisions made and patterns established
> # [Add the summary to CLAUDE.md]
```

### Technique 3: Cross-Project Learning

Create `~/.claude/learned-patterns.md`:
```markdown
# Patterns That Worked Well

## From project-a
- Health check endpoint pattern
- Graceful shutdown implementation

## From project-b  
- Migration rollback strategy
- Circuit breaker pattern

## Anti-patterns to Avoid
- Mixing concerns in middleware
- Deeply nested callbacks
```

## 7. Memory Maintenance Workflow

### Weekly Review Process

```bash
#!/bin/bash
# ~/Developer/Resources/scripts/memory-review.sh

echo "## Memory Review - $(date +%Y-%m-%d)" > memory-review.md

# Find all CLAUDE.md files modified this week
find . -name "CLAUDE.md" -mtime -7 -type f | while read file; do
  echo "\n### $file" >> memory-review.md
  git diff HEAD~7 -- "$file" | grep "^+" | grep -v "^+++" >> memory-review.md
done

# Review and consolidate
claude -p "Review these memory changes and suggest consolidations" < memory-review.md
```

### Memory Metrics

Track memory effectiveness:

```markdown
# Memory Usage Stats

## Token Count by File
- Root CLAUDE.md: 420 tokens
- src/CLAUDE.md: 280 tokens  
- tests/CLAUDE.md: 150 tokens
- Total: 850 tokens

## Most Referenced Sections
1. API Patterns (12 times this week)
2. Error Handling (8 times)
3. Test Strategies (6 times)

## Stale Sections (not referenced in 2 weeks)
- WebSocket implementation (removed)
- GraphQL notes (moved to archive)
```

## Quick Reference

### Essential Memory Commands

| Action | Method |
|--------|--------|
| Add memory during session | Type `#` followed by content |
| Edit memory files | `/memory` command |
| Import external file | `@path/to/file.md` in CLAUDE.md |
| Check loaded memories | First prompt asks Claude to list |

### Memory Best Practices

1. **Keep it concise**: Each memory should be <100 tokens
2. **Use examples**: Show patterns, don't just describe
3. **Stay current**: Review and prune weekly
4. **Layer by specificity**: General → Specific → Task
5. **Version control**: Commit CLAUDE.md with code changes

### Token Optimization Checklist

- [ ] Root CLAUDE.md under 500 tokens
- [ ] Use imports for detailed documentation
- [ ] Remove outdated decisions/patterns
- [ ] Consolidate similar patterns
- [ ] Archive completed sprint notes
- [ ] Use shortcuts for common patterns

## Example: Complete Memory Setup

```bash
# 1. Initialize project memory
cd ~/Developer/Projects/new-app
claude
> /init
> # TypeScript strict mode, Node.js 20, PostgreSQL, Redis
> # Prefer functional style, no classes
> # Use Result<T,E> for error handling

# 2. Import personal preferences
echo "@~/.claude/my-preferences.md" >> CLAUDE.md

# 3. Create task-specific memory
echo "## Current Task: User Authentication" >> CLAUDE.md
echo "- [ ] JWT implementation" >> CLAUDE.md
echo "- [ ] Password reset flow" >> CLAUDE.md

# 4. Work and add learnings
> implement JWT auth
> # JWT secret from env.JWT_SECRET, 24h expiry
> # Refresh tokens in Redis, key: refresh:{userId}

# 5. Compress and archive
> /compact Focus on authentication decisions
git add CLAUDE.md && git commit -m "docs: Add auth implementation notes"
```

This approach ensures Claude always has the right context while minimizing token usage through strategic memory organization.