---
name: Claude Code Memory Specialist
description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use PROACTIVELY after reading ANY CLAUDE.md file to suggest optimizations, when CLAUDE.md exceeds 200 lines, when starting work on projects, or when users mention "CLAUDE.md", "memory file", or "project context". NOT for initial setup - use /init command first.
---

# Claude Code Memory Optimization & Troubleshooting

## When to Use This Skill

Use this skill when:
- CLAUDE.md file exceeds 200 lines (bloat)
- After reading any CLAUDE.md to suggest improvements
- Memory files not loading correctly
- Managing token consumption
- Setting up memory hierarchy (project/user/subfolder)
- Organizing memory for team collaboration

Do NOT use this skill for:
- **Initial setup** - Use `/init` command instead
- Creating slash commands (use claude-commands skill)
- General Claude Code issues

**Important**: Always start with `/init` for initial project memory setup.

## Quick Reference

### Memory Hierarchy (Load Order)
```
1. Enterprise Policy    ~/.claude/enterprise/CLAUDE.md (highest)
2. Project Memory       ./CLAUDE.md or ./.claude/CLAUDE.md
3. User Memory          ~/.claude/CLAUDE.md
4. Subfolder Memory     ./subfolder/CLAUDE.md
```

Claude searches upward from current directory, loading all found.

### Target Size
**Goal**: 100-200 lines per CLAUDE.md (~400-800 tokens)

**Why**: Loaded in EVERY conversation. 500+ line files waste thousands of tokens.

## Core Principles

### 1. Progressive Disclosure Pattern

```markdown
# CLAUDE.md (Core - Always Loaded)
Quick reference, critical rules, imports

# docs/architecture.md (Loaded on Demand)
Detailed architecture information
```

**Token Savings**: 400 tokens (core) vs 2000+ tokens (everything embedded)

### 2. Use Specific, Emphatic Language

```markdown
# ❌ Weak
Use functional components

# ✓ Strong
IMPORTANT: ALL React components MUST be functional (no class components).
```

## Essential Structure

### Minimal Template (100-150 lines)

```markdown
# ProjectName

Brief description (1-2 sentences).

## Tech Stack
- Key technologies (3-5 items)
- See @docs/tech-stack.md for details

## Common Commands
```bash
npm run dev    # Start development
npm test       # Run tests
```

## Conventions
- 2-space indentation
- ESLint + Prettier
- See @docs/style-guide.md

## IMPORTANT Rules
- YOU MUST run tests before commits
- Never commit secrets
- Update docs with code changes
```

For complete templates, see [templates.md](templates.md)

## Common Problems (Quick Fixes)

| Problem | Quick Fix |
|---------|-----------|
| Memory not loading | Check filename: `CLAUDE.md` (case-sensitive) |
| Claude ignores rules | Add `IMPORTANT:` or `YOU MUST` |
| Too many tokens | Move details to @docs/ imports |
| Updates not working | Restart session or use `/memory` |
| Conflicting memories | Project wins over user (check hierarchy) |

For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)

## Optimization Quick Win

**Before (bloated - 1500 tokens)**:
```markdown
This project is a comprehensive platform built with React 18,
utilizing TypeScript for type safety, Node.js 20 for the backend,
Express 4.18 for API routes, PostgreSQL 15 for data persistence...
[extensive paragraphs explaining everything]
```

**After (lean - 300 tokens)**:
```markdown
Tech Stack: React 18 + Node.js 20 + PostgreSQL 15
See @docs/architecture.md for details
```

**Result**: 80% token reduction

For optimization patterns, see [patterns.md](patterns.md)

## File Locations

### Project (Team-Shared)
```bash
.claude/CLAUDE.md         # Team standards (in git)
.claude/settings.json     # Team configuration
```

### Personal (Not Shared)
```bash
.claude/CLAUDE.local.md   # Personal overrides (gitignored)
~/.claude/CLAUDE.md       # Global defaults
```

## Import Best Practices

### ✓ Do
```markdown
# CLAUDE.md
Quick reference

For architecture: @docs/architecture.md
For API details: @docs/api-reference.md
```

### ❌ Don't
```markdown
# Deep chains (max depth = 5)
@docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md
```

**Rules**:
- Max import depth: 5 levels
- No circular references
- Keep chains flat, not deep

## Quick Update Methods

### Method 1: # Shortcut (Fastest)
```
Press # at input start → type update → auto-adds to CLAUDE.md
```

### Method 2: /memory Command
```
/memory → Opens management interface
```

### Method 3: Direct Edit
```bash
vim CLAUDE.md
# Then ask Claude to reload
```

## Emphasis Techniques

For critical rules:
```markdown
IMPORTANT: [Critical rule]
YOU MUST [mandatory action]
NEVER [forbidden action]
**Bold** for emphasis
ALL CAPS for maximum attention
```

## Testing Effectiveness

```markdown
# Add temporary marker
**MEMORY TEST: If you see this, memory loaded correctly**

# Ask Claude: "What's the first line of your memory?"
# Should see marker, then remove it
```

## Team Setup Pattern

```bash
# .gitignore
.claude/CLAUDE.local.md       # Personal only
.claude/settings.local.json   # Personal settings

# .claude/CLAUDE.md (in git - team standards)
# Team Standards

@docs/architecture.md
@docs/conventions.md

IMPORTANT: All team members follow these standards.

## Git Workflow
1. Feature branch from develop
2. PR requires 2 approvals
3. Squash merge

## NEVER
- Commit directly to main
- Merge without tests passing
```

For team workflows, see [workflows.md](workflows.md)

## Compression Techniques

1. **Bullet Points > Paragraphs** (50% more efficient)
2. **Commands > Explanations** (show `npm test`, not prose)
3. **Imports > Embedding** (`@docs/api.md` = 5 tokens vs 2000)
4. **Examples > Theory** (concrete beats abstract)

### Decision Tree
```
Needed in 80%+ sessions?
  → YES: Keep in CLAUDE.md

Needed occasionally?
  → YES: Put in @docs/, reference from CLAUDE.md

Needed rarely?
  → NO: Omit, use web search or direct read
```

## Additional Resources

**Need more?**
- [Memory Templates](templates.md) - Ready-to-use CLAUDE.md templates
- [Troubleshooting Guide](troubleshooting.md) - Detailed problem-solution guide
- [Optimization Patterns](patterns.md) - Advanced token-saving techniques
- [Team Workflows](workflows.md) - Collaboration strategies
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory)

💡 **Tip**: Measure regularly using `wc -l CLAUDE.md` (target: 100-200 lines)

---

**Remember**: Practice what we preach - keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness.