How Claude Code Uses CLAUDE.md and Memory

Project notes let useful decisions survive a conversation. Claude Code's loading rules determine when those notes reach the next task.

September 2026 update: The product behavior described here reflects current documentation; the December 2025 analyses are discussed below as historical explorations.

Working with Claude Code over several months, I developed the practice of keeping project guidance in CLAUDE.md, a Markdown instruction file that the coding assistant can load alongside a task. It gave me a place to preserve architectural decisions and working agreements without reconstructing them in every conversation.

I've also seen a new session seem unaware of decisions made during earlier work. Check whether the decision is recorded, whether the record is current and whether it reached the session. If the right guidance was already available, review how the implementation departed from it.

Which product's memory?

The word memory covers several mechanisms. A saved preference, a conversation search and a repository instruction file can all provide useful context, but they have different controls and loading rules.

ProductWhat can carry context forwardWhat to check
Claude chatSaved topics and searches of earlier chats, with project boundariesMemory settings and account or organization availability. Claude chat can save context automatically; it is not limited to on-demand searches.
Claude CodeRepository instructions and auto memoryThe working directory, instruction settings, loaded file paths and saved notes.
ChatGPT webMemory can use relevant past chats, saved details and other enabled sourcesPersonalization settings and workspace restrictions. It does not retain every detail or search history for every response.
Local CodexA local memory store separate from ChatGPT web memory, plus project instructionsWhether local memories are enabled and which instruction files apply. Eligible past chats are processed in the background; updates need not be immediate.

These are current documented distinctions, with availability controlled by the relevant product and account. The primary references are Claude chat memory, Claude Code memory, ChatGPT memory and local Codex memories. A memory feature enabled in one of these products does not establish the configuration of another.

Claude Code's context window is the information available for the current response: instructions, conversation, file contents, tool results and other material the application supplies. A file on disk is accessible material; it only contributes to that response after its content is included. Anthropic's explanation of Claude Code describes that surrounding application and its tools.

Instruction priority answers whose direction should govern. It cannot make a factual statement true. A high-priority instruction can name a test command that the repository no longer has, and the latest user message can contain an outdated assumption about a release. Check those claims against the system they describe.

Follow the file into the session

Under the documented loading rules, instructions in the working directory and its ancestors are included at startup. A CLAUDE.md below that directory loads when Claude reads a file in the relevant subtree. Path-scoped rules under .claude/rules have their own matching conditions. Anthropic's large-codebase guide explains that distinction and the exclusions that can change it.

Consider this illustrative API project:

service/
  CLAUDE.md
  CONTEXT.md
  src/
    api/
      CLAUDE.md
      health.ts
      orders.ts

The root CLAUDE.md might say:

# Project guidance

Run the existing API tests after changing a handler.
Report the command, its result and any checks you could not run.
Read CONTEXT.md before resuming an unfinished task, then check its claims
against the current files and test results.

The nested src/api/CLAUDE.md might add:

# API response convention

Error responses contain error.code and error.message.
Keep stack traces out of the response body.

Starting from service/ should load the root guidance. The nested instructions become relevant when Claude reads health.ts or orders.ts through its file-reading tool. Starting from src/api/ puts both levels on the startup path.

Use /context and inspect Memory files to check the paths actually loaded. /memory provides file locations and editing controls; that list can include files that do not yet exist, so it serves a different purpose. The configuration troubleshooting guide describes both views.

Then give the session a concrete request:

Read src/api/health.ts and the current CONTEXT.md. Before changing the handler, identify the response convention that applies and compare the task record with the current implementation. Report any disagreement.

Check /context again after the file read. If the nested instruction is absent, investigate discovery, exclusions and settings. If it is present, review the resulting handler and its tests: does the error response have the specified fields, and can a failure expose a stack trace? A correct answer about the rule is weaker evidence than a correct implementation of it.

A test that exercises only a successful health response cannot establish what happens when the handler fails.

Keep instructions focused and records current

I organize project information into three categories:

  • Project context: what the codebase does, the architectural decisions that matter to this task and the reasons behind them.
  • Working agreements: conventions, review expectations and boundaries for making changes.
  • Current work: what is in progress, what is blocked and the next action that will resolve it.

The first two belong in maintained project guidance or clearly linked reference material. Current work changes more often, so I keep it in a separate record such as CONTEXT.md. The filename is my convention. It has no universal automatic-loading status.

