claude-plugins/claude-code/skills/claude-code-memory/SKILL.md

---
name: Claude Code Memory Specialist
description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use when memory isn't loading, context is bloated, or optimizing existing memory files. NOT for initial setup - use /init command first.
---

# Claude Code Memory Optimization & Troubleshooting

## When to Use This Skill

Use this skill when:
- Troubleshooting memory files that aren't loading
- Optimizing bloated CLAUDE.md files
- Managing token consumption
- Setting up memory hierarchy (project/user/subfolder)
- Creating additional memory files and imports
- Debugging why Claude isn't following instructions
- Organizing memory for team collaboration
- Converting verbose documentation to efficient memory

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

**Important**: Always start with `/init` for initial project memory setup. Use this skill to refine and troubleshoot afterward.

## Quick Reference: Memory Hierarchy

```
1. Enterprise Policy       ~/.claude/enterprise/CLAUDE.md (highest priority)
2. Project Memory          ./CLAUDE.md or ./.claude/CLAUDE.md
3. User Memory             ~/.claude/CLAUDE.md
4. Subfolder Memory        ./subfolder/CLAUDE.md (loaded when in subfolder)
```

**Lookup Order**: Claude recursively searches upward from current directory, loading all CLAUDE.md files found.

## Common Problems & Solutions

### Problem 1: Memory File Not Loading

**Symptoms**: Claude doesn't seem to remember project context

**Diagnose**:
```bash
# Check if memory file exists
ls -la CLAUDE.md
ls -la .claude/CLAUDE.md
ls -la ~/.claude/CLAUDE.md

# Check file permissions
ls -l CLAUDE.md
```

**Common Causes**:

1. **Wrong Location**
```bash
# ❌ Bad: Random location
/some/random/path/CLAUDE.md

# ✓ Good: Project root
./CLAUDE.md
# or
./.claude/CLAUDE.md
```

2. **Wrong Filename** (Case-sensitive!)
```bash
# ❌ Bad
claude.md
Claude.md
CLAUDE.MD

# ✓ Good
CLAUDE.md
```

3. **Syntax Errors in Imports**
```markdown
# ❌ Bad: Broken import
@docs/nonexistent.md

# ✓ Good: Valid path
@docs/architecture.md
```

**Fix - Verify Loading**:
```markdown
# Add to top of CLAUDE.md temporarily
**MEMORY LOADED: Project memory is active**

# Ask Claude: "What's at the top of your memory?"
# Should see the marker
```

### Problem 2: Bloated Memory (Token Waste)

**Symptoms**: Context fills up quickly, slow responses, high costs

**Diagnose**:
```bash
# Check memory file size
wc -l CLAUDE.md
# Goal: 100-200 lines max

# Count total tokens (rough estimate: chars ÷ 4)
wc -c CLAUDE.md
```

**Fix - Trim and Split**:

```markdown
# Before (Bloated - 500 lines)
# Project Overview

This project is a comprehensive e-commerce platform built with React, Node.js, Express, PostgreSQL, Redis, and Docker. The frontend uses React 18 with TypeScript in strict mode, Tailwind CSS for styling, React Router for navigation, Redux Toolkit for state management, and Axios for API calls. The backend uses Express.js with TypeScript, Sequelize ORM for database access, JWT for authentication, bcrypt for password hashing, and Redis for session management. We follow a microservices architecture with...

[400 more lines of verbose content]
```

```markdown
# After (Lean - 150 lines)
# Tech Stack

- Frontend: React 18 + TypeScript + Tailwind
- Backend: Express + PostgreSQL + Redis
- Architecture: Microservices pattern
- See @docs/architecture.md for details

# Coding Standards

- 2-space indentation
- Functional components only
- ESLint + Prettier
- 80% test coverage minimum

# Common Commands

```bash
npm run dev        # Local development
npm test           # Run all tests
npm run build      # Production build
```

# Key Files

- `src/api/`: REST endpoints
- `src/components/`: React components
- See @docs/file-structure.md

# IMPORTANT Project Rules

- YOU MUST run tests before committing
- Never commit .env files
- Always update API docs when adding endpoints
```

**Best Practices**:
- **100-200 lines max** for main CLAUDE.md
- Use **bullet points**, not paragraphs
- Be **specific**, not verbose
- **Import** detailed docs instead of embedding

### Problem 3: Claude Not Following Instructions

**Symptoms**: Claude ignores rules in CLAUDE.md

**Diagnose**:
```markdown
# Check instruction specificity

# ❌ Too vague
- Write clean code
- Follow best practices
- Be careful with security

# ✓ Specific
- Use 2-space indentation (not tabs)
- All API endpoints must have rate limiting
- Hash passwords with bcrypt (min 10 rounds)
```

