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

# Memory Troubleshooting Guide

Detailed problem-solution reference for CLAUDE.md issues.

## Problem 1: Memory File Not Loading

**Symptoms**: Claude doesn't seem to remember project context, no awareness of CLAUDE.md contents.

### Diagnosis

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

# Check file permissions
ls -l CLAUDE.md

# Check current directory
pwd
```

### Common Causes & Solutions

#### Cause 1: Wrong Location

```bash
# ❌ Bad: Random location
/some/random/path/CLAUDE.md

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

**Solution**: Move file to project root or `.claude/` directory.

#### Cause 2: Wrong Filename (Case-Sensitive!)

```bash
# ❌ Bad
claude.md
Claude.md
CLAUDE.MD
README.md

# ✓ Good
CLAUDE.md
```

**Solution**: Rename to exactly `CLAUDE.md` (all caps).

#### Cause 3: Syntax Errors in Imports

```markdown
# ❌ Bad: Broken import
@docs/nonexistent.md

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

**Solution**: Verify all imported paths exist and are correct.

#### Cause 4: File Permissions

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

# If not readable, fix it
chmod 644 CLAUDE.md
```

### Verification Test

Add a temporary marker to CLAUDE.md:

```markdown
**MEMORY LOADED: This is a test marker**
```

Ask Claude: "What's the first line of your memory?"
If Claude sees the marker, memory is loading correctly.
Remove marker after test.

---

## Problem 2: Bloated Memory (Token Waste)

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

### Diagnosis

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

# Count characters (rough token estimate: chars ÷ 4)
wc -c CLAUDE.md
# Goal: < 20KB
```

### Solution: Trim and Split

#### Before (Bloated - 500 lines)

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

[400 more lines of verbose content]
```

#### After (Lean - 150 lines)

```markdown
# Tech Stack

- Frontend: React 18 + TypeScript + Tailwind
- Backend: Express + PostgreSQL + Redis
- Architecture: Microservices
- Details: @docs/tech-stack.md

## Common Commands

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

## Key Conventions

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

## IMPORTANT Rules

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

**Result**: 70% token reduction

### Compression Techniques

1. **Use Bullet Points, Not Paragraphs**
2. **Use Imports for Details**
3. **Show Commands, Not Explanations**
4. **Prefer Tables Over Text**

---

## Problem 3: Claude Not Following Instructions

**Symptoms**: Claude ignores rules in CLAUDE.md, doesn't follow conventions.

### Diagnosis

Check instruction specificity:

```markdown
# ❌ Too Vague (ignored)
- Write clean code
- Follow best practices
- Be careful with security

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

### Solution: Add Emphasis

#### Weak Instruction (Often Ignored)

```markdown
Use functional components in React.
Run tests before committing.
```

#### Strong Instruction (Followed)

```markdown
IMPORTANT: ALL React components MUST be functional (no class components).

YOU MUST run `npm test` and ensure all tests pass before any git commit.
```

### Emphasis Hierarchy

1. `ALL CAPS` - Maximum attention
2. `IMPORTANT:` - Critical rules
3. `YOU MUST` - Mandatory actions
4. `NEVER` - Forbidden actions
5. **Bold** - Standard emphasis
6. Regular text - General info

### Example: Strong Rules Section

```markdown
## IMPORTANT Project Rules

YOU MUST:
- Run full test suite before every commit
- Get 2 PR approvals before merging
- Update API documentation when adding endpoints

NEVER:
- Commit directly to main branch
- Merge code with failing tests
- Hardcode API keys or secrets

ALWAYS:
- Use environment variables for config
- Include error handling in all async functions
- Write tests for new features
```

---

## Problem 4: Memory Updates Not Reflected

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

### Solutions

#### Method 1: Quick Add (# Shortcut)

```bash
# At input prompt, press # first
# Type: Use snake_case for Python functions
# Claude auto-adds to appropriate CLAUDE.md
```

**Best For**: Quick single-line updates

#### Method 2: /memory Command

```bash
/memory
# Opens memory management interface
```

**Best For**: Reviewing and editing existing memory

#### Method 3: Direct Edit + Reload

```bash
# Edit the file
vim CLAUDE.md

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

**Best For**: Major updates or reorganization

#### Method 4: Session Restart (Most Reliable)

```bash
# Close and reopen Claude Code
# Or Ctrl+C to exit CLI
```

**Best For**: When other methods don't work

---

## Problem 5: Too Many Memory Files

**Symptoms**: Conflicting instructions, unclear hierarchy, unexpected behavior.

### Diagnosis

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

# Check which directory you're in
pwd
```

