The Claude Code Memory System

Anyone who’s worked with Claude for more than a few conversations knows the frustration. Every new conversation starts from zero: explain again what you’re working on, how you like to work, what you’ve tried and thrown out. That doesn’t just waste time. It hurts quality, because the person tired of explaining keeps it short, and Claude is left with an incomplete picture.

This guide solves that.

It’s built in two parts. First, the basics. Three simple systems that get Claude to remember projects, understand how you work with it, and stop repeating the same mistakes. Second, the full system. How to get Claude to not just remember, but learn the person in front of it over time.

At the end of each part, a ready-to-use starter kit. Copy, adapt, start working.

Part One

The basics: how to make Claude remember a project

The problem

Claude looks smart inside a conversation. It remembers what you said three lines earlier, it adapts, it makes decisions that feel intelligent. But the moment you close the window and open a new conversation, all of it is gone.

It doesn’t know what projects you’re working on. It doesn’t know that in the previous conversation you told it three times not to add comments in code. It doesn’t know the system runs on Python 3.11, that the site is in Hebrew RTL, or that there’s an iron rule against using the color purple.

Every conversation, the same opening. The same first minute wasted bringing it up to context. The same feeling of “I spend most of my time explaining, and less of it actually working.”

This problem isn’t solved by “explaining better.” The opposite: the more you explain in the first message, the longer and more draining the conversation becomes, and quality drops because Claude chokes on the massive context. The fix goes the other way: move the explanation from the prompt into a file that Claude reads on its own in every conversation.

That file is CLAUDE.md.

CLAUDE.md: the file Claude reads in every conversation

CLAUDE.md is a simple markdown file that Claude reads automatically at the start of every conversation. Without you asking. Without you mentioning it. This file turns the experience from “I need to explain” to “it already knows.”

There are two types of it, and both matter.

Type one: global CLAUDE.md.

This file lives at ~/.claude/CLAUDE.md (on Windows: C:\Users\[name]\.claude\CLAUDE.md). It gets loaded into every conversation, no matter which project you’re working on. This is where you put personal preferences that don’t change:

• How to communicate (English? Short answers? Detailed ones?)
• How to work (plan before code? Confirm before costly actions?)
• What not to do (don’t add features you weren’t asked for, don’t clean up code unrelated to the task)

This file becomes Claude’s fixed identity when working with you. Every conversation, in every project, opens with that introduction already in place.

Type two: project-level CLAUDE.md.

This file lives at the root of each project. For example: C:\Users\[name]\HelloWorld\CLAUDE.md. It’s only read when you’re working inside that project. This is where you put everything specific to that project and nothing else:

• The stack (Python 3.11? Node 20? React?)
• The conventions (snake_case for functions? Comments in a specific language? Certain folders for test code?)
• The folder structure and important files
• What you’ve already tried and dropped. Especially important. This stops Claude from suggesting again a solution that already failed.
• Links to the DB schema, API docs, or any internal doc needed

A real example.

# CLAUDE.md - HelloWorld project

## Stack
- Python 3.11
- FastAPI + SQLAlchemy
- Postgres 15

## Rules
- All code in English. Hebrew comments allowed.
- snake_case for variables and functions.
- Don't add new dependencies without asking.

## What we tried and dropped
- Redis for cache: killed performance, dropped to local cache.
- Async raw SQL: staying sync for now.

## Important files
- db/schema.sql       # the official schema
- docs/api.md         # the API contract

Not a fancy document. Just a list. One line per decision. The cleaner and shorter the file, the better Claude uses it.

Why this works.

Because Claude actually reads it. Every conversation. Automatically. Once you’ve written a proper CLAUDE.md for the project, you don’t need to explain the stack, the conventions, and the “don’t do” list again. A new conversation opens and responds as if it’s day three of the job, not day one.

The instructions/ folder: saved guidance

After a few months of working with CLAUDE.md, you’ll discover a new problem: the file gets huge.

Guidance stacks up. Communication style. Writing rules for sites. A checklist of things not to do in certain projects. Everything gets crammed into one file that swells to 300 lines, and then it’s hard to update, hard to read, and Claude itself starts missing things inside it.

The fix: break the guidance out into a separate folder called instructions/, and point to it from CLAUDE.md.

What it looks like in practice.

Instead of a giant CLAUDE.md file, you have this structure:

~/.claude/
├── CLAUDE.md                   # short, points to files
└── instructions/
    ├── 10_mistakes.md          # 10 common mistakes
    ├── general_workflow.md     # general workflow for any task
    ├── website_design.md       # design rules for sites
    └── website_questions.md    # opening questions for a site build

In CLAUDE.md you write something like:

## Building sites
Before starting a site, read:
~/.claude/instructions/website_design.md
~/.claude/instructions/website_questions.md

