Claude Code Memory Management - The Complete Guide

Why it matters

Claude does not actually "remember" anything between conversations. Every new session starts from zero. What creates the illusion of memory is instruction files that load automatically every time you start Claude Code.

The problem: the context window is limited. Every instruction file takes up space. If you have tons of huge files loading, less room remains for the code you're working on, and Claude starts making mistakes, less accurate, forgets things mid-task, misses instructions.

Our goal:only what's truly important loads every session. Instructions relevant only to Supabase should not load when you're working on CSS.

What loads into memory every session

When Claude Code opens, it loads these things before you even write your first message:

• •CLAUDE.md files: from your project and parent directories, up to ~/.claude/CLAUDE.md
• •MEMORY.md: the first 200 lines of Claude's automatic memory
• •Rules: files from ~/.claude/rules/ and .claude/rules/ (those without paths always load)
• •Skills descriptions: the description of every installed skill (even unused ones)
• •MCP instructions: instructions from each connected MCP server
• •System prompt: Claude Code's own instructions

When you see Large CLAUDE.md will impact performance, it means all of this together got too large. The fix is not always in CLAUDE.md itself - sometimes it's duplicate skills or MCPs you don't use.

The hierarchy - global vs project vs local

There are three layers of instructions. They load together and work with each other:

Precedence rule:when there's a conflict, the more specific file wins. CLAUDE.local.md > ./CLAUDE.md > ~/.claude/CLAUDE.md.

CLAUDE.md - your instructions

This is the main file. You write it, Claude reads it every session. The basic rule: under 200 lines. If it's larger, Claude misses instructions.

Example of a good global ~/.claude/CLAUDE.md:

# Global Rules

## General
- Always respond in English
- Don't ask questions when the intent is clear
- Never use em dashes

## Research Before Assuming
- Never make assumptions about library APIs
- Check docs via Context7 first
- Ask only if all research options fail

## Scope Discipline
- Only modify files related to the task
- When fixing X, don't touch Y and Z "while you're at it"

Don't put here: architecture docs, API endpoint lists, schema documentation. This is a place for personal preferences that apply everywhere.

MEMORY.md - what Claude remembers

There's an automatic memory system in Claude Code. It lives in~/.claude/projects/[project]/memory/. Claude writes things it learns while working there.

The structure: there's a MEMORY.md index file (only first 200 lines load), and it points to specific memory files that load only when needed.

# Memory Index

- [projects.md](projects.md) - Active projects with stacks
- [skills-setup.md](skills-setup.md) - Installed plugins and skills
- [feedback_no_em_dashes.md](feedback_no_em_dashes.md) - Never use em dashes
- [courses-clubs.md](courses-clubs.md) - Project-specific patterns

What to save:preferences you told Claude before ("don't use em dashes"), patterns you discovered ("project X uses Polar.sh not Stripe"), architecture decisions. What not to save: time-dependent info (PR status, current tasks).

Rules with scope - smart loading

This is the most important trick. Instead of a giant CLAUDE.md, split into small rule files in ~/.claude/rules/ or .claude/rules/, and each loads only when needed.

Example: a rule scoped to Fly.io files only:

---
paths:
  - "**/fly.toml"
  - "**/*flyio*"
  - "**/provisioning*"
description: Fly.io operations - loads only when touching Fly files
---

# Fly.io Operations

## Destroying an Instance
1. flyctl apps list
2. flyctl machines list --app <name>
...

Now this rule loads only when Claude opens a fly.toml or provisioning file. The rest of the time it takes no context space.

Split pattern: each topic (auth, billing, database, deployment, frontend, testing) in a separate file with its own paths.

Skills - lazy-loaded capabilities

Skills are like rules on steroids. Each skill is a folder with SKILL.md that defines when to use it, and Claude reads it only when appropriate.

The downside:each skill's description loads in the system prompt every session. If you have dozens of installed skills, their descriptions take up lots of context space.

The fix: periodic audit. In Claude Code run /memoryto see what's loading. Skills you don't use - remove them:

npx skills remove <skill-name>

When to use skill vs rule? Rule = instruction that applies to certain files. Skill = complete capability with scripts, references, and workflow. A skill is heavier than a rule.

MCPs - external connections

MCP (Model Context Protocol) is how Claude connects to external services - Supabase, Vercel, PostHog, Brave Search, etc. Each connected MCP adds instructions to the context.

Check all connected MCPs:

claude mcp list

If an MCP is not connected (Needs authentication) or broken (Failed to connect), remove it:

claude mcp remove <name>

Tip: MCPs from Claude.ai (not local) are managed via claude.ai/settings/integrations, not via CLI.

Best Practices - 9 golden rules

1. 01

   Keep CLAUDE.md under 200 lines. If larger, split into rules.

2. 02

   Use paths frontmatter. Infrastructure rules (Fly, Supabase, AWS) don't need to load always.

3. 03

   Separate global from project. Personal preferences in ~/.claude/, architecture in ./CLAUDE.md.

4. 04

   Use CLAUDE.local.md for personal stuff. Local URLs, notes, sandbox credentials. Add to .gitignore.

5. 05

   Audit monthly. /memory in Claude Code, claude plugin list, claude mcp list. Remove what you don't use.

6. 06

   Don't dump everything into CLAUDE.md. Claude can read files. Better to point at a document than paste it inside.

7. 07

   Document the reason, not just the rule. "Don't do X" without explanation gets forgotten. "Don't do X because last time it broke Y" sticks.

8. 08

   Let Claude remember on its own. The automatic MEMORY.md works well. If you corrected it once, it'll keep it.

9. 09

   Treat CLAUDE.md as a contract, not an encyclopedia. It's instructions, not a book. Short and direct works better.

The audit prompt

Instead of doing the whole audit manually, let Claude do it for you. Paste this prompt into Claude Code, and it will audit your setup and tell you what to fix:

I want you to audit and clean up my Claude Code memory setup.

Do these steps:

1. Run these commands and collect info:
   - ls -la ~/.claude/CLAUDE.md ~/.claude/rules/ ~/.claude/skills/
   - wc -l ~/.claude/CLAUDE.md ~/.claude/rules/**/*.md
   - find . -maxdepth 3 -name "CLAUDE.md" -not -path "*/node_modules/*"
   - claude plugin list (if available)
   - claude mcp list

2. Analyze and tell me:
   - How many lines in global CLAUDE.md (should be under 200)
   - Are there rules loading without scope (no paths frontmatter)?
   - How many project CLAUDE.md files exist and are they too large (over 200 lines)?
   - Are there duplicate or unused skills?
   - Are there broken or unused MCPs?

3. Give me a clear report:
   - What's good: X
   - What's not: Y
   - 5 specific things I can fix now

4. If I approve, do the fixes yourself:
   - Add paths frontmatter to relevant rules
   - Split large CLAUDE.md files into scoped rules
   - Remove unused skills/MCPs (with my confirmation)

Start and give me the report.

How to use:

1. •Open Claude Code (cd ~ && claude)
2. •Copy the prompt above
3. •Paste into Claude
4. •Get an organized report of what's good and what's not
5. •Approve Claude to fix (or fix manually)

Run this monthly. Your setup collects dust. Skills you forgot you installed, broken MCPs, CLAUDE.md that grew without you noticing. Half an hour of cleanup monthly = hours of Claude working well.