Claude Academy

Claude's Learning System

Every time you correct Claude, express a preference, or share important project context, that knowledge disappears when the session ends. Next session, you repeat yourself.

Auto-memory fixes this. It's Claude's persistent learning system — a set of small files stored on your machine that Claude reads at the start of every session. Over time, Claude builds an evolving understanding of you, your preferences, and your project.

Think of auto-memory as the difference between working with a contractor who forgets everything between meetings and one who keeps notes.

Where Memories Live

Auto-memory files are stored in your home directory, organized by project:

~/.claude/projects/ ├── a1b2c3d4/ ← hash of /home/you/project-alpha │ └── memory/ │ ├── MEMORY.md ← index of all memories │ ├── user.md ← your role and preferences │ ├── feedback.md ← corrections you've made │ ├── project.md ← project context │ └── reference.md ← external pointers ├── e5f6g7h8/ ← hash of /home/you/project-beta │ └── memory/ │ ├── MEMORY.md │ ├── user.md

│ └── project.md

Each project gets its own memory directory, identified by a hash of the project path. This means memories from one project don't bleed into another.

The Four Memory Types

1. User Memory (user.md)

Stores information about you — your role, experience level, and personal preferences:

# User Memory

Senior backend engineer, 5 years experience
Prefers functional programming patterns
Uses macOS with iTerm2 and zsh
Wants concise explanations, not tutorials
Prefers TypeScript strict mode always

Claude builds this from conversations where you reveal preferences:

"I'm a senior engineer, you don't need to explain basic concepts" "I always use strict mode"

"Give me concise answers, not tutorials"

2. Feedback Memory (feedback.md)

Stores corrections you've made — things Claude got wrong that it should remember:

# Feedback Memory

Don't use console.log — use the project logger from src/lib/logger.ts
When writing tests, always use the test database helper from tests/utils/db.ts
The auth middleware is at src/middleware/auth.ts, not src/plugins/auth.ts
Always use cuid() for IDs, not uuid()
Date comparisons must use UTC — never local timezone

Every time you correct Claude, it has the opportunity to save that correction:

You: "No, we don't use console.log here. Use logger from src/lib/logger.ts"

Claude: [fixes the code and saves the correction to feedback memory]

Next session, Claude remembers to use your logger.

3. Project Memory (project.md)

Stores important context about the project that Claude discovered during sessions:

# Project Memory

Database uses soft deletes (deletedAt column) on all tables
The payment service was refactored in March 2026 — old patterns in git history are invalid
Webhook handlers must verify HMAC signature before processing
The user service has a circular dependency with the notification service (known issue, workaround in src/services/user/NOTES.md)
API versioning is done via URL prefix: /v1/, /v2/

This accumulates as Claude works in your codebase and discovers patterns, quirks, and important context.

4. Reference Memory (reference.md)

Stores pointers to external resources Claude should know about:

# Reference Memory

API documentation: https://internal-wiki.company.com/api-docs
Design system: https://figma.com/file/xxxxx
Architecture decision records: docs/adr/
Deployment runbook: docs/ops/deployment.md
The Stripe integration follows their v2023-10 API version

The MEMORY.md Index

Each project's memory directory has a MEMORY.md file that serves as an index:

# Memory Index

Last Updated: 2026-04-03

Active Memories
user.md: Senior backend engineer, prefers functional patterns
feedback.md: 12 corrections saved (logger, test utils, ID generation)
project.md: 8 context notes (soft deletes, payment refactor, webhooks)
reference.md: 4 external references

This helps Claude quickly assess what it knows before diving into the individual memory files.

How Memories Are Saved

Claude saves memories in two ways:

Automatic

During a conversation, when Claude detects a correction, preference, or important context, it may automatically save it as a memory. You'll see a note when this happens:

You: "We never use axios directly. Always use the HTTP client wrapper at src/lib/http.ts" Claude: "Got it. I've noted this preference and will use src/lib/http.ts for all HTTP requests going forward."

[Memory saved to feedback.md]

Explicit

You can directly tell Claude to remember or forget things:

# Save a memory "Remember that the auth service was completely rewritten last week — don't reference old patterns from git history" "Remember that I prefer detailed error messages in development but generic ones in production" "Remember that the payment team owns src/services/payment/ —

don't modify it without noting it needs their review"

# Remove a memory "Forget the note about using REST — we've switched to GraphQL"

"Forget that the auth service is being rewritten — it's done now"

The natural language interface makes it easy. No special commands or syntax needed.

How Memories Are Recalled

At session start, Claude reads all memory files for the current project. This happens automatically — you don't need to do anything.

During a session, memories influence Claude's behavior:

User memory: Claude adjusts its communication style and technical depth
Feedback memory: Claude avoids mistakes it's been corrected on
Project memory: Claude applies learned project context to new tasks
Reference memory: Claude knows where to find additional information

You can also ask Claude what it remembers:

"What do you remember about our testing conventions?"

"What feedback have I given you about error handling?"

Custom Memory Directory

By default, memories are stored at ~/.claude/projects//memory/. You can customize this with the autoMemoryDirectory setting:

{
  "autoMemoryDirectory": "/path/to/custom/memory"
}

This is useful for:

Shared team memory: Point to a shared directory where team members accumulate collective memories
Backup: Point to a cloud-synced directory (Dropbox, iCloud) for memory backup
Multiple machines: Point to a synced directory so memories follow you across devices

Managing Memory Over Time

Like any knowledge base, memories can become stale:

Periodic Review

Every few weeks, ask Claude to show its memories:

"Show me all your saved memories for this project"

Review them and clean up:

"Forget the note about the v1 API migration — that's complete"

"Update your memory: we've moved from Vitest to Jest"

Memory vs. CLAUDE.md

| Aspect | CLAUDE.md | Auto-Memory |

|---|---|---|

| Written by | You (manually) | Claude (automatically) + you (explicitly) |

| Stored in | Project directory | ~/.claude/projects/ |

| Committed to git | Usually yes | No |

| Shared with team | Yes | No (personal) |

| Best for | Stack, conventions, rules | Corrections, preferences, discoveries |

| Persistence | File on disk | File on disk |

They're complementary. CLAUDE.md is your deliberate project brief. Auto-memory is Claude's evolving notebook of things it's learned. Use both for the best experience.

Key Takeaway

Auto-memory gives Claude persistent learning across sessions. It stores four types of memories — user preferences, feedback corrections, project context, and external references — in files at ~/.claude/projects//memory/. Claude saves memories automatically when it detects corrections or important context, and you can explicitly tell it to "remember" or "forget" things. Over time, auto-memory turns Claude from a stateless assistant into one that genuinely knows your project and your preferences.

Auto-Memory: What Claude Remembers

Learning Objectives