## Every task
Before starting, read:
~/.claude/instructions/general_workflow.md
~/.claude/instructions/10_mistakes.md

That’s it. The main file is short, clear, points to the external files that hold the full content.

Why this is better.

• Easy to update. Discovered a new lesson about site design? Open website_design.md, add a line. CLAUDE.md doesn’t change.
• Easy to read. Every file is focused on one topic. No scanning 300 lines to find the rule you’re looking for.
• Easy to share. Want to share your standards with a new hire? Send the folder. They copy, ready to go.
• Claude uses it better. When you split the context into separate files, Claude loads only what’s relevant to the current task, instead of carrying 300 lines into every conversation.

In the starter kit at the end of this section, there are four ready-to-use instruction files. The same four I use myself. You can copy them as-is, or take them as a starting point and shape them into your own style.

10 mistakes I see over and over

Anyone working with Claude for more than a month starts noticing the same patterns of trouble. Things that keep repeating. I tracked them for months, and there are about ten. All of them are documented in the 10_mistakes.md file in the starter kit. Worth reading all of them, but three of them are critical enough that I’ll mention them here.

Mistake one: skipping Plan Mode.

This is the most painful one. The pull to type “build me X” and let Claude run is huge. And thirty minutes later you discover it built something that isn’t quite what you wanted. Or built something good, but in the wrong direction.

The fix: before any big task, enter Plan Mode (Shift+Tab twice), or just write “plan before you write a line of code.” Claude presents a plan, you approve or revise, and then it executes. The savings on rework are huge.

Mistake two: mixing planning and execution in the same conversation.

After you’ve planned, don’t execute in the same conversation. The context from the planning phase sits on Claude and makes it hesitant in execution. Instead: save the approved plan, open a new conversation (/clear), paste in the plan, and ask it to execute. Execution comes out clean and focused.

Mistake three: not using CLAUDE.md.

This is the exact mistake this whole part of the guide addresses. Without CLAUDE.md, you explain again in every session. With CLAUDE.md, you don’t. And still, most users never create one. If you only read one, make it this one.

The other mistakes (degraded context, vague prompts, giant files, no sub-agents, and more) are documented in full in the file in the starter kit. Worth reading in one sitting, and coming back to once a month to make sure you’re not slipping back into the same patterns.

I only covered the three critical ones here. Want to read all ten now, without downloading anything?

Part Two

The full system: how to make Claude learn you

Why the basics aren’t enough

Part one gave Claude a fixed identity: this is how we work, this is how the project is built, these are the things not to do. But there’s one big hole here.

CLAUDE.md is static. You write it once, and hope you don’t forget to update it.

In practice, you won’t remember.

Mid-conversation, you tell Claude “don’t add comments in code.” It fixes it. You move on. The conversation ends. That lesson, which could have been worth its weight for another fifty conversations, is gone. Because in the middle of the work, nobody stops to open CLAUDE.md, find the right spot, and update a line.

Another example: you discover that your way of phrasing questions to Claude works better when you propose options with a recommendation, not just a list of options. You tried it, it worked. But it stays as internal knowledge. In the next conversation, you’re back to getting just a list of options with no recommendation, and time is wasted again.

What’s missing is a system that does that annoying step automatically. That says at the end of a conversation: “I noticed we talked about X. Worth saving?” And offers it, so you don’t have to remember on your own.

That’s auto-memory.

auto-memory: Claude saves for you

auto-memory is an active memory system that works like this:

Throughout the conversation, Claude listens. It doesn’t just answer, it also notices details that could be useful in future conversations. A decision that was made. A preference that came up. A bug that got solved. A communication style that works.

At the end of a meaningful conversation, when a task wraps up or an important decision was made, Claude actively suggests what to save:

Claude: Before we wrap up, I want to suggest saving these to memory:

1. We decided on PostgreSQL over MongoDB
   because we need complex JOINs.

2. In your code, you don't want explanatory comments,
   only when there's a WHY not obvious from the code.

Approve all / choose / skip?

This isn’t magic. It’s an instruction in the global CLAUDE.md that tells Claude exactly this: “before ending a meaningful conversation, actively suggest what’s worth saving.” The file included in the full starter kit has this instruction ready.

Once you’ve copied it, your Claude sessions start ending this way. Before you say “thanks, let’s wrap,” Claude offers 2 or 3 lessons that came up during the conversation and are worth saving. You approve which are relevant, it saves.

Where does it save?

In a dedicated folder called memory/. Every memory is saved as a separate markdown file. Two things are essential here:

• A separate file for each memory. Easy to update, delete, or check what’s stored.
• A dedicated, agreed-upon folder. Claude knows where to look in every future conversation.

The structure of every memory file looks like this:

---
name: no_code_comments
description: Don't add code comments unless a non-obvious WHY is needed
type: feedback
---

Don't add comments explaining what the code does.

