Memory & CLAUDE.md
Project context
What Claude Code memory is and how it works
Memory in Claude Code is a set of plain CLAUDE.md text files that are loaded into the model's context automatically at the start of every session. It is not model training and not a database: it is ordinary Markdown that Claude reads as standing instructions for the project. Because of this you don't have to repeat in every prompt that the project builds with npm run build, uses TypeScript, or keeps tests in a certain folder — the model already knows it from the memory file. The more precise and compact your CLAUDE.md is, the fewer mistakes and clarifying questions you get.
Memory files form a hierarchy, shown below. The organization-managed level sets company-wide rules, the user file ~/.claude/CLAUDE.md holds your personal preferences across all projects, the project file .claude/CLAUDE.md is committed to git and applies to the whole team, and CLAUDE.local.md is for personal notes kept out of git. Claude Code doesn't pick one level — it combines them all, with more specific instructions extending the general ones. Through the import directive @path/to/file one file can pull in others — that is exactly what the @docs/api-conventions.md lines in the example above do: they split a large CLAUDE.md into modules that are easier to maintain.
Use memory for stable facts about the project: development commands, directory structure, code style, important modules. The /memory command (see the block below) lets you append a new rule straight from a session — for example "always use pnpm instead of npm" — and Claude writes it to the right file. The main pitfalls: storing secrets or API keys in memory (the file is committed to git), leaving stale instructions (they mislead the model worse than having none), and bloating the file with huge code blocks. Keep CLAUDE.md short and current and memory becomes the single most useful part of your Claude Code setup.
Claude Code loads instructions from multiple levels. All levels are combined:
Managed by organizationOrganization rules applied to all employee projects
~/.claude/CLAUDE.mdYour personal preferences for all projects
.claude/CLAUDE.md или CLAUDE.mdInstructions for the whole team, committed to git
CLAUDE.local.mdLocal settings, not committed to git
# CLAUDE.md ## Project Overview This is a Next.js 14 e-commerce application with TypeScript. ## Tech Stack - Next.js 14 with App Router - TypeScript 5.3 - Prisma ORM with PostgreSQL - Tailwind CSS + shadcn/ui ## Development Commands ```bash npm run dev # Start development server npm run test # Run Jest tests npm run lint # ESLint check npm run db:push # Push Prisma schema ``` ## Code Conventions - Use functional components with hooks - Prefer server components where possible - Use Zod for validation - All API routes should have error handling ## Directory Structure ``` src/ ├── app/ # Next.js app router ├── components/ # React components ├── lib/ # Utilities and helpers ├── prisma/ # Database schema └── types/ # TypeScript types ``` ## Important Files - src/lib/auth.ts — Authentication logic - src/lib/db.ts — Database client - prisma/schema.prisma — Data model
CLAUDE.md can import other files for modularity:
# CLAUDE.md ## Imports @docs/api-conventions.md @docs/testing-guide.md @.claude/rules/security.md ## Project specific rules ...
💡 Use @path/to/file to include file contents in context
Use /memory to quickly add information to memory:
✓ Recommended
- • Project description
- • Development commands
- • Directory structure
- • Code style and conventions
- • Important files and modules
- • Dependencies and versions
✗ Avoid
- • Secrets and API keys
- • Personal data
- • Huge code blocks
- • Outdated documentation
- • Information not for Claude
Memory Organization Tips
- 1.Keep CLAUDE.md up to date — outdated info is harmful
- 2.Split into modules for large projects
- 3.Use CLAUDE.local.md for personal settings
- 4.Commit .claude/CLAUDE.md to git for team
Frequently asked questions
What is CLAUDE.md and why do I need it?
CLAUDE.md is a plain Markdown file with standing instructions for your project that Claude Code automatically loads into context at the start of every session. You put development commands, directory structure, code style, and important modules in it so you don't have to repeat them in every prompt. It is not model training or a database, just notes that Claude reads as guidance.
Where are Claude Code memory files stored?
Memory forms a hierarchy of several levels. The organization-managed level sets company-wide rules. The user file ~/.claude/CLAUDE.md holds your personal preferences across all projects. The project file .claude/CLAUDE.md is committed to git and applies to the whole team. CLAUDE.local.md is for personal notes kept out of git. Claude Code combines all levels at once rather than picking one.
How do I add information to Claude Code memory?
Use the /memory command right in a session: run it, state what to remember (for example 'always use pnpm instead of npm'), and Claude appends the rule to the right CLAUDE.md file. You can also edit CLAUDE.md manually. Using the @path/to/file import directive, one file can pull in others, splitting a large CLAUDE.md into maintainable modules.
What should I avoid putting in CLAUDE.md?
Don't store secrets or API keys in memory — the file is committed to git and can leak. Avoid stale instructions: they mislead the model worse than having none. Don't bloat the file with huge code blocks or personal data. Keep CLAUDE.md short and current so memory stays the most useful part of your setup.
This lesson is part of a structured LLM course.
My Learning Path