**Fix - Add Emphasis**:

```markdown
# Before (Weak)
Use functional components in React.

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

# Before (Ignored)
Run tests before committing.

# After (Enforced)
YOU MUST run `npm test` and ensure all tests pass before any git commit.
```

**Emphasis Techniques**:
- `IMPORTANT:` for critical rules
- `YOU MUST` for mandatory actions
- `NEVER` for forbidden actions
- **Bold** for emphasis
- ALL CAPS for maximum attention

### Problem 4: Memory Updates Not Reflected

**Symptoms**: Changes to CLAUDE.md don't take effect

**Fix**:

**Method 1: Quick Add**
```bash
# Press # at input start
# Type: Use snake_case for Python functions
# Claude auto-adds to appropriate CLAUDE.md
```

**Method 2: Manual Edit**
```bash
# Use /memory command
/memory

# Or edit directly
vim CLAUDE.md

# Then explicitly ask Claude to reload
"Please re-read CLAUDE.md"
```

**Method 3: Session Restart**
```bash
# Most reliable: restart session
# Ctrl+C or close/reopen Claude Code
```

### Problem 5: Too Many Memory Files

**Symptoms**: Conflicting instructions, unclear hierarchy

**Diagnose**:
```bash
# Find all CLAUDE.md files
find . -name "CLAUDE.md"
find ~ -name "CLAUDE.md"
```

**Understand Priority**:
```
Higher Priority (wins on conflict)
↓
1. ~/.claude/enterprise/CLAUDE.md  # Organization policy
2. ./CLAUDE.md                     # Current project
3. ~/.claude/CLAUDE.md             # Your personal defaults
4. ./subfolder/CLAUDE.md           # Subfolder overrides
↓
Lower Priority
```

**Fix - Organize Properly**:

```markdown
# ~/.claude/CLAUDE.md (Personal defaults for ALL projects)
# General Preferences

- Prefer functional programming
- Explain complex code
- Ask before destructive operations

# ./CLAUDE.md (Project-specific, overrides above)
# MyProject Specifics

@docs/tech-stack.md
@docs/conventions.md

IMPORTANT: This project uses OOP (override personal FP preference).

# ./frontend/CLAUDE.md (Frontend-specific)
# Frontend Guidelines

- React + TypeScript
- Component-driven development
- See @../docs/ui-patterns.md
```

### Problem 6: Import Loops or Errors

**Symptoms**: "Import depth exceeded" or circular imports

**Fix - Import Rules**:

```markdown
# ❌ Bad: Too deep
CLAUDE.md
  → @docs/a.md
    → @docs/b.md
      → @docs/c.md
        → @docs/d.md
          → @docs/e.md
            → @docs/f.md (FAILS - max depth 5)

# ✓ Good: Flat structure
CLAUDE.md
  → @docs/architecture.md
  → @docs/conventions.md
  → @docs/testing.md
  → @docs/deployment.md

# ❌ Bad: Circular import
CLAUDE.md → @docs/a.md → @docs/b.md → @docs/a.md (LOOP!)

# ✓ Good: No circles
CLAUDE.md → @docs/a.md → @docs/c.md
         → @docs/b.md → @docs/c.md
```

**Import Best Practices**:
- Max depth: 5 levels
- No circular references
- Use relative paths for project files
- Use absolute paths for user/global files

## Optimization Patterns

### Pattern 1: Core + Imports Architecture

```markdown
# CLAUDE.md (Core - 100 lines)
# MyProject

Quick reference for AI coding assistant.

## Tech Stack
- Backend: Node.js + Express + PostgreSQL
- Frontend: React + TypeScript + Tailwind
- Details: @docs/tech-stack.md

## Common Commands
```bash
npm run dev      # Start dev server
npm test         # Run tests
npm run build    # Production build
```

## Coding Standards
- 2-space indentation
- ESLint + Prettier
- Full details: @docs/style-guide.md

## Architecture
- Microservices pattern
- See @docs/architecture.md

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

---

# docs/tech-stack.md (Detailed - loaded on demand)
[Full tech stack details, dependencies, versions...]

# docs/style-guide.md (Detailed)
[Comprehensive coding standards...]

# docs/architecture.md (Detailed)
[System architecture diagrams, patterns...]
```

**Benefits**:
- Main memory stays lean
- Details loaded only when needed
- Easy to update specific areas
- Team can own different docs

### Pattern 2: Subfolder Specialization

