Skip to content
explainroo
Working with AI agents

Claude Code Memory and CLAUDE.md

Updated 3 min read

With explainroo How to Prompt a Coding Agent to Make an Explainer Video
On this page
  1. Put instructions in the right CLAUDE.md file
  2. Use automatic memory for changing project details
  3. Treat instructions as guidance, not access controls
  4. Start small and keep the files current

When you use Claude Code in a repository, a new session starts with a fresh context window. Files named CLAUDE.md and Claude Code’s automatic memory help carry useful information between sessions. A CLAUDE.md file contains instructions you write; automatic memory contains notes Claude Code creates about a project.

Use CLAUDE.md for stable guidance, such as coding conventions and test commands. Let automatic memory capture useful project details that change over time. Both provide context for Claude Code, so neither guarantees that Claude will follow an instruction or remember every detail. The Claude Code memory documentation describes how these sources fit into a session.

Put instructions in the right CLAUDE.md file

A project-level CLAUDE.md shares instructions with people who work in the repository. Place it at the repository root, or use .claude/CLAUDE.md. For personal preferences that should not be shared, use ~/.claude/CLAUDE.md. An organization can also provide instructions through enterprise settings.

Claude Code also supports CLAUDE.local.md for personal project settings. It is automatically added to .gitignore, which makes it useful for local preferences or notes that should stay on your machine. Claude Code can read AGENTS.md files as well, so check for those instructions when you join a repository.

For larger projects, put guidance near the code it concerns. A nested CLAUDE.md can provide instructions for a particular part of the repository. You can also import another file with @path/to/file; Claude Code loads the imported content with the file that references it. Imports can be nested up to four levels.

Keep each CLAUDE.md under 200 lines, as the official guidance recommends. A concise, specific instruction is easier to apply than a broad one. For example, “Use 2-space indentation” gives Claude Code a clear rule to follow; “Format code properly” leaves the meaning open to interpretation.

Use automatic memory for changing project details

Automatic memory stores project notes separately from your repository’s instruction files. Claude Code keeps the notes under ~/.claude/projects/, with a project-specific memory directory and a MEMORY.md file that acts as its index. The memory file layout can help you locate and inspect those notes.

Put lasting rules in CLAUDE.md and changing facts in memory. A coding convention belongs in the instruction file. A recent migration decision or a note about where a feature lives is more likely to belong in memory. Keep the index short and point to details rather than filling it with long explanations. Claude Code loads the first 200 lines of MEMORY.md at session start, so important notes should appear near the top.

Review memory from time to time. Notes can become outdated. One reported auto-memory corruption issue describes incorrect or partial information that carried into later sessions. Check remembered claims against the current code and documentation before relying on them. The /memory command lets you view and manage memory files.

Treat instructions as guidance, not access controls

Claude Code reads CLAUDE.md and memory as context. Claude Code follows concise, relevant instructions more consistently, but these files cannot block an action. If a command or tool call must be blocked regardless of what Claude decides, use a PreToolUse hook rather than relying on Markdown instructions.

Conflicting instructions also make behavior less predictable. When Claude Code gives an unexpected answer, check the project and personal CLAUDE.md files, nested instruction files, and rules under .claude/rules/. Remove or update instructions that no longer match the repository.

Start small and keep the files current

Run /init to create a starting CLAUDE.md based on the repository. If one already exists, Claude Code suggests improvements rather than replacing it. Then edit the file so it contains the commands and conventions that actually apply. Use /memory to review automatic notes, and remove details that are stale or no longer useful.

Write down information Claude Code needs repeatedly and keep it near the code or task it applies to. Verify details that might have changed. Avoid building a large custom memory setup before you know what the built-in files fail to preserve.

Free and open source

Let your AI agent make the video

explainroo lets a coding agent like Claude Code or Codex make narrated explainer videos and product demos. The voice, the word timing and the rendering run on your own computer, with no API key and no cost per video. Optional outside services use your own key.

Copy this into your AI agent

Make me a short explainer video about [your topic]. Use explainroo for it: run npx --yes explainroo docs and follow what it prints.

Getting started Example videos GitHub

Made with explainroo: How explainroo makes a video

More on working with ai agents

All guides on working with ai agents