Lesson 2.4: Understanding Claude's Memory

🎯 What You'll Learn: How Claude remembers information within sessions, across projects, and globally
⏱️ Time Required: 35 minutes
📦 What You'll Build: A memory strategy document for your automation project

---

Riley's Journey Continues

Riley's coordinated workflow is running smoothly. But she noticed something puzzling.

💬 "I asked Claude to draft a margin call summary, and it kept calling 'Initial Margin' calls 'collateral deposits', and once it referred to a 'Breach' as a 'flag'. Those aren't interchangeable in regulatory reports. My compliance team was confused. Then I realised - Claude doesn't know our specific terminology. Every conversation, I was re-explaining things. That's when I knew I needed to understand memory."
— Riley Harper

Where Riley is now:

✅ Coordinated multi-agent workflow running

✅ Saving 5 hours every Monday

🎯 Ready to make Claude remember important context

By the end of this lesson:

🧠 Riley will understand the three types of Claude memory

📋 She'll know when context persists vs. resets

📄 She'll be ready to build her CLAUDE.md file (Lesson 2.5)

---

What We're Building in This Lesson

Claude's memory works like a combination of a notebook (session), a company wiki (project), and personal preferences (global). Knowing which to use when makes Claude dramatically more helpful.

In this lesson:

Riley's "Breach vs. flag" problem

The three types of memory explained

Session memory: What persists in a conversation

Project memory: CLAUDE.md files

Global memory: Settings that apply everywhere

When to use which type

---

Key Concept: The Three Types of Memory

Overview

┌─────────────────────────────────────────────────────────────┐
│                    CLAUDE'S MEMORY                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │ SESSION MEMORY  │  │ PROJECT MEMORY  │  │   GLOBAL    │ │
│  │                 │  │                 │  │   MEMORY    │ │
│  │ Current chat    │  │ CLAUDE.md file  │  │             │ │
│  │ Resets on /clear│  │ Per-folder      │  │~/.claude/   │ │
│  │                 │  │ Auto-loaded     │  │CLAUDE.md    │ │
│  │ "What we just   │  │ "Company wiki"  │  │ "Personal   │ │
│  │  talked about"  │  │                 │  │  preferences"│
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
│         ▲                    ▲                   ▲         │
│         │                    │                   │         │
│    Temporary            Persistent           Universal     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Type 1: Session Memory

What it is: Everything discussed in the current conversation.

Persists: Until you run /clear or start a new session.

Think of it as: Notes from a meeting - useful during the meeting, gone after.

Riley's Example:

💬 "In one session, I told Claude that Meridian Capital is our highest-exposure counterparty. It remembered that for the whole conversation. But after /clear, I had to tell it again. Session memory is like a whiteboard that gets erased."

When session memory helps:

Building on previous context in a conversation

Iterating on work step by step

Claude remembering your preferences for this task

When session memory hurts:

Conversation gets too long (Claude slows down)

Earlier mistakes propagate through session

Need fresh perspective (use an agent instead)

---

Type 2: Project Memory (CLAUDE.md)

What it is: A markdown file that Claude reads at the start of every session in that folder.

Persists: Forever (until you change it)

Location: CLAUDE.md in your project root or .claude/CLAUDE.md

Think of it as: Company wiki or employee handbook - always available, always consistent.

Riley's Example:

# Margin Operations Context

## Team Information
- Firm: Mid-sized financial services firm
- Team: Derivatives Clearing Risk, Operations
- Scope: Margin reporting across equity and fixed income positions
- Reporting to: Head of Risk Operations (Marcus Webb)

## Margin Call Status (Use THESE exact terms)
- "Open" = margin call issued, awaiting counterparty payment
- "Disputed" = counterparty contests the call amount
- "Settled" = payment received and confirmed
- "Failed" = settlement deadline missed — escalation required

NOTE: Do NOT use "outstanding", "pending", "completed", or "overdue".
These terms have specific regulatory meanings in clearing confirmations.

## Position Risk Status (Use THESE exact terms)
- "Watch" = approaching exposure limits, monitoring required
- "Restricted" = new positions blocked pending review
- "Breached" = exposure limits exceeded — same-day escalation to Marcus Webb

NOTE: Do NOT use "flagged", "at-risk", or "warning" as substitutes.
Each status triggers different compliance actions.

## Key Metric Abbreviations
- "IM" = Initial Margin (NOT "collateral deposit" or "margin deposit")
- "VM" = Variation Margin (NOT "daily settlement" or "MTM payment")
- "Net Exposure" = counterparty exposure after netting agreements applied

Why this matters:

💬 "After I added the status terminology to CLAUDE.md, Claude never mixed up 'Breach' and 'flag' again. In a regulated environment, that's not just tidiness, it's accuracy the compliance team depends on. Project memory is like onboarding a new employee once and never having to repeat it."

---

Type 3: Global Memory (Global CLAUDE.md)

What it is: A CLAUDE.md file placed in your home ~/.claude/ folder, it loads in every project, every session.

Persists: Forever (until you change it)

Location: ~/.claude/CLAUDE.md

Think of it as: Personal preferences, how you like to work, regardless of which project you're in.

Example Global CLAUDE.md:

# My Global Preferences

## Communication Style
- Concise responses — bullet points over paragraphs
- Use tables when comparing options
- Flag anything that looks like a data inconsistency

## About Me
- My role: Operations Director
- I work in financial services — use professional language
- Prefer UK English spelling

💡 This file is separate from your project CLAUDE.md. Think of it as your personal assistant preferences, they follow you everywhere. Your project CLAUDE.md holds domain knowledge specific to that folder.

---

Memory Comparison Table

---

Exercise: Create Your Memory Strategy

⏱️ Total Time: 35 minutes

What You'll Build

📋 A memory strategy document that maps what goes where for YOUR automation project.

---

Step 1: Audit Your Repeated Instructions

⏱️ Time: 10 minutes

What you're doing:

Identifying what you keep telling Claude over and over.

Instructions:

Think about your last several Claude sessions. What did you have to explain multiple times?

Categories to consider:

Riley's Audit:

## Things I Keep Re-Explaining

### Terminology (Almost every session)
- Margin call status terms (Open/Disputed/Settled/Failed — NOT "outstanding", "pending", etc.)
- Position risk status (Watch/Restricted/Breached — NOT "flagged" or "at-risk")
- Key metric abbreviations (IM = Initial Margin, VM = Variation Margin)
- What "Net Exposure" means in our netting agreement context

### People & Structure (Often)
- Reporting to Head of Risk Operations (Marcus Webb)
- Which portfolio managers own which counterparty relationships
- My 2 direct reports (risk analysts)

### Processes (Sometimes)
- Monday report goes to Marcus Webb + Head of Derivatives Clearing
- IM variance threshold: >10% WoW requires explanation in report
- Breaches (£10M+ net exposure) require same-day escalation to Marcus

### Preferences (Every session)
- Concise bullet points, not paragraphs
- Tables for data comparison
- Flag anything over 10% variance

Your Audit:

## Things I Keep Re-Explaining

### Terminology


### People & Structure


### Processes


### Preferences

✅ Success Check:

---

Step 2: Map Information to Memory Types

⏱️ Time: 10 minutes

What you're doing:

Deciding where each piece of information should live.

Decision Framework:

Is this specific to ONE project/folder?
    YES → CLAUDE.md (Project Memory)
    NO  → Is this about MY personal preferences?
              YES → Settings (Global Memory)
              NO  → Only needed for this task?
                        YES → Just say it (Session Memory)
                        NO  → Probably CLAUDE.md

Riley's Mapping:

## Memory Mapping

### → CLAUDE.md (Project Memory)
- Margin and position terminology ✅ (Company-specific, regulatory impact)
- Risk status classifications ✅ (Domain knowledge)
- Team structure ✅ (Organisational context)
- Report process ✅ (Project-specific workflow)
- Threshold definitions ✅ (Business rules)

### → ~/.claude/CLAUDE.md (Global Memory)
- Prefer concise bullets ✅ (My style, all projects)
- Use tables for data ✅ (My preference)

### → Session Only
- Today's specific positions (changes daily)
- This week's priorities (temporary)
- Current conversation context (naturally accumulates)

Your Mapping:

## My Memory Mapping

### → CLAUDE.md (Project Memory)
-
-
-

### → ~/.claude/CLAUDE.md (Global Memory)
-
-

### → Session Only
-
-

✅ Success Check:

---

Step 3: Create Your Memory Strategy Document

⏱️ Time: 15 minutes

What you're doing:

Documenting your strategy for future reference and team sharing.

Create the file:

touch .claude/MEMORY-STRATEGY.md

Riley's Memory Strategy:

# Riley's Claude Memory Strategy

## Overview
This document defines what information goes where to ensure
consistent, effective Claude interactions across my automation project.

---

## Project Memory (CLAUDE.md)

### What Goes Here
Information specific to her firm risk operations that should be
available in every session working on this project.

**Include:**
- Team and firm information (context, scope)
- Margin and position terminology (critical — regulatory impact)
- Risk status classifications and definitions
- Team structure and key contacts
- Standard processes and thresholds
- Report formats and recipients