```markdown
# Project Structure
myproject/
├── CLAUDE.md              # Project-wide context
├── frontend/
│   ├── CLAUDE.md         # Frontend-specific
│   └── src/
├── backend/
│   ├── CLAUDE.md         # Backend-specific
│   └── src/
└── docs/
    ├── architecture.md
    └── conventions.md

# ./CLAUDE.md (Root)
# MyProject

Microservices e-commerce platform.

Common across all areas:
- Git workflow: feature branches + PRs
- Testing required before merge
- See @docs/architecture.md

# ./frontend/CLAUDE.md (Loaded when in frontend/)
# Frontend Context

- React 18 + TypeScript strict mode
- Component structure: Atomic Design
- Styling: Tailwind utility-first
- State: Redux Toolkit

## Component Patterns
@../docs/ui-patterns.md

# ./backend/CLAUDE.md (Loaded when in backend/)
# Backend Context

- Express + TypeScript
- Database: PostgreSQL + Sequelize
- Auth: JWT + refresh tokens
- Caching: Redis

## API Patterns
@../docs/api-patterns.md
```

**When to Use**:
- Large monorepos
- Different tech stacks per area
- Team specialization (frontend/backend teams)
- Different conventions per module

### Pattern 3: User + Project Separation

```markdown
# ~/.claude/CLAUDE.md (Personal preferences - ALL projects)
# Personal Defaults

## Communication Style
- Explain decisions before acting
- Ask before destructive operations
- Show diffs for large changes

## Code Preferences
- Prefer functional programming
- Avoid premature optimization
- Comprehensive error handling

## Tools
- Git commit format: Conventional Commits
- Prefer `npm` over `yarn`

# ./CLAUDE.md (Project overrides personal defaults)
# ProjectX

IMPORTANT: This legacy project uses OOP extensively (override FP preference).

Tech stack:
- Java Spring Boot
- MySQL
- jQuery (legacy frontend)

Common commands:
```bash
mvn clean install
mvn test
```

Conventions:
- CamelCase for classes
- snake_case for database
```

**Benefits**:
- Consistent personal style across projects
- Project-specific overrides when needed
- Easy onboarding to new projects

### Pattern 4: Team Collaboration

```markdown
# .claude/CLAUDE.md (Team-shared, in git)
# Team Standards

IMPORTANT: All team members should follow these conventions.

## Git Workflow
1. Create feature branch: `feature/description`
2. PR to `develop` (not `main`)
3. 2 approvals required
4. Squash merge

## Code Review Checklist
- Tests pass locally
- Coverage > 80%
- No linter warnings
- Documentation updated

## Architecture Decisions
@docs/adr/  # Architecture Decision Records

## Tech Stack
@docs/tech-stack.md

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

# .claude/CLAUDE.local.md (Personal, gitignored)
# My Personal Overrides

[Your personal preferences that don't affect team]
```

**Team Setup**:
```gitignore
# .gitignore
.claude/CLAUDE.local.md     # Personal only
.claude/settings.local.json # Personal settings
```

**Benefits**:
- Consistent team standards
- Personal customization allowed
- Version control for team rules
- Onboarding documentation

## Token Management Strategies

### Strategy 1: Measure Current Usage

```bash
# Estimate tokens in memory
wc -c CLAUDE.md | awk '{print $1/4}'
# Goal: < 5000 tokens (< 20KB file)

# Count lines
wc -l CLAUDE.md
# Goal: 100-200 lines

# Find verbose sections
grep -n "." CLAUDE.md | awk -F: 'length($2) > 100 {print NR": "$0}'
```

### Strategy 2: Lean Writing

```markdown
# Before (150 tokens)
The application uses a microservices architecture where each service is independently deployable and scalable. The services communicate via REST APIs and message queues. This allows for better separation of concerns and makes it easier to maintain and scale individual components.

# After (30 tokens)
Architecture: Microservices (REST + message queues)
- Independent deployment/scaling
- See @docs/architecture.md
```

**Compression Techniques**:
- Bullet points > paragraphs
- Commands > explanations
- Imports > embedding
- Examples > theory

### Strategy 3: Strategic Importing

```markdown
# CLAUDE.md - Always Loaded (100 lines = ~400 tokens)
Common commands, key conventions, critical rules

# @docs/ - Loaded On Demand
architecture.md      # Loaded when discussing architecture
api-reference.md     # Loaded when working on APIs
testing-guide.md     # Loaded when writing tests
deployment.md        # Loaded when deploying
```

**Import Decision Tree**:
```
Need info for 80%+ of sessions?
  → Put in CLAUDE.md

Need info occasionally?
  → Put in @docs/, reference from CLAUDE.md

Need info rarely?
  → Don't include, use web search or direct file read
```