**Why:** the code speaks for itself with good names.
**When yes:** only when there's a non-trivial WHY, a hidden constraint,
a known bug, a fix that worked around something.

The frontmatter (3 fields at the top) is the metadata that lets Claude quickly identify what type of memory this is and when it’s relevant.

The active suggestion at the end of a conversation is the magic of the system. Without it, we’d have to remember to update. And we already said: we won’t.

The 4 memory types

Not every memory is created equal. There are different types of information worth saving, and separating them helps Claude decide when to pull a memory off the shelf and when to leave it.

The system has four types:

1. user: who the person in front of me is.

Role, background, level of knowledge, communication preferences. Things that shape Claude’s style with you, regardless of the specific task.

---
name: user_role
description: User background - experienced React dev, new to Python
type: user
---

Experienced front-end developer (8+ years React/TypeScript).
Recently started working in Python as well, but new to this stack.

How to use: when the conversation is in Python,
frame explanations in React terms when it fits.

2. feedback: how to work with me.

Corrections you made to Claude that should stick over time. Both explicit corrections (“don’t do X”) and quiet approvals (“yes, exactly, keep going like that”).

---
name: changes_table_before_edit
description: Before text edits, show a before/after table and wait for approval
type: feedback
---

Before any text change in files: show a table
| # | location | before | after |
and wait for approval.

**Why:** past attempts showed that without a table,
edits drift and hit content that wasn't meant to change.

3. project: what’s going on in the current work.

State, dates, decisions, partners, constraints. Information that shifts over time and needs current context.

---
name: merge_freeze_july
description: Merge freeze through July 15, mobile team cutting a release
type: project
---

Starting July 8, no merges except critical bugfixes.
Freeze ends the night of July 15.

**Why:** mobile team is cutting the 4.2 release branch on July 9.
**How to use:** flag regular PRs as "after freeze" until the date passes.

4. reference: where to find outside information.

Pointers to sources outside the code: Linear, Notion, Slack channels, dashboards. Claude uses these to know where to direct you.

---
name: bug_tracker_linear
description: Bugs are tracked in the Linear project called BUG
type: reference
---

All our bugs are tracked in Linear, project "BUG".
URL: linear.app/company/team/BUG

How to use: when talking about a specific bug, search there first.

Splitting into four types sounds bureaucratic, but it saves time: Claude loads only the memory types relevant to the current task, instead of carrying the whole history into every conversation.

MEMORY.md: the index

After ten memories are saved, twenty, fifty, a new problem starts: how does Claude know which memory is relevant to the current task?

The fix: an index file called MEMORY.md. It sits at the top of the memory/ folder, and appears automatically in every conversation. In this file, one line per memory, with a short description:

# Memory Index

# Communication preferences
- [user_role.md](user_role.md) : React dev, new to Python
- [user_language.md](user_language.md) : writes in English, prefers replies in the same

# Working rules
- [feedback_changes_table.md](feedback_changes_table.md) : before text edits, show before/after table
- [feedback_no_comments.md](feedback_no_comments.md) : don't add code comments

# Active projects
- [project_merge_freeze.md](project_merge_freeze.md) : merge freeze through July 15
- [project_redesign.md](project_redesign.md) : new homepage design, Q3

# External sources
- [reference_linear.md](reference_linear.md) : Linear for bugs
- [reference_dashboard.md](reference_dashboard.md) : Grafana for latency

Claude reads the index in every conversation. When it sees a conversation about a bug, it knows to open reference_linear.md. When it sees a design task, it knows to open project_redesign.md. It doesn’t load everything every time.

Important: MEMORY.md is an index only. Short lines. No substantive content. The content goes into the separate files. If MEMORY.md gets big and crowded, it means someone forgot this rule and put full paragraphs in it instead of index lines.

A live example: what it looks like in practice

Here’s a full scenario so it’s clear how the system works day to day.

User: I'm coming back to the landing page.
      Draft me a structure for the hero section.

Claude: [reads CLAUDE.md, instructions/website_design.md,
        and relevant memories from MEMORY.md]

        Got it. Before I start, things I remember about you:
        - Minimalist, no purple
        - No emojis (flagged 3 times before)
        - Preferred color for sites: green #8DC63F

        Continue with that, or has something changed?

That’s exactly the conversation that no longer starts from zero.

At the end of the conversation, after we worked and the hero is ready:

Claude: Before we wrap up, I noticed two things worth saving:

        1. We decided every section gets 80px padding
           on desktop and 40px on mobile.

        2. You asked for a minimum font-size of 18px for every CTA.

        Approve both? Choose? Skip?

User: Just the first. The second is specific to this project.

Claude: [saves only the first as feedback_padding.md]

That’s it. Another conversation ends, another two things were learned, one saved forever, without you having to remember to update anything yourself.