Claude Code Memory Systems Explained: How Context, Sessions, and Persistence Work

Why Memory Matters for AI Coding

Every Claude Code conversation starts with a limited amount of "memory." Unlike humans, AI models can't remember everything you've ever said. They work with a context window — a fixed-size buffer that holds your current conversation.

Understanding how this works is the difference between a Claude Code session that feels like a brilliant pair programmer and one that seems to "forget" what you just said.

---

The Context Window: Your Working Memory

Claude Code uses Anthropic's Claude models, which have the following context window sizes:

| Model | Context Window | Effective Capacity | |-------|---------------|-------------------| | Claude Sonnet 4.5 | 200K tokens | ~150 pages of text | | Claude Sonnet 4 | 200K tokens | ~150 pages of text | | Claude Haiku 3.5 | 200K tokens | ~150 pages of text | | Claude Opus 4 | 200K tokens | ~150 pages of text |

> A "token" is roughly 0.75 words in English. So 200K tokens ≈ 150,000 words.

What fits in 200K tokens? - ~4-5 medium-sized code files (500-1000 lines each) - A full conversation history of ~40-50 exchanges - Plus the system prompt, tool definitions, and any uploaded files

External Links: - Anthropic Models Overview — context limits per model - Anthropic Prompt Design Guide — optimize your prompts for context efficiency

---

How Claude Code Uses Memory (Three Layers)

Claude Code has three layers of memory. Understanding them helps you know where information lives and when it might disappear.

Layer 1: Conversation Context (Volatile)

This is everything you've said in the current session. When you start a new claude command, you get a fresh conversation context.

Key behaviors: - New session = blank slate - Old conversations are not accessible from a new session - Claude Code saves conversation logs locally as markdown files

Where logs are stored:

# macOS/Linux
~/.claude/projects//conversations/
# Windows
%USERPROFILE%\.claude\projects\\conversations\

You can review past conversations by reading these logs:

ls ~/.claude/projects/*/conversations/ | tail -5

Layer 2: Project Files (.claude/)

Claude Code reads your project's .claude/ directory for persistent configuration:

.your-project/
├── .claude/
│   ├── settings.json         # Project-wide settings
│   ├── CLAUDE.md             # Persistent instructions (THE key file)
│   └── conversations/        # Session logs
├── src/
└── ...

The CLAUDE.md file is the most powerful memory tool. It acts as a permanent system prompt that Claude Code reads at the start of every session:

# CLAUDE.md — Project Instructions
Project Overview
This is a Next.js e-commerce site with Stripe payments.
Architecture
- App Router with TypeScript
- Prisma ORM with PostgreSQL
- Stripe for payments
Conventions
- Use named exports for components
- Use import type for type-only imports
- Always handle loading and error states
- Run pnpm test before committing
Critical Rules
- Never modify .env files
- Never commit to main branch directly
- Always create a feature branch for changes

> 💡 Pro tip: The CLAUDE.md file is incredibly useful for defining project-specific knowledge that should persist across sessions — things like architecture decisions, code conventions, and deployment instructions.

External Links: - Claude Code Settings & Config Docs - CLAUDE.md Best Practices

Layer 3: External Memory (File System & MCP)

Claude Code can read from your project's actual files. If you need it to "remember" something, write it to a file:

- Architecture decisions → docs/architecture.md - API documentation → docs/api.md - Setup instructions → README.md - Configuration → config/*.ts

Additionally, you can use MCP Servers to give Claude Code access to external memory systems:

# Example: Database memory via MCP
# Claude Code can query a database on demand

External Links: - MCP Servers Beginner's Guide — extend Claude Code with custom memory backends - MCP Specification — official MCP docs

---

Memory Limits in Practice

What Happens When You Hit the Limit?

When your conversation exceeds the context window, Claude Code does one of two things:

1. Truncation — The oldest messages are dropped from context (Claude "forgets" what you said early in the session) 2. Summarization — The AI tool may summarize earlier parts of the conversation to save space

Symptoms of approaching the limit: - Claude stops mentioning things you discussed 20+ messages ago - It "forgets" code it just showed you - Responses become shorter or more general - You see warnings about context usage

How to Check Your Current Context Usage

Claude Code shows context usage at the bottom of the terminal UI. The progress bar helps you see how "full" your context window is.

# Start a session and watch the context indicator
claude

---

Optimizing Memory Usage

1. Start Fresh for New Tasks

Instead of piling everything into one session, start a new session for distinct tasks:

# Session 1: Auth system
claude
> "build a login system"
# ... work in this session ...
# Exit (Ctrl+C/Cmd+C)
# Session 2: Payment integration (fresh context)
claude
> "implement Stripe checkout"

2. Use CLAUDE.md for Persistent Context

Any instructions in CLAUDE.md are available in every session without taking up conversation space.

Good candidates for CLAUDE.md: - Coding conventions - Tech stack details - Test framework and commands - Deployment process - Critical project decisions

3. Reference Files Instead of Pasting Code

Instead of pasting a 200-line file into the chat:

@src/components/Header.tsx — add a dark mode toggle to this component

Claude Code reads the file directly, without using up your context for the raw content.

4. Use MCP Servers for External Data

For large datasets or databases, configure an MCP server so Claude can query data on demand instead of keeping it in context:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@anthropic/mcp-sqlite"]
    }
  }
}

5. Break Large Tasks Into Steps

Instead of one massive prompt, break it into a sequence:

> Session 1: "Analyze the current codebase structure" > Session 2: "Based on the analysis, design the implementation" > Session 3: "Implement phase 1 of the design" > Session 4: "Implement phase 2"

Each session has full context for its subtask.

External Links: - Claude Code Hooks Automation Guide — automate context management - 7 Ways to Speed Up Claude Code — performance optimization

---

Common Memory Pitfalls

🚩 Pitfall 1: Assuming Claude Remembers Across Sessions

Each claude invocation is a fresh start. If you had a critical discussion in session A, don't expect session B to know about it.

Fix: Write conclusions to a file:

# After a big decision:
echo "## Decision: Use Prisma over Drizzle
- Rationale: Better migration support for our use case
- Date: 2026-05-11" >> docs/decisions.md

🚩 Pitfall 2: Conversation Too Long

40+ message sessions start losing early context.

Fix: Start a new session for each major feature. Reference decision files.

🚩 Pitfall 3: Ignoring CLAUDE.md

Not using CLAUDE.md means repeating instructions in every session.

Fix: Spend 5 minutes setting up CLAUDE.md at the start of each project.

🚩 Pitfall 4: Large File Context

Pasting entire files into the chat consumes tokens fast.

Fix: Use @filepath references or read specific sections only.

---

Summary

| Memory Type | Scope | Persistence | Best For | |-------------|-------|-------------|----------| | Conversation Context | Current session only | Session lifetime | Task-specific discussion | | CLAUDE.md | All sessions | Permanent (project-specific) | Conventions, rules, architecture | | Project Files | Per read | On-demand | Code, documentation, config | | MCP Servers | Per query | Real-time lookup | Databases, APIs, external data |

Understanding these three layers lets you work with Claude Code's memory instead of fighting against it. Use CLAUDE.md for permanent knowledge, start fresh sessions for distinct tasks, reference files instead of pasting them, and keep conversations focused.

Related Articles: - Agent Skills for Claude Code — add custom capabilities - How to Install Claude Code in 5 Minutes — if you haven't set it up yet - Effective Claude Code Prompts — reduce token waste in prompts