### Strategy 4: Regular Cleanup

```bash
# Monthly review checklist
# 1. Remove outdated info
grep -i "deprecated\|old\|legacy\|TODO" CLAUDE.md

# 2. Merge redundant sections
# 3. Move details to @docs/
# 4. Update changed conventions
# 5. Test: does Claude follow all rules?
```

## Testing Memory Effectiveness

### Test 1: Loading Verification

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

# Ask Claude
"What's the first line of your project memory?"

# Should respond with marker
# Remove marker after verification
```

### Test 2: Instruction Adherence

```markdown
# Test Plan

Rule: "Use 2-space indentation"
Test: Ask Claude to write a function
Expected: 2-space indentation
Actual: ___

Rule: "Run tests before commit"
Test: Ask Claude to commit changes
Expected: Runs npm test first
Actual: ___

Rule: "Never commit .env files"
Test: Ask to add .env to commit
Expected: Refuses or warns
Actual: ___
```

### Test 3: Token Efficiency

```markdown
# Baseline
Current tokens: ___ (measure file size ÷ 4)
Session context usage: ___ (check /usage)

# After optimization
New tokens: ___
Reduction: ___
Improvement: ___%

# Quality check
Does Claude still follow all rules? Yes/No
Response quality maintained? Yes/No
```

### Test 4: Team Consistency

```markdown
# Cross-developer test

Developer A asks: "What's our git workflow?"
Claude response: ___

Developer B asks: "What's our git workflow?"
Claude response: ___

Responses identical? Yes/No
If no, identify conflict in memory files.
```

## Memory File Templates

### Template 1: Minimal Project

```markdown
# ProjectName

Brief description.

## Tech Stack
- Language/Framework
- Database
- Key libraries

## Common Commands
```bash
start-command
test-command
build-command
```

## Conventions
- Code style rule 1
- Code style rule 2
- Naming convention

## IMPORTANT
- Critical rule 1
- Critical rule 2
```

### Template 2: Team Project

```markdown
# ProjectName

@docs/overview.md

## Quick Reference

### Tech Stack
@docs/tech-stack.md

### Common Commands
```bash
npm run dev
npm test
npm run build
```

### Coding Standards
- 2-space indentation
- ESLint + Prettier
- Full guide: @docs/style-guide.md

### Architecture
@docs/architecture.md

## IMPORTANT Team Rules

- YOU MUST create PR for all changes
- Tests must pass before merge
- Update docs with code changes

## Git Workflow
@docs/git-workflow.md

## Never
- Commit to main directly
- Merge without review
- Commit secrets
```

### Template 3: Monorepo

```markdown
# MonorepoName

Multi-package repository.

## Structure
- `packages/frontend/` - React app → See frontend/CLAUDE.md
- `packages/backend/` - API server → See backend/CLAUDE.md
- `packages/shared/` - Common code

## Global Standards
- Node.js 20+
- pnpm workspaces
- Shared ESLint config

## Commands (from root)
```bash
pnpm install
pnpm test
pnpm run build
```

## Cross-Package
- Import from `@myapp/shared`
- See @docs/package-deps.md

## IMPORTANT
- Changes affecting multiple packages need full test suite
```

### Template 4: Personal Defaults

```markdown
# Personal Preferences

Applied to all my projects unless overridden.

## Communication
- Explain reasoning before acting
- Confirm before destructive ops
- Show diffs for large changes

## Code Style
- Functional programming preferred
- Descriptive variable names
- Comments for "why", not "what"

## Git
- Conventional Commits format
- Squash feature branches

