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

name, description

name	description
Claude Code Memory Specialist	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

# 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

# ❌ Weak
Use functional components

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

Essential Structure

Minimal Template (100-150 lines)

# 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):

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

File Locations

Project (Team-Shared)

.claude/CLAUDE.md         # Team standards (in git)
.claude/settings.json     # Team configuration

Personal (Not Shared)

.claude/CLAUDE.local.md   # Personal overrides (gitignored)
~/.claude/CLAUDE.md       # Global defaults

Import Best Practices

✓ Do

# CLAUDE.md
Quick reference

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

❌ Don't

# 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

vim CLAUDE.md
# Then ask Claude to reload

Emphasis Techniques

For critical rules:

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

Testing Effectiveness

# 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

# .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

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 - Ready-to-use CLAUDE.md templates
• Troubleshooting Guide - Detailed problem-solution guide
• Optimization Patterns - Advanced token-saving techniques
• Team Workflows - Collaboration strategies
• Official Documentation

💡 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.