### Understanding Priority

Higher priority wins on conflicts:

```
1. ~/.claude/enterprise/CLAUDE.md  # Organization policy (highest)
↓
2. ./CLAUDE.md                     # Current project
↓
3. ~/.claude/CLAUDE.md             # Your personal defaults
↓
4. ./subfolder/CLAUDE.md           # Subfolder overrides
```

### Solution: Organize Properly

#### Global Personal (~/.claude/CLAUDE.md)

```markdown
# Personal Defaults

## Communication Style
- Explain decisions before acting
- Ask before destructive operations

## Code Preferences
- Prefer functional programming
- Avoid premature optimization
```

**Use For**: Universal personal preferences

#### Project Root (./CLAUDE.md)

```markdown
# MyProject

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

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

Tech Stack: Java + Spring Boot
```

**Use For**: Project-specific standards (overrides personal)

#### Subfolder (./frontend/CLAUDE.md)

```markdown
# Frontend Context

- React 18 + TypeScript
- Component structure: Atomic Design
- See @../docs/ui-patterns.md
```

**Use For**: Directory-specific context (loaded when in that directory)

---

## Problem 6: Import Loops or Errors

**Symptoms**: "Import depth exceeded", circular import error, or infinite loading.

### Import Rules

```markdown
# ❌ Bad: Too Deep
CLAUDE.md
  → @docs/a.md (depth 1)
    → @docs/b.md (depth 2)
      → @docs/c.md (depth 3)
        → @docs/d.md (depth 4)
          → @docs/e.md (depth 5)
            → @docs/f.md (depth 6 - FAILS!)

# ✓ 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
```

### Solution: Restructure Imports

**Before (Deep Chain)**:
```markdown
# CLAUDE.md
@docs/main.md

# docs/main.md
@project/overview.md

# project/overview.md
@details/architecture.md

# details/architecture.md
[content]
```

**After (Flat)**:
```markdown
# CLAUDE.md
@docs/overview.md
@docs/architecture.md
@docs/conventions.md
```

### Best Practices

- **Max depth**: 5 levels
- **No circular references**
- **Prefer flat over deep**
- **Use relative paths** for project files: `@docs/file.md`
- **Use absolute paths** for global files: `@~/.claude/shared.md`

---

## Problem 7: Conflicting Team Instructions

**Symptoms**: Different team members get different behavior from Claude.

### Diagnosis

```bash
# Check for local overrides
ls .claude/CLAUDE.local.md
ls .claude/settings.local.json

# Check git-tracked files
git ls-files | grep -i claude
```

### Solution: Proper Separation

#### Team-Shared (.claude/CLAUDE.md - in git)

```markdown
# Team Standards

IMPORTANT: All team members follow these conventions.

## Git Workflow
1. Branch from `develop`
2. PR requires 2 approvals
3. Squash merge

## Coding Standards
@docs/style-guide.md

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

#### Personal (.claude/CLAUDE.local.md - gitignored)

```markdown
# My Personal Preferences

[Individual customizations that don't affect team]
```

#### .gitignore Setup

```gitignore
# Personal files (not shared)
.claude/CLAUDE.local.md
.claude/settings.local.json
```

---

## Quick Reference: Diagnostic Checklist

When memory isn't working, check:

```markdown
- [ ] File named exactly "CLAUDE.md" (case-sensitive)
- [ ] File in project root or .claude/ directory
- [ ] File has read permissions (chmod 644)
- [ ] Valid markdown syntax
- [ ] Imports use correct paths
- [ ] No circular import loops
- [ ] Import depth ≤ 5 levels
- [ ] File size < 20KB (~200 lines)
- [ ] Instructions are specific, not vague
- [ ] Used emphasis for critical rules
- [ ] No syntax errors in code blocks
- [ ] Tried session restart
- [ ] Verified loading with test marker
```

---

## Getting Help

If problems persist:

1. **Verify File Loading**: Add test marker, ask Claude to read it
2. **Check Hierarchy**: Understand which files are being loaded
3. **Review Syntax**: Ensure valid markdown and imports
4. **Simplify First**: Start with minimal CLAUDE.md, add back gradually
5. **Restart Session**: Most reliable way to reload changes

For further assistance, see [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory).