Claude Code Memory System

You just onboarded a new developer. They set up Claude Code and immediately asked it to “add a new API endpoint.” Claude generated an Express route — but your project uses Fastify. It created a JavaScript file — but your project is TypeScript-only. It put the file in src/routes/ — but your convention is src/api/v2/. Every assumption was wrong because Claude had zero context about your project.

The memory system solves this. It is how you teach Claude about your project’s architecture, conventions, and preferences — persistently, across sessions, shared with your team.

What You Will Walk Away With

• The complete memory hierarchy: managed, project, user, local, and auto memory
• Techniques for writing effective CLAUDE.md files that change Claude’s behavior
• Project rules with path-specific matching for large monorepos
• Auto memory management and the 200-line MEMORY.md limit
• Import patterns for modular, maintainable memory files

The Memory Hierarchy

Claude Code loads memory from six locations, each serving a different purpose:

Memory Type	Location	Who Sees It	Loaded When
Managed policy	System-level (deployed by IT)	All users	Always, highest priority
User memory	~/.claude/CLAUDE.md	Just you, all projects	Always
Project memory	./CLAUDE.md or ./.claude/CLAUDE.md	All team members	Always
Project rules	./.claude/rules/*.md	All team members	Conditionally, based on path
Local memory	./CLAUDE.local.md	Just you, this project	Always
Auto memory	~/.claude/projects/<project>/memory/	Just you, per project	First 200 lines

More specific memory takes precedence over broader memory. If your user CLAUDE.md says “use 2-space indentation” but the project CLAUDE.md says “use 4-space indentation,” the project rule wins.

Writing Effective CLAUDE.md Files

The Project CLAUDE.md

This is the most impactful file you will write. It is loaded into every Claude Code session for every team member working on this project.

# Project: Payments API

## Architecture
- Framework: Fastify with TypeScript
- Database: PostgreSQL via Prisma ORM
- Auth: JWT with refresh tokens stored in Redis
- API versioning: URL-based (/api/v2/)

## Key Commands
- `npm run dev` -- Start dev server on port 3000
- `npm run test` -- Run Jest tests
- `npm run test:watch` -- Jest in watch mode
- `npm run lint` -- ESLint with auto-fix
- `npm run db:migrate` -- Run Prisma migrations
- `npm run db:seed` -- Seed development data

## Code Conventions
- All API routes go in src/api/v2/
- Use Zod schemas for request/response validation
- Error responses follow RFC 7807 (Problem Details)
- Database queries use Prisma, never raw SQL
- All exported functions must have JSDoc comments
- Tests live next to source files: user.service.ts -> user.service.test.ts

## Do NOT
- Do not modify migration files after they have been committed
- Do not use console.log -- use the Logger service from src/lib/logger.ts
- Do not add new npm dependencies without checking bundle size impact

Tip

Copy-paste CLAUDE.md template for a new TypeScript project:

# Project: [PROJECT_NAME]

## Architecture
- Runtime: Node.js 20+
- Language: TypeScript (strict mode)
- Framework: [YOUR_FRAMEWORK]
- Database: [YOUR_DB] via [YOUR_ORM]
- Testing: [YOUR_TEST_FRAMEWORK]

## Key Commands
- `npm run dev` -- Development server
- `npm run build` -- Production build
- `npm run test` -- Run tests
- `npm run lint` -- Lint and auto-fix

## Code Conventions
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Error handling: always use typed errors, never throw raw strings
- Files: kebab-case for files, PascalCase for components/classes

## Common Patterns
- API calls: use the `fetcher` utility in src/lib/fetcher.ts
- State management: [YOUR_PATTERN]
- Auth: [YOUR_AUTH_PATTERN]

The Personal CLAUDE.md

Your user-level CLAUDE.md (~/.claude/CLAUDE.md) applies to all projects. Keep it focused on universal preferences:

# Personal Preferences

- Always explain your reasoning before making changes
- When you encounter a decision point, present options and ask me to choose
- Use concise responses -- skip summaries of what you just did
- When editing files, show a brief diff summary of changes
- I prefer functional programming patterns over OOP when possible

Local Overrides

CLAUDE.local.md is gitignored automatically. Use it for machine-specific details:

# Local Development

- My dev database runs on localhost:5433 (not default 5432)
- Test API endpoint: https://staging.internal.company.com/api
- Use `npm run dev:local` instead of `npm run dev` (custom env vars)

Project Rules

For large projects, a single CLAUDE.md becomes unwieldy. Project rules let you split instructions into modular, path-specific files.

Basic Rules

Create files in .claude/rules/:

.claude/rules/
  testing.md         # Testing conventions
  api-design.md      # API design standards
  database.md        # Database query patterns
  security.md        # Security requirements

Each file is loaded into context when relevant. Claude reads them as it works with files in matching paths.

Path-Specific Rules

Rules can target specific directories or file patterns using frontmatter:

---
globs: src/api/**/*.ts
---

