Claude Code /memory Explained: Make AI Truly Remember Your Project

Why You Need /memory

One of the most frustrating things about developing with Claude Code is: every time you start a new session, Claude remembers nothing.

In the last conversation, you told it “the project uses TypeScript strict mode,” “commit messages follow conventional commits,” and “don’t touch anything in the legacy directory.” Close the terminal and reopen it — everything resets to zero. You have to say it all over again.

What’s worse is team collaboration — you spent thirty minutes teaching Claude your project conventions, but those conventions only exist in that one conversation. Different person, different session, start from scratch every time.

Every Claude conversation starts as a blank slate, but your project conventions shouldn’t.

That’s when you need /memory.

What Is /memory

/memory is a built-in Claude Code command for viewing and managing all memory files.

In interactive mode, type:

/memory

It lists all memory files loaded in the current session, including:

• CLAUDE.md files: Project instructions you wrote manually, distributed across different levels
• Auto Memory files: Notes and preferences Claude recorded automatically
• Rule files: Modular instructions under .claude/rules/

You can also use /memory to toggle Auto Memory on or off, or open the memory folder directly for editing.

Simply put, /memory answers one question: what does Claude currently remember?

Two Memory Systems

Claude Code has two complementary memory mechanisms that together solve the “cross-session memory” problem:

CLAUDE.md — Instructions You Write for Claude

CLAUDE.md is a Markdown file placed at your project root. Claude Code automatically loads it into the system prompt at startup. Whatever you write, Claude follows.

# CLAUDE.md

## Code Standards
- Use TypeScript strict mode
- Commit messages follow conventional commits
- 2-space indentation, 120 line width

## Project Structure
- src/api/ is backend code
- src/components/ is frontend components
- Do not modify any files under legacy/

Key characteristics: You write it, you control it, it’s committed to Git, shared with the team.

Auto Memory — Notes Claude Writes Itself

Auto Memory consists of notes Claude automatically records while working. If you correct a mistake, it quietly notes it down. If you say “always use bun instead of npm from now on,” it remembers.

Notes are stored in ~/.claude/projects/<project>/memory/MEMORY.md — plain Markdown files you can view, edit, or delete at any time.

Key characteristics: Claude writes it, it accumulates automatically, it’s not committed to Git, it’s personally private.

The Difference Between the Two

Dimension	CLAUDE.md	Auto Memory
Who writes it	You, manually	Claude, automatically
Storage location	Project root	~/.claude/projects/
Committed to Git	Yes, shared with team	No, personally private
When loaded	Every session startup	Every session startup (MEMORY.md only)
Best for	Project standards, architecture docs, team conventions	Personal preferences, debugging insights, lessons learned

CLAUDE.md Hierarchy and Loading

CLAUDE.md isn’t just one file — it has multiple levels, layered from global to project to personal.

Level 1: Global Memory

~/.claude/CLAUDE.md

Applies to all your projects. Put universal preferences here, like:

- Reply in Chinese
- Write commit messages in English
- Prefer functional programming style

Level 2: Project Memory

./CLAUDE.md

The file at your project root — the most commonly used level. Travels with Git, shared across the entire team. Put project standards, architecture docs, and tech stack conventions here.

Level 3: Personal Local Memory

./CLAUDE.local.md

A personal local file, added to .gitignore, never committed to the repository. Perfect for personal preferences like your debugging habits or preferred test framework configurations.

Level 4: Modular Rules

