--- title: "05 — CLAUDE.md — The Memory File the Loop Reads Every Launch" uid: claude-md-memory tags: ["roadmap:claude-code", "slash-commands", "configuration", "claude-md", "claude-code", "memory"] excerpt: "CLAUDE.md is persistent memory read at every launch, layered by directory — the project's WHY, WHAT, and HOW delivered to a model that forgets everything between sessions." date: 2026-08-13T03:28:22+0000 source: https://www.aveshina.my.id/en/blog/claude-md-memory --- "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. ```figure ~/.claude/CLAUDE.md global · personal defaults · every project project-root/CLAUDE.md team standards · version-controlled · the source of truth app/api/CLAUDE.md progressive disclosure · loads only when work is there read at every launch → copied onto the blank context window ``` 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](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](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](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](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](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](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](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](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](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](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](https://code.claude.com/docs/en/memory#determine-memory-type) ```quiz Q: Why does Claude read CLAUDE.md at the start of every session? - Because it has no other way to find files - Because every session starts with a blank context window; the file is the persistent memory re-applied each launch correct: 1 explain: Context wipes between sessions. CLAUDE.md is copied onto the blank window at launch so the model knows the project's build commands, style, and architecture without being told each time. Q: What belongs in CLAUDE.md? - Everything the model might ever need, including full code listings - Non-obvious info it can't infer: build/test commands, repo-specific style, architectural WHY, guardrails correct: 1 explain: The file should be short and human-readable. Code the model can read directly doesn't belong; the non-obvious rules and decisions do. Q: The hierarchical memory system loads files in which order at launch? - Subdirectory first, then root, then global - Global (~/.claude/), then project root, then subdirectory (progressive disclosure) correct: 1 explain: Claude searches from the working directory up to the root, layering global personal defaults, team root standards, and subdirectory-specific files (loaded only when work happens there). Q: What is the difference between /clear and /memory? - They do the same thing - /clear wipes the current context window; /memory opens the persistent memory file to edit long-term standards correct: 1 explain: /clear resets the session whiteboard; the memory file reloads next launch anyway. /memory edits the file that every future session reads. Q: You notice the model keeps ignoring a project rule across sessions. The right fix is… - type the rule more forcefully in each prompt - add/refine the rule in CLAUDE.md via /memory so every session starts with it correct: 1 explain: A repeatedly-ignored rule is a signal it's missing or unclear in the persistent memory file. Fix the file once and every future session inherits it. ```