Claude Code Keeps Forgetting Your Project? How CLAUDE.md Survives the Context Window

An hour into a session, Claude Code stops following the conventions you explained at the start. It renames things you told it not to rename, forgets which service owns the database, proposes the pattern you rejected twice. This is not the model getting worse. The context window filled up, the conversation was compacted, and your explanations were among the things summarized away. The fix is not repeating yourself louder - it is putting the facts that must survive into the one file that always does.

What actually happens when the window fills

Every session has a fixed context window. Your messages, the agent's replies, every file it reads, and every tool result all share that space. When it approaches the limit, Claude Code compacts: earlier conversation gets replaced by a summary, and the session continues. Compaction is lossy by design. A summary keeps the gist of the task and drops most specifics - including the naming rule you stated once, forty minutes ago, in a paragraph about something else.

CLAUDE.md is the exception

CLAUDE.md is re-read at the start of every session and stays in context regardless of compaction. Facts placed there do not get summarized away. That makes it the right home for exactly the things you find yourself repeating: architecture boundaries, naming conventions, commands that must be run a specific way, files that must never be edited, the test command, the deploy command. If a fact would change what the agent does on any task in the repo, it belongs in CLAUDE.md, not in chat.

What to keep out of it

The failure mode in the other direction is a 900-line CLAUDE.md that buries the load-bearing rules under history and aspiration. Every line sits in every session's context, so each one pays rent or leaves. Keep it to current, durable, behavior-changing facts. Meeting notes, roadmap, and explanations of why a decision was made belong in docs the agent can read on demand - point to them with one line: See docs/architecture.md before touching the billing module.

A structure that holds up

# Project
One paragraph: what this is, who runs it, how.

# Commands
- test: npm test -- --run
- lint: npm run lint:fix
- dev: npm run dev (port 3100)

# Boundaries
- Never edit src/legacy/** - frozen, mirrors production.
- Database access only through src/db/client.ts.
- No new dependencies without asking.

# Conventions
- Files: kebab-case. React components: PascalCase.
- Errors: throw AppError, never raw Error.
- Commits: conventional commits, no scope.

Thirty to sixty lines like this outperforms a wall of prose. The agent follows lists of constraints far more reliably than paragraphs of advice.

Recovering a session that already drifted

When you notice drift mid-session, do not argue with the summary - it cannot give back what it dropped. State the rule once more, then move it into CLAUDE.md so it never needs restating: "Add to CLAUDE.md under Boundaries: never mock the payments service in tests." The agent can edit the file itself, and the rule is permanent from the next line onward. Run /clear between unrelated tasks so a stale summary from the last task does not leak into the next one.

The short version

Forgetting is compaction, and compaction is normal. Chat is scratch space; CLAUDE.md is project memory. Keep the file short, current, and limited to facts that change behavior, and the agent stops starting from zero.

The Agentic Coding Kit ships battle-tested CLAUDE.md and AGENTS.md templates - boundaries, commands, conventions - plus 30 more config files for Claude Code and Cursor. $19 one-time. Or draft yours free with the CLAUDE.md generator.