The Forgetting Problem

AI has a fundamental weakness: it has no persistent memory. Every conversation starts from scratch. The project specs, coding styles, and deployment processes you told Claude yesterday — today it has forgotten everything. The context window is like a whiteboard that gets erased the moment the conversation ends.

This is fatal for a coding assistant that needs deep project understanding. Imagine a new colleague who wakes up with amnesia every morning — you have to explain everything from the beginning. That is AI without a memory system.

Claude Code solves this with a multi-layered memory mechanism.

Memory Hierarchy

CLAUDE.md: Persistent Memory

CLAUDE.md is Claude Code’s most important memory mechanism. It is a Markdown file that is automatically loaded into context at the start of every conversation. Think of it as an “employee handbook” written for Claude.

Claude Code reads CLAUDE.md from three locations:

• ~/.claude/CLAUDE.md — Global config, applies to all projects
• /project/CLAUDE.md — Project-level config, committed to Git and shared with the team
• /project/.claude/CLAUDE.md — Personal project config, can be added to .gitignore

How to Write an Effective CLAUDE.md

A good CLAUDE.md should contain:

# Project Name

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS v4
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + Playwright

## Project Structure
src/
app/          # Pages and routes
components/   # React components
lib/          # Utilities and business logic
prisma/       # Database schema

## Dev Commands
npm run dev     # Start dev server
npm run test    # Run tests
npm run lint    # Lint code

## Coding Standards
- Use functional components and hooks
- All components must have TypeScript type definitions
- Variable naming: camelCase
- File naming: kebab-case
- Commit messages: Conventional Commits

## Important Conventions
- API routes go under src/app/api/
- All DB operations through Prisma Client
- Never directly modify prisma/migrations/

Key principles: concise, specific, actionable. Don’t write prose — write directives. Claude faithfully follows every rule in CLAUDE.md.

The Difference Between “Memory” and “Context”

Understanding the distinction between these two concepts is crucial:

• Memory: Persistent information that exists across conversations. Includes CLAUDE.md, project settings, user preferences. Accessible in every conversation.
• Context: Ephemeral information that exists only in the current conversation. Includes conversation messages, tool call results, file contents read. Disappears when the conversation ends.

Memory (Persistent)              Context (Ephemeral)
┌─────────────┐                ┌─────────────┐
│ CLAUDE.md   │  ──loaded──▶  │ System prompt│
│ settings    │                │ Chat history │
│ Preferences │                │ Tool results │
│ Project cfg │                │ File content │
└─────────────┘                └─────────────┘
Persists across                Disappears after
sessions                       conversation ends

Memory Types in Claude Code

Claude Code manages several different types of memory:

User Preferences

Stored in ~/.claude/. Includes global settings, common MCP configurations, personal coding preferences. Applies to all projects.

Project Context

Stored in the project’s CLAUDE.md and .claude/ directory. Includes tech stack, coding standards, project structure. Shared with the team.

Session Feedback

When you correct Claude’s behavior during a conversation (“don’t use var, use const”), Claude can save this feedback as persistent memory, automatically following it in future conversations.

Auto Memory

Claude Code can automatically extract key information at the end of a conversation and save it. For example, if it discovers an important pattern in the project during debugging, it will suggest recording it in CLAUDE.md.

The Complete Workflow

Combining all these mechanisms, here is how Claude Code works in a typical coding session:

1. Load memory: Read CLAUDE.md, load project configuration
2. Understand task: Parse the user’s request
3. On-demand retrieval: Use Glob/Grep/Read to fetch relevant code
4. Execute task: Edit code, run tests in the Agentic Loop
5. Compact context: If conversation is too long, auto-summarize earlier content
6. Update memory: If important new info is discovered, suggest saving to CLAUDE.md

It is this multi-layered memory system that allows Claude Code to bridge the gap of forgetting — though each conversation still starts with a fresh context, persistent memory ensures critical knowledge is never lost.