# API Route Conventions

All API routes must:
1. Use Zod for input validation
2. Return typed responses using ApiResponse<T>
3. Include rate limiting via the @rateLimit decorator
4. Log all requests using the RequestLogger middleware

---
globs: "*.test.ts,*.spec.ts"
---

# Testing Standards

- Use descriptive test names: "should return 404 when user not found"
- Group related tests in describe blocks by method/function
- Mock external services, never make real API calls in tests
- Each test file should test a single module

Tip

Copy-paste rule for React component conventions:

Create .claude/rules/react-components.md:

---
globs: "src/components/**/*.tsx"
---

# React Component Conventions

- Use functional components with TypeScript interfaces for props
- Props interface named ComponentNameProps
- Export components as named exports, not default
- Co-locate styles: Component.tsx and Component.module.css
- Co-locate tests: Component.tsx and Component.test.tsx
- Use React.memo() only when profiling shows a performance benefit
- Prefer composition over prop drilling -- use context for deeply shared state

Auto Memory

Auto memory is where Claude writes notes for itself. Unlike CLAUDE.md (which you write for Claude), auto memory contains things Claude discovers during sessions.

What Claude Remembers

• Project patterns: build commands that work, test conventions, deployment steps
• Debugging insights: solutions to tricky problems, common error causes
• Architecture notes: key file relationships, module boundaries
• Your preferences: communication style, workflow habits

Managing Auto Memory

Auto memory is stored in ~/.claude/projects/<project>/memory/. The main file is MEMORY.md, and Claude may create topic-specific files alongside it.

~/.claude/projects/my-project/memory/
  MEMORY.md           # Main index, first 200 lines loaded at startup
  debugging.md        # Debugging patterns Claude discovered
  api-conventions.md  # API patterns Claude learned from your code

Use /memory to open and edit the auto-memory file. Remove entries that are outdated or incorrect.

Caution

Only the first 200 lines of MEMORY.md are loaded at startup. If your auto memory file grows beyond this, Claude will not see everything. Periodically review it with /memory and prune stale entries.

CLAUDE.md Imports

For large projects, you can split your CLAUDE.md into modules and import them:

# Project: Large Monorepo

@api-guidelines.md
@testing-standards.md
@deployment-checklist.md

The @path syntax imports the contents of the referenced file. Paths are relative to the CLAUDE.md file location.

When This Breaks

Claude ignores CLAUDE.md instructions: This happens when the context window is too full and older instructions get compacted away. Keep your CLAUDE.md concise (under 200 lines for the main file) and front-load the most critical rules.

Auto memory contains incorrect information: Claude sometimes records inaccurate patterns. Use /memory to review and correct entries. Delete anything that is wrong — stale memory is worse than no memory.

Rules do not apply to the right files: Check your glob patterns. The globs frontmatter uses standard glob syntax. Test with simple patterns first (src/**/*.ts) before using complex ones.

Local overrides not taking effect: Make sure your file is named exactly CLAUDE.local.md (not claude.local.md or CLAUDE_local.md). Claude Code automatically gitignores this file.

Team members have different behavior: This usually means someone has personal CLAUDE.md or local overrides that conflict with project settings. The precedence is: managed > local > project > user. Check all four levels.

What is Next

• Enterprise Integration — Managed policies and organization-wide memory
• Custom Commands — Build commands that leverage your memory configuration
• CLAUDE.md Optimization Tips — 10 specific tips for writing better memory files