The Memory System

The Problem with Starting Over

Without memory, every Claude Code conversation starts from zero. Claude doesn’t know your name, your coding preferences, your project’s rules, or the decisions you’ve made in the past. You end up repeating yourself:

• “Use TypeScript, not JavaScript”
• “Our app uses Tailwind CSS for styling”
• “Always write tests for new functions”
• “My timezone is Eastern”

Typing these reminders every session gets old fast. That’s where the memory system comes in — a way to teach Claude things once and have it remember them forever.

CLAUDE.md: Your Project’s Instruction Manual

The most important file in the memory system is called CLAUDE.md. It lives in the root of your project folder, and Claude reads it automatically at the start of every conversation.

Think of CLAUDE.md as a sticky note on top of a filing cabinet: “Here’s how we do things around here.”

Here’s what a simple CLAUDE.md looks like:

Now every time you start a Claude Code session in this project, Claude already knows the color palette, the font choices, and the rules — without you saying a word.

Auto-Generate with /init

You don’t have to write CLAUDE.md from scratch. Claude can analyze your project and generate one for you. Just type:

The /init command scans your project — the file structure, dependencies, configuration files, existing code patterns — and generates a CLAUDE.md that captures the essentials. It’s not perfect, but it’s a great starting point.

/init

After running /init, open the generated CLAUDE.md and review it. Add anything Claude missed. Remove anything wrong. This file is yours — you control what Claude remembers.

Pro Tip

Run /init every time you start a new project. It takes 10 seconds and saves you from repeating yourself in every conversation. Think of it as introducing yourself to a new coworker — do it once, and they remember.

What to Include vs What to Skip

Your CLAUDE.md should include the things you’d tell a new team member on their first day. Here’s a guide:

Include:

• What the project does (one sentence)
• Tech stack and main dependencies
• Coding style rules (formatting, naming conventions)
• Project-specific commands (how to run tests, start the server, deploy)
• Important decisions (“We use REST, not GraphQL” or “All dates are stored in UTC”)
• File organization patterns (“Pages go in src/pages, components in src/components”)

Skip:

• Obvious things (“JavaScript is a programming language”)
• Information that changes frequently (specific data, user counts, etc.)
• Secrets, API keys, or passwords (never put these in any file that could be shared)

Auto Memory: Claude Learns from You

Beyond CLAUDE.md, Claude Code has a built-in auto memory feature. When you correct Claude during a conversation, it remembers the correction for next time.

For example:

Next time you start a new conversation, Claude already knows you prefer TypeScript. You don’t need to say it again. The memory accumulates over time — the more you use Claude Code, the better it knows your preferences.

Your Personal CLAUDE.md

There’s a difference between project-level memory and personal memory:

• Project CLAUDE.md (./CLAUDE.md) — Lives in a specific project folder. Contains rules for that project. Shared with anyone who works on the project.
• Personal CLAUDE.md (~/.claude/CLAUDE.md) — Lives in your home directory. Contains your personal preferences. Applies to every project, on every session.

Your personal CLAUDE.md is where you put things like:

These preferences follow you everywhere. Whether you’re working on a portfolio site or a business dashboard, Claude will use TypeScript, write tests, and keep its responses concise.

Pro Tip

Your personal CLAUDE.md is private to your machine. It never gets committed to Git or shared with anyone. Put your real preferences there — Claude is the only one who reads it.

The Persistent Memory System

For power users, you can build a full memory system with multiple files. Instead of putting everything in one CLAUDE.md, you split it into organized files:

• decisions.md — Architecture choices and past decisions (“We chose PostgreSQL over MySQL because…”)
• preferences.md — Hard rules and workflow preferences (“Always run tests before committing”)
• people.md — Contacts and collaborators (“Designer: Sarah, sarah@design.co”)
• user.md — Your identity, accounts, and personal info

Your CLAUDE.md then references these files, telling Claude to read them at the start of each session. It’s like giving Claude a filing system instead of a single sticky note.

Here’s the exciting part — you can ask Claude to build this entire system for you:

Build a persistent memory system for me. Create a folder at ~/.claude/memory/ with these files: user.md (my identity and accounts), preferences.md (my workflow rules), decisions.md (architecture choices), and people.md (contacts). Then update my ~/.claude/CLAUDE.md to read these files at the start of every session and update them at the end.

Claude will create the folder structure, write template files, and wire everything together. From that point forward, every session starts by loading your full context and ends by saving anything new.

Remember this: I prefer dark themes on all projects, I use 2-space indentation, and my deploy command is 'npm run deploy'. Save this to my preferences.

Show me everything you currently know about my preferences and personal context. List out all the memory files and what's in them.

Pro Tip

Start simple. You don’t need the full multi-file memory system on day one. Just create a project-level CLAUDE.md with a few rules. Add your personal CLAUDE.md when you notice yourself repeating preferences. Build the full system when you’re ready for it.

Try It Yourself