Claude Code does not forget in one way - it forgets at three different moments, and each one needs a different fix. Most builders only solve the first problem and keep chasing the others.
Call it session drift, context loss, or just the agent forgetting what you told it - the label changes but the experience does not. The agent worked correctly an hour ago. Now it is doing something different.
Most builders hit this and reach for the obvious fix: add more to CLAUDE.md. Repeat the instructions. Explain the rules again. Sometimes that works. Often it does not, and the drift comes back anyway.
The reason it does not reliably work is that Claude Code does not forget one thing. It forgets three different things - at three different moments - and each one requires a different layer to fix.
Claude Code forgets at three distinct moments: when a session opens with no memory of your project, when context fills mid-session and earlier instructions get pushed out, and when it applies rules it technically knows but does not mechanically enforce. CLAUDE.md fixes the first. A /docs folder and MEMORY.md fix the second. Hooks fix the third. Most builders stop at the first and spend the rest of their time chasing the other two.
Forgetting Problem 1 - Lost project context
Every time a new Claude Code session opens, the agent starts with no memory of your project. It does not know your conventions, your architecture decisions, your naming patterns, or what you decided last week. It knows only what is in the files it reads before responding.
This is the forgetting problem most builders recognize first. And CLAUDE.md - a project instruction file that loads automatically at the start of every session - solves it. Write the rules once, and the agent reads them every time.
Without a CLAUDE.md, every session begins from scratch. You are repeating context, re-explaining decisions, and correcting the same deviations on every task. CLAUDE.md is not a document. It is the difference between a stateless agent and one that knows where it is.
Forgetting Problem 2 - Lost session memory
The second problem shows up inside long sessions. Claude Code holds context in a window. As a session grows - more file reads, more decisions, more output - earlier information gets deprioritized. Constraints set at the start of the session stop applying by the middle. The agent forgets what it established while working.
This problem is less often named. A well-written CLAUDE.md does not solve it. Instructions loaded at session start can drop from active context by session middle - not because the file is wrong, but because the window fills.
The fix is a different layer. A /docs folder gives the agent a place to retrieve project memory on demand, rather than holding it all in the context window at once. A MEMORY.md carries forward decisions and context from previous sessions, so the agent does not rediscover the same ground every time.
This is the difference between AOL 2 and AOL 3. AOL 2 loads rules at startup. AOL 3 externalizes memory so it survives a full session.
Forgetting Problem 3 - Inconsistent rule enforcement
The third problem is the least obvious because it looks like the first two. The agent knows the rule. It applied it correctly earlier. Then it did not apply it. Nothing changed between those two moments except the session got longer.
This is not the agent forgetting what the rule says. It is the agent failing to apply a rule it knows consistently, on every relevant action. Rules in CLAUDE.md ask Claude to remember them and choose to apply them. On a short session that works. On a long session with many moving parts, it degrades.
Hooks do not ask the agent to remember anything. They run before and after every tool call - automatically, regardless of session state.A PreToolUse hook intercepts an action before it completes. A PostToolUse hook validates the result after. The rule fires whether or not the agent recalled it at that moment. This is the enforcement layer - the mechanism that makes the difference between a rule that is written and a rule that is applied.
This is AOL 5. It is not more instructions. It is a different mechanism entirely.
Most builders reach AOL 2 and stop. The agent has a CLAUDE.md. Sessions feel more structured. But the second and third problems keep appearing - and because they look similar to the first, they get treated the same way: more instructions, longer prompts, repeated corrections.
The most common mistake after experiencing drift is writing a longer CLAUDE.md.
A longer instruction file loads more text at session start. On a short session, that helps. On a long session - the kind where drift actually appears - it fills the context window faster and makes the second problem worse, not better.
The second mistake is treating inconsistent rule application as a prompting issue. If the agent applied the rule correctly several times and then stopped, the problem is not that the instruction is unclear. The problem is that the instruction is not enforced. Rewording it does not add enforcement.
The right question to ask when drift appears is not “what am I missing from my CLAUDE.md?” It is “which of the three problems is this?”
Each problem has a specific fix. One layer cannot substitute for another.
Claude Code has no persistent memory between sessions. When a new session opens, the agent starts with no knowledge of your project - no conventions, no prior decisions, no constraints. It reads only what is in the files available before it responds. CLAUDE.md is the standard fix: a project instruction file that loads automatically at session start so the agent does not begin from scratch every time.
Claude Code maintains context in a window with a fixed capacity. As a session grows - more file reads, tool outputs, and exchanges - earlier content gets deprioritized to make room for new information. Instructions loaded at session start, including CLAUDE.md content, can drop from active context by the middle of a long session. The fix is a /docs folder and MEMORY.md: external files the agent can retrieve on demand, rather than content it must hold in the window continuously.
Hooks are the reliable fix for inconsistent rule application. A PostToolUse hook runs automatically after every tool call and validates the result before the session continues. Because hooks fire at the system level - not from the agent’s memory - they apply regardless of session length, context state, or whether the agent recalled the rule at that moment. PreToolUse hooks intercept and warn before an action completes.
CLAUDE.md loads project rules at the start of every session and solves the problem of the agent having no project context. MEMORY.md carries forward decisions and context from previous sessions, reducing what needs to be re-established each time. Hooks enforce rules mechanically on every tool call, regardless of what the agent remembers. Each solves a different forgetting problem: CLAUDE.md for session start, MEMORY.md for session continuity, hooks for rule enforcement.
The Claude Code Starter Guide includes all three layers: the CLAUDE.md template for project rules, /docs scaffolding for session memory, MEMORY.md for cross-session context, and a Hooks guide covering both hook types and the first hooks most useful to set up on a real project.
The CLAUDE.md template, /docs scaffolding, MEMORY.md format, and Hooks guide - the complete starting point for all three layers. Free account required.
Agentic AI explained through one concept: the moment your AI tool stops giving advice and starts taking action. Most builders cross this line without realizing what changed - or what habits they now need.
Read article
Most builders treat CLAUDE.md like a README. It is not documentation - it is a map. And if it is not where the agent expects it, the agent navigates without it.
Read article
Most builders jump from prompts straight to agents and wonder why things break. AI skills are the missing layer - reusable, composable units of agent behavior that make complex systems manageable.
Read article