CLAUDE.md — Memory Layer: The "Constitution" of the Agent

In the overview article, we likened a "blank" AI to a talented employee who needs to be onboarded every day. CLAUDE.md is the first and most fundamental solution to that problem: a document that Claude reads at the start, so it never has to ask again, "What does this project do, and what are the conventions?"

This is the foundation of the entire toolkit. If CLAUDE.md is done well, all subsequent layers (Skills, Hooks, Subagents...) will function more smoothly. If done poorly, the agent will continuously "guess" the context.

What is CLAUDE.md and How Does It Work

Each Claude Code session begins with an empty context window. CLAUDE.md is a Markdown file you write; Claude reads it at the beginning of each session to have a sustainable context — code standards, build commands, architectural notes — without needing you to repeat them in every conversation (Claude Docs — Memory).

The correct visualization: it is like the "constitution" or onboarding document of the project. You write it once, and Claude follows it every time.

One technical detail worth noting (and often misrepresented): the content of CLAUDE.md is not inside the system prompt — according to the official documentation, it is read at the start of the session and included as a user message immediately after the system prompt (Anthropic Support — CLAUDE.md). The practical consequence: this is guidance with high weight but not an absolute command — Claude tries to follow it but does not guarantee 100%. For strict binding, we use Hooks (see Article 3).

Memory Hierarchy: 4 Layers, Loaded from Broad to Narrow

The true power of CLAUDE.md lies in its hierarchical structure. Claude Code loads multiple files in order, and the files are concatenated rather than overwritten (Claude Docs — Memory):

Loading rule: Claude traverses up the directory tree from where you run, gathering files from the root filesystem down to the working directory. Content that appears later tends to be "noticed" more — so narrower/specific guidance (project, local) naturally carries more weight than general guidance (user). The CLAUDE.md file in a subdirectory is loaded on demand when Claude reads the file in that directory, not at startup.

Implication for businesses: IT can place an organizational-level CLAUDE.md to enforce common standards across all machines and repositories — a light yet effective governance mechanism.

@import: Organizing Files, Not Stuffing

You can pull content from another file into CLAUDE.md using the @ syntax:

# Project Conventions
- Git process: @docs/git-instructions.md
- API standards: @.claude/rules/api-style.md

@import supports both relative/absolute paths and allows for multi-level nested imports — the documentation states a depth limit (sources note around 4–5 hops depending on the version), so don't nest too deeply (Claude Docs — Memory). If you only want to mention a path without importing, wrap it in backticks: ` @README `.

Important trap: @import helps to organize files neatly, but does not reduce tokens — the imported file is still fully loaded at startup. Don't assume that separating files saves context.

Two commands you need to know: /init and /memory

• /init — generates an initial CLAUDE.md by scanning the project. It also reads available convention files like AGENTS.md, .cursorrules, .windsurfrules if they exist. If you choose the personal option, it automatically adds CLAUDE.local.md to .gitignore.
• /memory — lists the memory files currently being loaded, allows toggling auto memory, and opens the memory directory for editing.

A compatibility tip: Claude Code reads CLAUDE.md, but does not read AGENTS.md directly. If your project uses AGENTS.md (a common standard across many tools), create a CLAUDE.md that consists of a single line @AGENTS.md for reuse.

A small but useful note: HTML comment blocks <!-- ... --> in CLAUDE.md are removed before entering context — used for notes to the reader without consuming tokens.

"Auto memory": a second memory, written by Claude

In addition to CLAUDE.md (written by you), Claude Code also has an auto memory system — where Claude automatically records lessons and patterns it discovers while working (commands used frequently, insights when debugging, your preferences). According to current documentation, it is stored in the project's local memory directory, with a file MEMORY.md serving as an index, and only the beginning of the index is loaded each session (the rest is loaded on demand) (Claude Docs — Memory).

Clearly distinguish between the two:

Four things named "memory" that are easily confused

This is the most confusing point for newcomers, and needs to be distinguished:

1. CLAUDE.md (Claude Code) — the guideline file you write, loaded into the session context.
2. Auto memory (Claude Code) — Claude automatically notes locally on the machine.
3. Memory tool (Claude Developer Platform / API) — a tool for Claude to create/read/edit/delete files in a memory directory set on your infrastructure, persistent across multiple conversations, helping to reduce context window pressure (Anthropic — Context management). This is an API tool, not a mechanism for loading guidelines in Claude Code.
4. Managed Agents memory store (Claude Developer Platform, beta) — a text document repository by workspace, when attached to a session will be mounted as a directory in the sandbox; includes audit logs, versioning, rollback (Claude Platform Docs).

When reading documentation or other articles, always ask: "Which 'memory' is being referred to here among the four above?"

Best practices: writing CLAUDE.md correctly

From the original documentation and Anthropic's "steering" framework (Claude Docs — Memory; Steering Claude Code):

• Concise. Aim for under ~200 lines. Long files consume context and reduce compliance levels.
• Specific over vague. "Use 2 space indentation" is better than "format code nicely"; "Run npm test before committing" is better than "remember to test."
• Avoid contradictions. Conflicting rules cause Claude to choose arbitrarily. Regular reviews are necessary.
• Place correctly. This is the most important principle:
• Rules like "Always do Y whenever X" → should be a Hook (mandatory), not wording in CLAUDE.md.
• Mandatory constraints like "Absolutely do not..." → Hook/permission, not CLAUDE.md.
• A lengthy procedure ~30 lines → should be separated into a Skill.
• Rules that only apply to src/api/** → should be a rule with paths: (loaded by file scope).
• Personal preferences → file user/local, do not include in the shared project CLAUDE.md.
• Organizational governance. Managed CLAUDE.md (and managed settings) applies to all sessions on the machine and cannot be excluded — used for mandatory company standards.

Minimal example

A good project CLAUDE.md does not need to be long:

# Project: izzi-web (Next.js 16, TypeScript)

## Conventions
- Use strict TypeScript; do not use `any`.
- Test with vitest; run `npm run verify` before committing.
- Components are placed in `src/components/`, named in PascalCase.

## Architecture
- Backend calls through `src/lib/api.ts` (Bearer JWT), do not fetch directly.
- Detailed git process: @docs/git-instructions.md

Short, specific, placed correctly — Claude can comply without consuming much context.

Summary & next steps

CLAUDE.md is the foundational memory layer: it provides Claude with sustainable context through a 4-tier hierarchy, organized by @import, initialized by /init, and checked by /memory. Remember two things: (1) it is guidance, not an absolute guardrail; (2) do not confuse it with the three other types of "memory."

However, there are pieces of knowledge/processes that are too lengthy or too specialized to fit into CLAUDE.md. That is when Agent Skills are needed — packaging expertise into modules loaded on demand. This is the content of Lesson 2.

References

• Claude Docs — Memory (CLAUDE.md): https://docs.claude.com/en/docs/claude-code/memory
• Anthropic Support — Give Claude context: CLAUDE.md (user message after system prompt): https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-prompts
• Anthropic — Steering Claude Code: https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more
• Anthropic — Context management (memory tool API): https://www.anthropic.com/news/context-management
• Claude Platform Docs — Managed Agents memory: https://platform.claude.com/docs/en/managed-agents/memory
• AZDIGI — Vietnamese Claude Code series: https://azdigi.com/blog

Lesson 1/7 in the "Agent Development Toolkit with Claude" series. Content reinterpreted from the original documentation by Anthropic. Previous ← Lesson 0: Overview · Next → Lesson 2: Agent Skills.