How auto-memory works

When you work with Claude Code on a project, Claude automatically saves useful information it discovers to a memory directory:

~/.claude/projects/{project-path}/memory.md

This happens behind the scenes. As Claude explores your codebase, runs commands, and learns about your project's patterns, it writes those learnings to its memory file. The next time you start a conversation in the same project, Claude loads this memory and starts with context from previous sessions.

What gets saved to memory

Auto-memory captures things like:

• Build system quirks it discovered (e.g., "this project needs --legacy-peer-deps for npm install")
• Architecture patterns it identified (e.g., "all database access goes through the repositoryWhat is repository?A project folder tracked by Git that stores your files along with the complete history of every change, inside a hidden .git directory. Ask AI for more pattern in src/repos/")
• Error solutions it found (e.g., "TypeScript build fails if you forget to run codegen first")
• Project-specific terminology (e.g., "a 'workflow' in this codebase means a scheduled job, not a CI pipelineWhat is pipeline?A sequence of automated steps (install, lint, test, build, deploy) that code passes through before reaching production. Ask AI for more")

Telling Claude to remember something

You can explicitly ask Claude to save something to memory:

You: "Remember that our staging environment uses a different database
      URL than production, and we always need to run migrations there
      before deploying."

Claude: *saves this to memory for future sessions*

This is useful for context that is important but does not belong in CLAUDE.md, things that are personal to your workflow or temporary.

CLAUDE.md vs. Memory: when to use which

These two systems serve different purposes. Choosing the right one matters.

Use CLAUDE.md for:

• Tech stack and architecture decisions
• Build, test, and deploy commands
• Coding conventions the whole team follows
• Project structure overview
• Do/Don't rules that apply to everyone

Use memory for:

• Personal workflow preferences ("I like verbose git commitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. Ask AI for more messages")
• Temporary context ("we are migrating from Prisma to Drizzle this sprint")
• Discoveries about the codebase that are not conventions ("the auth moduleWhat is module?A self-contained file of code with its own scope that explicitly exports values for other files to import, preventing name collisions. Ask AI for more has a quirky initialization order")
• Environment-specific notes ("my local DockerWhat is docker?A tool that packages your application and all its dependencies into a portable container that runs identically on any machine. Ask AI for more setup uses port 5433 for Postgres")

User-level settings

The user-level CLAUDE.md at ~/.claude/CLAUDE.md is a middle ground between team CLAUDE.md and personal memory. Use it for preferences that apply across all your projects:

# ~/.claude/CLAUDE.md

## My preferences
- Keep responses concise, skip unnecessary explanations
- When suggesting changes, show the diff format
- Always run tests after making changes
- Use American English for comments and documentation

## My editor setup
- I use VS Code with Vim keybindings
- Terminal is iTerm2 with zsh
- I prefer to see file paths relative to project root

These preferences follow you from project to project without being imposed on your teammates.

Maintaining CLAUDE.md over time

A CLAUDE.md that was accurate six months ago might be misleading today. Here is how to keep it useful.

Review quarterly

Set a reminder to review your CLAUDE.md every few months. Check for:

• Outdated stack references. Did you switch from Jest to Vitest? Update the commands.
• Removed conventions. Did you drop the rule about CSS modules? Remove it.
• New tools. Did you add a linterWhat is linter?A tool that scans your code for style violations, common mistakes, and suspicious patterns without running it. Ask AI for more or formatter? Add the command.

Update after major changes

Certain events should immediately trigger a CLAUDE.md update:

• Major dependencyWhat is dependency?A piece of code written by someone else that your project needs to work. Think of it as a building block you import instead of writing yourself. Ask AI for more upgrade (e.g., Next.js 14 to 15), update the stack section
• New team convention (e.g., adopted conventional commitsWhat is conventional commits?A commit message format (e.g., feat:, fix:, chore:) that standardizes history and enables automated tooling like changelogs. Ask AI for more), add the rule
• Architecture change (e.g., moved from RESTWhat is rest?An architectural style for web APIs where URLs represent resources (nouns) and HTTP methods (GET, POST, PUT, DELETE) represent actions on those resources. Ask AI for more to GraphQLWhat is graphql?A query language for APIs where clients specify the exact shape of data they need in a single request, avoiding over-fetching and under-fetching. Ask AI for more), update the structure section
• New team member onboarding: if they needed something explained that Claude would too, add it

Pruning

Over time, CLAUDE.md files accumulate rules. Some become unnecessary:

• Rules about tools you no longer use
• Overly specific rules that Claude has learned through memory
• Rules that duplicate what is now obvious from the codebase itself

Remove these. A shorter CLAUDE.md is a better CLAUDE.md because it leaves more context windowWhat is context window?The maximum amount of text an AI model can consider at once, including your conversation history and any files it has read. Ask AI for more for your actual work.

Tips for maximum effectiveness

1. Test with fresh conversations

The best way to validate your CLAUDE.md is to start a brand new conversation and give Claude a task. If Claude makes a mistake that your CLAUDE.md should have caught, the instructions need improvement.

2. Be specific about what "right" looks like

Instead of "follow our coding style", show an example:

## API endpoint pattern
Every endpoint follows this structure:
1. Validate input with Zod schema
2. Check authorization
3. Execute business logic
4. Return standardized response

Example:

export async function createUser(req: Request) {

const input = CreateUserSchema.parse(req.body); // 1. validate

await requireAdmin(req); // 2. authorize

const user = await userService.create(input); // 3. execute

return ok({ user }); // 4. respond

}

3. Use the same language as your codebase

If your team calls things "services", do not call them "controllers" in CLAUDE.md. If your database tables are called "organizations" not "teams", use the correct term. Consistency reduces confusion.

4. Coordinate with your team

CLAUDE.md is committed to git. Treat it like any other team document:

• Review changes in pull requests
• Discuss new rules in team meetings
• Let team members propose additions based on their own experiences with Claude

The best CLAUDE.md files reflect collective team knowledge, not just one person's preferences.