Why Claude Code Forgets and How to Fix It

"I just told you that rule five minutes ago" — if you've used Claude Code for any serious development work, you've had this thought.

Claude follows your instructions perfectly at the start of a session. An hour later, it's writing code as if your CLAUDE.md doesn't exist. This isn't a bug. It's a predictable consequence of how context windows work, and it's entirely preventable.

This article explains the mechanics behind why Claude Code "forgets," how to use the 6 memory layers effectively, when to use /compact vs /clear, and how to avoid the Auto-Compaction trap that silently degrades your session quality.

Why Claude Code Forgets Your Instructions

Claude Code's context window is approximately 200,000 tokens. That sounds massive, but real development work fills it faster than you'd expect.

What consumes context:

• CLAUDE.md (2,000–5,000 tokens)
• Auto Memory's MEMORY.md (up to 200 lines)
• Source code reads (~5,000 tokens per 500-line file)
• Conversation history (accumulates with every exchange)
• Tool call results (file reads, search results, command output)

Reading 10 files and having a 30-minute conversation can easily consume over 100,000 tokens.

"Forgetting" happens in two ways:

1. Pushed out of the context window — older information exits the window and Claude can no longer reference it. Your CLAUDE.md rules aren't literally forgotten — they're buried under newer conversation content and stop receiving attention
2. Summarized by Auto-Compaction — at around 167,000 tokens, automatic compression kicks in and summarizes conversation history. The summary preserves decisions but often loses the reasoning behind them, causing Claude to drift in a different direction

In both cases, it's a placement problem, not an existence problem. Put the right information in the right place, and it won't be forgotten.

Understanding the 6 Memory Layers

Claude Code has 6 memory layers with a clear priority hierarchy. Higher layers take precedence.

Most solo developers use layers 2, 3, and 6.

Project CLAUDE.md (layer 3) is the cornerstone of context management. Rules written here are loaded at the start of every session. Conversely, rules not written here are at risk of being forgotten.

For team projects, layer 5 (.claude/rules/*.md) is powerful. Glob patterns let you apply different rules to different files — for example, frontend.md loads only when touching frontend code.

For patterns on how to structure your CLAUDE.md effectively, see "Claude Code Context Management: CLAUDE.md Design Patterns."

How Auto Memory Works and When to Use It

Auto Memory lets Claude automatically record what it learns during sessions. Files are saved to ~/.claude/projects/<project>/memory/, with MEMORY.md serving as the index.

What Auto Memory records:

• Build commands and test conventions
• Debugging insights
• Architecture decisions
• Code style preferences
• Your workflow patterns

What Auto Memory does NOT record:

• Code content itself (reading the codebase is more reliable)
• Temporary work state ("currently editing this file")
• Information derivable from git history

Practical tips

Give explicit feedback and it gets recorded. Tell Claude "don't use mocks in tests" and Auto Memory saves it as feedback that persists across sessions.

MEMORY.md has a 200-line cap. Only the first 200 lines are loaded at session start. Beyond that, you'll get a warning. Prune old entries regularly.

# View and manage Auto Memory
> /memory

How to split responsibilities between CLAUDE.md and Auto Memory:

• CLAUDE.md → Rules you define. "Use TypeScript strict mode." "Write tests with Vitest."
• Auto Memory → Things Claude learns. "This user is a senior engineer." "The DB schema was changed last session."

Writing the same thing in both wastes tokens. Rules go in CLAUDE.md. Learning goes in Auto Memory.

/compact vs /clear — Choosing the Right One

When sessions get long, two commands manage context. Choosing wrong means losing information you needed.

/compact — Compress the conversation

Summarizes conversation history, drastically reducing token usage. Key decisions are preserved, but the detailed context of individual exchanges is lost.

> /compact

When to use it:

• You want to continue the same task but context is getting heavy
• /context shows usage above 70%
• Claude's response speed is slowing down

When NOT to use it:

• The task is done and you're switching to different work (/clear is better)

/clear — Reset context entirely

Wipes all conversation history. CLAUDE.md and Auto Memory are reloaded fresh.

> /clear

When to use it:

• A task is complete and you're switching to the next one
• Claude is clearly stuck on outdated context
• Something feels off (reset is the fastest fix)

Decision rule

"Am I continuing the same task?" → Yes → /compact / No → /clear

When in doubt, /clear is safer. With CLAUDE.md and Auto Memory in place, most context is recoverable.

The Auto-Compaction Trap and How to Avoid It

Auto-Compaction triggers automatically when context reaches approximately 167,000 tokens. Unlike manual /compact, it fires without warning.

Why it's a problem

Auto-Compaction summarizes conversations, but the summary can drop the reasoning behind decisions. For example:

• "We're using Supabase Auth because we need RLS integration" → after compaction, only "Use Supabase Auth" survives
• Without the reasoning, Claude may suggest alternatives that contradict your architecture

How to defend against it

1. Write important decisions to files

Don't let decisions exist only in conversation. Write them to docs/decisions.md or CLAUDE.md. File content isn't affected by context compression.

2. Split sessions by task

One task = one session as a default. Auth flows, DB schema changes, and large refactors with precise constraints especially benefit from session isolation.

3. Use PreCompact Hooks for automatic backup

A PreCompact Hook runs a script right before compression fires. You can auto-save critical state to a file.

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/save-session-state.sh"
          }
        ]
      }
    ]
  }
}

Practical Techniques for Stable Long Sessions

Putting it all together — here's the routine that keeps sessions stable in real development work.

Session start routine

1. Run /context to check for leftover context from a previous session
2. Verify CLAUDE.md matches today's task
3. If a session-handoff.md exists from last time, reference it

Mid-session monitoring

• Check /context every 30 minutes. Above 70% usage → consider /compact
• Run /clear after each completed task. Don't carry context into unrelated work
• Write decisions to files as they happen. Don't leave them only in conversation

Session handoff

# session-handoff.md

## Completed
- Migrated src/auth/login.ts from JWT to Supabase Auth
- All existing tests passing

## Next Session
- Migrate src/auth/register.ts (same approach as login.ts)
- Update auth check in middleware.ts

## Constraints
- Supabase RLS stays enabled
- NEXT_PUBLIC_SUPABASE_URL already set in .env.local

Even with Auto Memory, write "what to do next" in session-handoff.md manually. Auto Memory records what Claude judges as important, which may not include your specific work plan.

Use Agent Teams to distribute context

For large-scale work, Agent Teams let you parallelize tasks across multiple agents. Each agent has its own independent context window, so you avoid the single-session overflow problem entirely.

For example, assigning "frontend refactoring" and "API test additions" to separate agents gives each one the full 200,000-token budget.

Wrapping Up

Claude Code "forgetting" isn't a bug — it's a constraint of context windows. With the right strategies, you can maintain consistent quality even in long sessions.

If Claude seems to have forgotten your rules, check your CLAUDE.md first. Optimizing information placement — not volume — is what changes the experience.

Related articles:

• Claude Code Context Management: CLAUDE.md Design Patterns
• How I Reduced Claude Code Token Consumption by 50%
• How to Fix "context window exceeded" in Claude Code