In the illustrative project, the root instruction asks Claude to read that record explicitly. You can instead use a documented @CONTEXT.md import in CLAUDE.md. Imports resolve relative to the importing file, can recurse four hops and have approval conditions for external paths; text inside Markdown code spans or fences is not expanded. Choose deliberately between an instruction to fetch a record and including it during startup. Import documentation

For example, suppose CONTEXT.md says that every API handler now uses the agreed error shape. Reading orders.ts then reveals a raw exception response. The record needs correction and the remaining handler needs work. Repeating the note in a new conversation would carry the error forward. A useful recovery record points to the relevant files, records the last check and distinguishes completed work from the next verification.

This is why I keep the rationale with a consequential decision. “Use this response shape” tells a future contributor what to do. “Clients parse error.code; error.message is for display; stack traces stay in internal logs” gives them something to evaluate when requirements change.

What compaction preserves

As a session grows, Claude Code can compact it: replace conversation history with a summary that fits the available context. A summary can omit a detail you still need. Current documentation also describes explicit restoration of several kinds of material:

MaterialDocumented behavior after compaction
Project-root CLAUDE.md and unscoped rulesRe-injected from disk
Nested CLAUDE.md and path-scoped rulesReloaded when Claude reads files that trigger them
Auto memoryRe-injected from disk
System prompt and output styleContinue to apply

The context-window documentation gives the full breakdown. Check the relevant file's loading conditions and inspect the changed code.

For a long refactor, I would repeat the check when work moves into a new subtree or resumes after compaction. Re-read a current-state record whose contents govern the next change, then verify its consequential claims. This keeps the recovery process tied to the files being worked on.

Auto memory and explicit project guidance

Auto memory saves selected notes for later sessions. With the feature enabled, Claude Code initially loads the first 200 lines or 25KB of its MEMORY.md index, whichever comes first; detailed topic files are read as needed. The documented default location is ~/.claude/projects/<project>/memory/, with configuration options that can change it. This is separate from a team-maintained CLAUDE.md. Auto memory documentation

The size rules differ, too: under 200 lines is guidance for keeping CLAUDE.md focused, while the documented file-loading limit is 4 MiB. Files above that limit are skipped. The memory index's 200-line/25KB cutoff is an actual initial-read boundary. Splitting a large instruction file into imports helps organization but still consumes context when those imports load.

A required API response contract belongs under review with the project's instructions and tests. An assistant's recollection of a preference can help it resume work, but the team needs to be able to inspect and change its own requirements. Use /memory to review saved notes and the feature's controls; inspect whether a note is still correct before acting on it.

An earlier version of this article cited Manthan Gupta's December 14, 2025 exploration, which probed the assistant through conversation and tested selected behaviors. He explicitly warned that model-reported internals could be inaccurate. That is useful exploratory work; it does not establish a fixed internal architecture for every Claude product.

Decode Claude's December 16, 2025 account examined an unreleased Claude Code feature in version 2.0.72. It described structured notes containing current state, task details, file references, errors and lessons. The appealing idea was inspectable Markdown that could carry selected knowledge across sessions. Its experimental directory and extraction schedule are historical details, not the current operating instructions above. Saving notes extends what a future session can recover; it does not create an unlimited context window.

OpenAI's December 2025 Sora Android case offers a related example: its authors describe maintaining instruction files and show guidance in a top-level AGENTS.md. Codex has its own discovery rules, including its directory chain and size limit. Their account describes that team's use of these files; clients still need their own configuration. The historical account remains available with a notice that Sora was discontinued on April 26, 2026.

Make the next session usable

I still find the new-colleague-with-notes analogy helpful. The colleague may arrive with a summary and may be able to retrieve more. I want the notes to identify the decision, its reason and the evidence needed to continue, without requiring a retelling of the entire project.

  1. Put recurring project requirements in maintained instructions, with concrete conventions a reviewer can check.
  2. Keep a current-work record, supply it explicitly and reconcile its claims with the repository or runtime before relying on them.
  3. Check which guidance reached the session, particularly after changing directories, entering a new subtree or compacting a long conversation.
  4. Review the result against the requirement. Fix missing guidance, stale records and implementation errors at the point where each actually occurs.

The Claude Code workflow article develops the wider practice within synthesis coding. For the API example here, the next useful check is specific: exercise a handler's failure path and inspect both the returned error and the record that says the work is complete.