**Don't Include:**
- Today's specific numbers (use session)
- My personal preferences (use global)
- Temporary decisions (use session)

### File Location
`/margin-automation/CLAUDE.md`

### Update Frequency
- Review monthly
- Update when terminology changes
- Add new terms as discovered

---

## Global Memory (~/.claude/CLAUDE.md)

### What Goes Here
My personal preferences that apply across ALL projects.

**Include:**
- Response style: concise
- Preferred formats: bullets, tables, markdown
- Your name, role, and working context

**Don't Include:**
- Project-specific terminology
- Company information
- Domain knowledge

### File Location
`~/.claude/CLAUDE.md` (your home folder, not a project folder)

### Update Frequency
- Rarely (when your preferences change)

---

## Session Memory

### What Goes Here
Context for the current task only.

**Include:**
- Today's specific data and positions
- Current task requirements
- Decisions made this session
- Iterative work in progress

**Management:**
- Use /clear when starting a fresh task (this discards the conversation)
- Use /compact when a session you're still working on slows down (this keeps your work but frees up room)
- Use /context to check how full the context window is, so you know when to compact or clear
- Keep sessions focused on one workflow
- Don't let conversations get too long (>50 exchanges)

---

## Quick Reference

| Info Type | Memory Type | Location |
|-----------|-------------|----------|
| Company terms | Project | CLAUDE.md |
| My response style | Global | ~/.claude/CLAUDE.md |
| Today's exposure snapshot | Session | Current chat |
| Position status terms | Project | CLAUDE.md |
| Prefer tables | Global | ~/.claude/CLAUDE.md |
| This week's priorities | Session | Current chat |

---

## Common Mistakes to Avoid

1. **Putting style preferences in a project CLAUDE.md**
   - Wrong: "I like bullet points" in your project's CLAUDE.md
   - Right: Put it in `~/.claude/CLAUDE.md` — global, applies everywhere

2. **Putting project info in your global CLAUDE.md**
   - Wrong: Company-specific terminology in `~/.claude/CLAUDE.md`
   - Right: Put it in the project's CLAUDE.md so it stays scoped

3. **Not using /clear**
   - Symptom: Claude seems confused or slow
   - Fix: Start fresh with /clear for new tasks

4. **CLAUDE.md too long**
   - Symptom: Important info gets buried
   - Fix: Keep under 200 lines, prioritize critical info

---

Created: [Date]
Last Updated: [Date]
Next Review: [Date + 1 month]

Your Memory Strategy:

Create your own strategy document using Riley's as a template.

✅ Success Check:

---

Overall Success Criteria

By the end of this lesson, you should:

Quick Test:

Pick 5 random things you tell Claude. Can you instantly identify which memory type each belongs to?

---

Troubleshooting

🤔 "Claude keeps forgetting things I told it earlier in the session"

**Why this happens:** Very long conversations can cause earlier context to be deprioritized.

**Fix:**
- Keep sessions focused (one workflow per session)
- Use /clear and restart if conversation exceeds ~50 exchanges
- Put critical info in CLAUDE.md so it's always loaded

📝 "My CLAUDE.md doesn't seem to be working"

**Why this happens:** File location or naming issue.

**Fix checklist:**
- [ ] File is named exactly CLAUDE.md (case sensitive)
- [ ] File is in project root OR .claude/CLAUDE.md
- [ ] Content is valid markdown
- [ ] No syntax errors in the file

**Test:** Start new session and ask "What do you know about this project?"

⚡ "Sessions are getting slow"

**Why this happens:** Too much context accumulating.

**Fix:**
- Run /compact to summarise the conversation and free up room without losing your work (best when you're still mid-task)
- Use /clear for a clean slate when you're moving to a new task
- Keep CLAUDE.md focused (under 200 lines)
- Break long workflows into multiple sessions
- Use agents for isolated analysis (fresh context)

🔄 "Information inconsistent between sessions"

**Why this happens:** Relying on session memory for persistent info.

**Fix:** If you need info in every session, it belongs in CLAUDE.md, not session memory.

---

You Did It!

You now understand how Claude's memory works!

What Riley accomplished:

💬 "Once I understood the three memory types, everything made sense. No more repeating terminology every session. No more confusion about margin status terms. I put it in CLAUDE.md once, and Claude knows it forever. That's the power of understanding memory."

The transformation:

---

💡 The pattern: Once you stop explaining the same context every session and start putting it in CLAUDE.md, the improvement in Claude's responses is immediate and permanent. The audit is the shortcut, just notice what you keep repeating.

---