.claude/rules/*.md

The most flexible level — covered in detail below.

Loading Order

At startup, Claude Code walks upward from your current directory to the filesystem root, loading every CLAUDE.md it finds along the way. This means in a monorepo, a CLAUDE.md in a sub-package directory automatically takes effect when you work in that sub-package.

Important: CLAUDE.md survives context compaction — it’s re-read from disk and re-injected after compaction. If a rule disappeared after compaction, it only existed in the conversation, not in CLAUDE.md.

How Auto Memory Works

Auto Memory requires no effort from you — Claude decides on its own which information is worth remembering during work.

What Gets Remembered

• Your corrections: You say “that’s wrong, use X instead of Y,” and Claude notes it
• Explicit instructions: You say “remember to always use bun” or “don’t forget to run coverage in tests”
• Recurring patterns: You’ve corrected the same issue multiple times, and Claude realizes it should record it
• Key project info: Build commands, architectural decisions, important file paths

Storage Structure

~/.claude/projects/<project>/memory/
  MEMORY.md           # Main memory file, loaded at every session startup
  debugging.md        # Debugging insights (split by topic)
  patterns.md         # Code patterns
  api-conventions.md  # API conventions

MEMORY.md is the main file, automatically loaded into context at every session startup. Keep it under 200 lines.

Topic sub-files (like debugging.md) aren’t loaded at startup — Claude reads them on demand when needed. This preserves detailed information without wasting context window space.

Trigger Keywords

Want Claude to remember something? Use these keywords:

Remember: all new files should use the .tsx extension from now on

Don't forget: the test command is npm run test -- --coverage

When Claude detects keywords like “remember,” “don’t forget,” it proactively writes to MEMORY.md.

.claude/rules/ Modular Rules

As projects grow and conventions multiply, a single CLAUDE.md file becomes increasingly bloated. .claude/rules/ provides a modular solution.

Basic Usage

.claude/
  rules/
    code-style.md     # Code style conventions
    testing.md         # Testing standards
    security.md        # Security guidelines
    api-design.md      # API design standards

Each .md file is an independent set of rules that Claude Code automatically discovers and loads.

Conditional Loading: Glob Matching

This is the most powerful feature of .claude/rules/ — loading rules on demand based on file paths.

Add a paths field in the rule file’s frontmatter:

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

## API Standards

- All endpoints must validate input parameters
- Use a unified enum type for error codes
- Response format must be { code, data, message }

This rule only loads when Claude is working with TypeScript files under src/api/. When editing frontend components, these rules don’t appear, saving context space.

Practical Organization

.claude/
  rules/
    frontend/
      react.md          # paths: src/components/**/*.tsx
      styling.md         # paths: src/**/*.css
    backend/
      api.md             # paths: src/api/**/*.ts
      database.md        # paths: src/models/**/*.ts
    general/
      code-style.md      # No paths, loaded globally
      security.md        # No paths, loaded globally

Rule files without paths load globally at startup; files with paths load on demand.

Practical Use Cases

Case 1: Codifying Team Standards

Write your team’s coding standards, commit conventions, and architectural agreements into CLAUDE.md and commit to Git:

# CLAUDE.md

## Commit Standards
- Use conventional commits
- feat/fix/refactor/docs/test/chore

## Code Standards
- TypeScript strict mode
- No use of any
- Components use functional style

When a new team member joins, git clone and it’s automatically in effect. Standards go from word-of-mouth to code-as-documentation.

Case 2: Persisting Personal Preferences

Record personal preferences in Auto Memory or CLAUDE.local.md:

Remember: I prefer adding comments before functions explaining parameter meanings
Remember: when debugging, prefer console.table over console.log

These preferences won’t affect other team members, but they automatically take effect every time you start a new session.

Case 3: Domain-Specific Management in Monorepos

In a large monorepo, different sub-packages have different tech stacks and conventions:

.claude/
  rules/
    react-app.md       # paths: packages/web/**/*
    node-api.md        # paths: packages/api/**/*
    shared-utils.md    # paths: packages/shared/**/*

When Claude works in different sub-packages, it automatically loads the corresponding conventions. Frontend rules don’t pollute backend code, and backend conventions don’t interfere with frontend components.

Case 4: Rapid Onboarding for New Team Members

Day one for a new hire: git clone → open Claude Code → all project conventions automatically loaded.

No need to read through dozens of Wiki pages, no need for hand-holding from senior developers. Claude already knows all the project conventions — the new team member just collaborates with Claude normally, and the output automatically meets team standards.

Practical Tips

Tip 1: The 200-Line Rule

Both CLAUDE.md and MEMORY.md should stay under 200 lines. Beyond 200 lines, Claude’s adherence drops — too much context causes attention to scatter.

Move detailed content into sub-files under .claude/rules/ or into Auto Memory topic files. The main file should contain only the most critical rules.

Tip 2: Write Rules in Imperative Form

Don’t write descriptive sentences — write imperative instructions:

❌ The project uses TypeScript
✅ All new files must use TypeScript strict mode

Claude treats imperative statements as rules to follow, and descriptive statements as optional context. If you want Claude to strictly comply, use imperatives.

Tip 3: Regularly Clean Up Auto Memory

Auto Memory accumulates continuously, and over time, outdated or incorrect records are inevitable. Periodically check with /memory and remove content that’s no longer accurate. If an Auto Memory entry is stable and important, consider “promoting” it to CLAUDE.md.

Tip 4: Use /init to Quickly Generate CLAUDE.md

Don’t know how to write a CLAUDE.md for a new project? Just use:

/init

Claude will analyze your project structure, tech stack, and configuration files, then automatically generate a CLAUDE.md draft. Just modify it from there.

Final Thoughts

/memory solves a simple problem: making Claude’s memory persist beyond a single session.

When developing with Claude Code, the biggest waste isn’t Claude writing wrong code — it’s repeating the same things every time you start a session. Project standards said ten times, personal preferences emphasized eight times, architectural conventions re-explained every session.

Write them into CLAUDE.md, let Auto Memory accumulate automatically, use .claude/rules/ for on-demand loading. Say it once, and Claude remembers forever.

One command to make every conversation build on the last.