## Testing
- Write tests alongside code
- Aim for 80%+ coverage
```

## Troubleshooting Checklist

When memory isn't working:

```markdown
- [ ] File named exactly "CLAUDE.md" (case-sensitive)
- [ ] File in correct location (project root or .claude/)
- [ ] File has valid markdown syntax
- [ ] Imports use correct paths (relative/absolute)
- [ ] No circular import loops
- [ ] Import depth ≤ 5 levels
- [ ] File size reasonable (< 20KB)
- [ ] Instructions are specific, not vague
- [ ] Used emphasis (IMPORTANT, YOU MUST) for critical rules
- [ ] No syntax errors in code blocks
- [ ] Tried reloading (/memory or restart)
- [ ] Verified loading with test marker
```

## Common Anti-Patterns

### ❌ Anti-Pattern 1: Novel-Length Memory

```markdown
# CLAUDE.md (2000 lines)
[Extensive documentation about everything...]
```

**Why Bad**: Wastes tokens, slows responses, high cost

**Fix**: Keep to 100-200 lines, import details

### ❌ Anti-Pattern 2: Vague Instructions

```markdown
- Write good code
- Follow best practices
- Be secure
```

**Why Bad**: Too generic, Claude ignores

**Fix**: Be specific with examples

### ❌ Anti-Pattern 3: Mixing Concerns

```markdown
# CLAUDE.md
[Project setup]
[Personal preferences]
[Team standards]
[Implementation details]
[API documentation]
[All mixed together]
```

**Why Bad**: Hard to maintain, conflicts

**Fix**: Separate files by scope and audience

### ❌ Anti-Pattern 4: Static Documentation

```markdown
# Last updated: 6 months ago
[Outdated conventions]
[Deprecated tools]
[Old architecture]
```

**Why Bad**: Misleads Claude, causes errors

**Fix**: Regular reviews, use # for quick updates

### ❌ Anti-Pattern 5: No Imports

```markdown
# CLAUDE.md (500 lines)
[Everything embedded inline]
```

**Why Bad**: Token waste, hard to navigate

**Fix**: Use @imports for detailed docs

## Advanced Techniques

### Technique 1: Dynamic Context Loading

```markdown
# CLAUDE.md
When working on:
- Frontend → Read @frontend/CLAUDE.md
- Backend → Read @backend/CLAUDE.md
- DevOps → Read @docs/devops.md
- Testing → Read @docs/testing.md
```

### Technique 2: Versioned Standards

```markdown
# CLAUDE.md
Current API version: v2
See @docs/api-v2.md

Migration from v1:
@docs/migration-v1-to-v2.md
```

### Technique 3: Role-Based Memory

```markdown
# CLAUDE.md
Your current role: Full-stack developer

Available roles:
- @docs/role-frontend.md
- @docs/role-backend.md
- @docs/role-devops.md
- @docs/role-qa.md

Switch with: "Act as [role]"
```

### Technique 4: Conditional Instructions

```markdown
# CLAUDE.md
## Environment-Aware

When in development:
- Verbose logging OK
- Use local DB

When in production:
- Minimal logging
- Use RDS
- NEVER commit with `console.log`
```

### Technique 5: Memory Backup System

```bash
# Create backup before major changes
cp CLAUDE.md CLAUDE.md.backup.$(date +%Y%m%d)

# Or use git
git add CLAUDE.md
git commit -m "docs: update memory before refactor"

# Rollback if needed
git checkout HEAD~1 -- CLAUDE.md
```

## Team Workflows

### Workflow 1: Onboarding New Developer

```bash
# 1. Clone repo (includes .claude/CLAUDE.md)
git clone repo

# 2. Claude reads memory automatically
# New dev asks: "What's this project?"

# 3. Claude uses CLAUDE.md to explain:
# - Tech stack
# - Architecture
# - Conventions
# - Common commands

# 4. New dev productive immediately
```

### Workflow 2: Updating Standards

```bash
# 1. Team decision: Switch to pnpm
# 2. Update CLAUDE.md:
#    s/npm/pnpm/g

# 3. Commit change
git commit -m "docs: switch to pnpm"

# 4. All developers get update on pull
# 5. Claude uses new standard automatically
```

### Workflow 3: Feature-Specific Memory

```bash
# Working on auth feature
cd features/auth

# features/auth/CLAUDE.md
# Authentication Feature

Uses JWT + refresh tokens
See @../../docs/auth-patterns.md

Important:
- Password: bcrypt (min 12 rounds)
- Tokens: 15min access, 7d refresh
- MFA required for admin

# Claude loads this when in auth directory
```

## Quick Fixes Reference

| Problem | Quick Fix |
|---------|-----------|
| Memory not loading | Check filename case: `CLAUDE.md` |
| 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 | Check hierarchy, project wins over user |
| Import not found | Verify path, use relative for project files |
| Import loop | Check for circular references |
| Too verbose | Use bullets, not paragraphs |
| Team inconsistency | Put shared rules in `.claude/CLAUDE.md` (in git) |
| Personal conflicts | Use `.claude/CLAUDE.local.md` (gitignored) |

## Resources

- [Official Memory Documentation](https://docs.claude.com/en/docs/claude-code/memory)
- [Claude Code Plugins](../claude-code-plugins/SKILL.md) - For packaging memory in plugins
- [Slash Commands](../claude-code-slash-commands/SKILL.md) - Complement to memory
- [Hooks](../claude-code-hooks/SKILL.md) - Automation with memory

---

**Remember**: Start with `/init`, keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness, update regularly.