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 Code forgets because older context gets pushed out of the sliding context window or compressed by Auto-Compaction. The fix: write persistent rules in CLAUDE.md, use /compact or /clear strategically, and never let important decisions exist only in conversation.

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 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 depends on the model you're using. The standard window is around 200,000 tokens, though some models support up to 1 million. Either way, real development work fills it faster than you'd expect.

What consumes context:

• CLAUDE.md files (2,000–5,000 tokens each)
• 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. Refactoring sessions that touch many files can push usage up surprisingly fast.

"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 — when the context window fills up (roughly 80–85% capacity), 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 Memory Layers

Claude Code has multiple memory layers with a clear priority hierarchy. More specific locations take precedence over broader ones, as described in the official memory documentation.

Most solo developers use Project CLAUDE.md, User CLAUDE.md, and Auto Memory.

Project CLAUDE.md is the cornerstone of context management. Rules written here are loaded at the start of every session and take precedence over your personal User CLAUDE.md. Conversely, rules not written here are at risk of being forgotten.

A common mistake I made early on with 32blog was putting project-specific rules in ~/.claude/CLAUDE.md (the user-level file). Those rules got overridden by the project CLAUDE.md and were effectively invisible. Move project rules to the project root.

For team projects, .claude/rules/*.md is powerful. You can scope rules to specific file types with paths frontmatter — for example, frontend.md loads only when Claude touches src/components/**/*.tsx files. This keeps context lean.

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. Details are in the official docs.

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. As you accumulate feedback — things like "don't add Co-Authored-By to commits" or "always verify before proposing changes" — you stop repeating the same corrections.

MEMORY.md has a 200-line cap. Only the first 200 lines are loaded at session start. Content beyond line 200 is silently ignored. Claude keeps MEMORY.md concise by moving detailed notes into separate topic files (like debugging.md or api-conventions.md) that are read on demand.

# 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

An important thing the docs clarify: CLAUDE.md fully survives compaction. After /compact, Claude re-reads your CLAUDE.md from disk and re-injects it fresh. If an instruction disappeared after compaction, it was given only in conversation — not written to CLAUDE.md.

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 the context window fills up — roughly 80–85% of capacity. 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 — Claude re-reads files from disk after compaction.

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. The trigger field tells you whether it was manual (/compact) or automatic.

{
  "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 subagents and Agent Teams to distribute context

For large-scale work, subagents let you delegate tasks that run in their own context window. Each subagent gets independent context, keeping your main session lean. Agent Teams take this further — multiple agents working in parallel, each with the full context budget.

For example, assigning "frontend refactoring" and "API test additions" to separate agents gives each one independent context instead of competing for space in a single session.

Frequently Asked Questions

Does CLAUDE.md survive /compact?

Yes. After /compact, Claude re-reads your CLAUDE.md from disk and injects it fresh into the session. Only conversation history is compressed — CLAUDE.md files and Auto Memory are unaffected.

What's the difference between CLAUDE.md and Auto Memory?

CLAUDE.md contains rules you define: coding standards, workflows, architecture decisions. Auto Memory contains things Claude learns from your corrections and preferences. Use CLAUDE.md for prescriptive rules and Auto Memory for accumulated knowledge.

How do I check my context usage?

Run /context in your Claude Code session. It shows a breakdown of token consumption across system prompt, tools, memory files, conversation history, and free space.

Can I disable Auto-Compaction?

Auto-Compaction is built into Claude Code and can't be turned off directly. The best defense is proactive context management: run /compact manually before reaching capacity, split sessions by task, and write important decisions to files rather than keeping them in conversation.

What happens when MEMORY.md exceeds 200 lines?

Only the first 200 lines are loaded at session start. Content beyond that is silently ignored. Claude manages this by keeping MEMORY.md as a concise index and moving detailed notes into separate topic files that are read on demand.

Does /clear delete my Auto Memory?

No. /clear only wipes conversation history. Auto Memory files in ~/.claude/projects/<project>/memory/ are untouched and reloaded at the start of the next session.

Can I share CLAUDE.md rules across projects?

Yes. Place shared rules in ~/.claude/CLAUDE.md (user-level) for personal rules that apply everywhere. For team-shared cross-project rules, use symlinks in .claude/rules/ pointing to a shared directory.

Can subagents have their own memory?

Yes. Subagents can maintain their own Auto Memory. See the subagent memory documentation for configuration details.

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.

For more Claude Code guides, see the full article collection.

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
• Claude Code Troubleshooting: The Complete Guide