05 — CLAUDE.md — The Memory File the Loop Reads Every Launch

"Just a config file" was how I filed CLAUDE.md, and it took one blank-context session to see the point. The idea that landed: CLAUDE.md is persistent memory the loop reads at every launch, layered by directory, because every session starts with a blank context window. [1] It's the onboarding manual that re-applies itself automatically — the project's WHY, WHAT, and HOW, delivered to a model that otherwise forgets everything between sessions.

The framing that clicked is the contrast with the context window. Context is a whiteboard that wipes on /clear; CLAUDE.md is the file that gets copied onto the whiteboard at the start of every session before I type a single prompt [1]. Because the model begins each interaction blank, this file is what makes a session behave like it "knows" my project — the build commands, the architectural rules, the style conventions it couldn't infer from reading code alone. Slash commands like /init, /memory, /clear, /cost, and /status are the handles I use to manage the memory system around it.

What goes in it (and what doesn't)

The roadmap is blunt about the discipline, and it matches what I've seen go wrong [2]: the file should be short and human-readable, focused on the non-obvious information the model can't infer from the code. That means:

• Build, test, and lint commands — the exact bash invocations (npm run lint, npm run test) so the verify phase runs the right thing.
• Repository-specific style — naming conventions, file structure, "Server Components by default" type rules.
• Architectural decisions — the WHY behind choices that would otherwise look arbitrary (why cache tags, why a specific data-flow pattern).
• Things the model gets wrong without being told — the one-off quirks, the "never do X" guardrails.

What _doesn't_ belong: information the model can read directly from the code, or anything so long it bloats every session's tokens. The roadmap's word is "concise" — a source of truth, not a brain dump [2].

The slash commands that manage it

The memory system has a handful of commands, and reading them as operations on the file made them click:

• /init — the initialization utility. Creates a CLAUDE.md in the current folder, scaffolding the foundation for project-specific standards [3]. My starting point in any new repo.
• /memory — opens the memory file(s) in my editor so I can refine the persistent standards directly [4]. This edits the long-term store, not the current context.
• /clear — wipes the current context (the whiteboard) without touching the memory file [5]. The reset between unrelated tasks; the memory file reloads next launch anyway.
• /cost — real-time snapshot of monetary expense and token usage for the active session [6]. How I notice when context has bloated.
• /status — a dashboard of session health: version, model in use, account details, usage limits [7]. My pre-flight check before a big task.
• /help — the searchable directory of all commands and shortcuts [8]. The thing I reach for when I've forgotten a name.
• /rewind and /plan — covered in the workflow post, but they live in this command set too.
• /exit and /export — clean shutdown (saving history for -c to resume) and saving the conversation to a Markdown file for sharing [9].
• /doctor — diagnostic for installation health: auth tokens, network, dependencies like Git and Node [10].
• /usage — for Pro/Max subscribers, the remaining capacity report (not monetary cost) [7].

The way of thinking: /init and /memory shape the _persistent_ memory; /clear, /cost, /status manage the _session_ that reads it.

The layered hierarchy

The part that took longest to click is that CLAUDE.md is not one file — it's a hierarchical memory system layered by directory [11]. At the start of every session, Claude recursively searches from the current working directory up to the root, loading:

• Global preferences from ~/.claude/CLAUDE.md — my personal defaults across every project.
• Shared team standards from the project root's CLAUDE.md — the repo's source of truth, checked into version control.
• Subdirectory files via progressive disclosure — a CLAUDE.md inside app/api/ only loads when work happens there, keeping the top-level lean.

The practical payoff of the hierarchy is that I stop trying to put everything in one file. My personal preferences (response brevity, a preferred commit style) live globally. The repo's architecture lives at the root, shared with teammates through git. The API-specific quirks live next to the API code and only load when relevant. The top-level file stays short because the detail lives where the detail is used.

How I use this

The habit these notes left me with is treating CLAUDE.md as a product, not a one-time setup. I /init once, then refine with /memory every time I notice the model repeatedly getting something wrong — that's a signal the rule is missing from the file. I keep the root file ruthlessly short (build/test commands, the architectural WHY, the hard guardrails) and push detail into subdirectory files where it can be progressively disclosed. And I never use /clear as a way to "fix" a model that's ignoring my standards — if it's ignoring them mid-session, the fix is /memory to make them clearer, because the file is what every _next_ session will start from.

References

[1] Anthropic, "Manage Claude's memory," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/memory#manage-claudes-memory

[2] Anthropic, "Write an effective CLAUDE.md," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md

[3] Anthropic, "Interactive mode — /init," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode

[4] Anthropic, "Manage Claude's memory — /memory," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/memory#directly-edit-memories-with-memory

[5] Anthropic, "Interactive mode — /clear," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode

[6] Anthropic, "Using the /cost command," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/costs

[7] Anthropic, "Interactive mode — /status, /usage," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode

[8] Anthropic, "Built-in commands," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode#built-in-commands

[9] Anthropic, "Interactive mode — /exit, /export," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode

[10] Anthropic, "Interactive mode — /doctor," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode

[11] Anthropic, "Determine memory type," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/memory#determine-memory-type