What Is Claude Code Context? A Complete Guide to Token Savings and Session Persistence
Understand Claude Code's context window from first principles — why your AI assistant forgets everything between sessions, and how to fix it with CLAUDE.md, spec checklists, handoff notes, git practices, and MCP-based automation.
What This Guide Covers
AI coding assistants — Claude Code, Cursor, GitHub Copilot, and others — lose all context when you open a new session. You settled on a design yesterday, but this morning the AI remembers nothing. You end up re-explaining the same project from scratch every time.
This guide explains how Claude Code's context window works from first principles, then organizes four manual techniques and an MCP-based automation approach by which structural cause each one addresses. Rather than a tips collection, the goal is to show "which remedy plugs which hole" — so you can evaluate new tools on your own as they appear.
How Claude Code's Context Window Works
LLM (large language model) inference is stateless. A Claude Code session feels like a conversation only because the full history of the exchange is fed to the model with every request (the actual API transport uses prompt caching to avoid retransmitting the unchanged prefix, but the model still reads and processes the entire history each time).
[Request 1] system + CLAUDE.md + your message 1
[Request 2] system + CLAUDE.md + message 1 + response 1 + message 2
[Request 3] system + CLAUDE.md + message 1 + response 1 + message 2 + response 2 + message 3
...
The cap on how much the model can read at once is the "context window." In Claude Code, the limit ranges from 200K to 1M tokens (roughly 150,000–750,000 words) depending on the model. As the conversation grows, older exchanges are automatically compressed; when the session closes, the history is no longer included in subsequent requests.
In practical terms, saving context = keeping the context window available for actual work rather than letting it fill with repeated explanations or exploratory reads.
The Five Structural Causes of Context Loss
Context loss decomposes into the following factors.
| # | Cause | Description |
|---|---|---|
| 1 | Frozen model weights | A trained model knows nothing about your specific project |
| 2 | Stateless inference | Conversation history is fed to the model per request, never retained server-side |
| 3 | Context window limits | There is a cap on how much can be read at once; older content falls out first |
| 4 | No persistent storage | Once a session ends, its history is no longer included in inference |
| 5 | Search vs. understanding | Code search indexes survive, but the reasoning behind decisions does not |
Every remedy ultimately reduces to one thing: a mechanism for re-injecting the necessary information into the next request. This lens makes it straightforward to evaluate any technique or tool.
Cause-to-Remedy Mapping
| # | Structural Cause | Effective Remedy |
|---|---|---|
| 1 | Frozen model weights (knows nothing about your project) | Context file (CLAUDE.md, etc.) |
| 2 | Stateless inference (full history fed to model each request) | Handoff notes / session persistence tools |
| 3 | Context window overflow (oldest messages drop first) | Information distillation (persist only distilled decisions) |
| 4 | No persistent storage (session close = history gone) | Writing to files (git / notes / tools) |
| 5 | Search indexes ≠ understanding | Structured state files |
Technique 1: CLAUDE.md (Context Files) — Addressing Cause 1
Overview
Place the slow-changing facts of your project in a file that is automatically loaded at session start. This directly addresses cause 1 (the model knows nothing about your project).
Claude Code uses CLAUDE.md, the cross-tool standard is AGENTS.md, Cursor uses .cursorrules, and GitHub Copilot uses .github/copilot-instructions.md. The AI reads these files automatically when a session begins.
Context Savings
Without a context file, Claude Code explores the project from scratch at each session start — reading files, checking dependencies, parsing configuration. This exploration alone consumes a significant portion of the context window.
With a context file, Claude Code starts each session with the project's fundamentals already loaded. No context is spent on exploration; it goes directly to the actual work.
What to Write
Start with your tech stack — that alone eliminates Claude Code's exploration phase.
// filename: CLAUDE.md
# Budget Tracker App
## Project Overview
A personal budgeting app. Next.js + Supabase.
## Tech Stack
- Frontend: Next.js 14 (App Router)
- DB: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Deploy: Vercel
## Coding Conventions
- Function components only
- Styling with Tailwind CSS
- Tests with Vitest + Testing Library
## Current Status
- Basic CRUD is complete
- Authentication in progress
- Category analytics not started yet
If you have explained the same thing to the AI twice, it belongs in CLAUDE.md. After explaining, tell Claude Code: "Add what I just explained to CLAUDE.md." You do not need to write it yourself.
Anti-Patterns and Remedies
| Anti-Pattern | Symptom | Root Cause | Remedy |
|---|---|---|---|
| Context file bloat | AI response quality degrades; instructions in long conversations get ignored | Everything — changelogs, task lists, detailed specs — crammed into one file exceeding 200 lines | Keep to four sections (overview, stack, conventions, status) under 50 lines. Move volatile information to techniques 2 and 3 |
| Stale information left in place | AI works from outdated assumptions (deprecated APIs, changed conventions) | Fast-changing information written once and never updated | Record only slow-changing facts. Any information that changes more than once a week belongs in a separate file |
| Wrong filename | AI does not load the file at session start | Each tool has its own naming convention: CLAUDE.md (uppercase) for Claude Code, .cursorrules (dot prefix) for Cursor | Check the tool's documentation for the exact required filename |
Why It Works — How Claude Code Loads Context
CLAUDE.md is automatically injected into the prompt at session start. Claude Code reads ~/.claude/CLAUDE.md (global settings shared across all projects) first, then the project root CLAUDE.md, then .claude/ project settings, concatenating them into the system prompt. Every request begins with the project's baseline information already present, eliminating the need for the AI to explore on its own. It addresses cause 1 by teaching the model about the project through the filesystem on every session.
Limitations
Project fundamentals come through, but day-to-day decisions — "how far did I get yesterday," "why this design was chosen" — do not. CLAUDE.md is suited for slow-changing information; fast-changing information requires a different technique.
Technique 2: Spec with Progress Checklists — Addressing Cause 4
Overview
Write out the project's features as a spec with checkboxes. This enables Claude Code to accurately resume from unchecked items across sessions.
Context Savings
Without a spec, Claude Code investigates the project state on its own at session resumption. Information not visible in code — alternatives that were considered and rejected, what was planned next — cannot be recovered.
With a checklist spec, telling Claude Code "read SPEC.md and resume from the unchecked items" produces an accurate resumption.
What to Write
Documenting every feature is unnecessary. Three items you want to work on next are sufficient to start.
// filename: SPEC.md
# Budget Tracker App — Feature Spec
## Authentication
- [x] Login
- [x] Password reset
- Email sending via Resend (simpler API than SendGrid)
- Token expiry set to 1 hour
- [ ] Social login (Google)
## Expense Tracking
- [x] Manual entry
- [x] Category selection
- [ ] Receipt auto-import
## Analytics
- [ ] Monthly breakdown by category
After completing a task, tell Claude Code "Update the checklist in SPEC.md." The AI handles the update.
Anti-Patterns and Remedies
| Anti-Pattern | Symptom | Root Cause | Remedy |
|---|---|---|---|
| Spec-code divergence | AI works from stale assumptions (treats completed items as pending) | Checklist not updated for several days; actual code state and spec are out of sync | Instruct the AI to update checklist after each completed item. If updates are missed, sync at the start of the next session |
| Inconsistent granularity | Progress appears misleading (one large item done looks like 50% but is actually 10%) | Large items ("implement auth") mixed with small ones ("change button color") | Normalize to items completable in roughly one hour |
| Missing decision rationale | "What was done" is clear but "why" is untraceable | Only checkbox state is recorded; no design notes attached | Record the rationale and rejected alternatives in one line under each item |
Why It Works
A checklist writes "what is done and what is pending" to an external file. It addresses cause 4 (progress lost at session end) by persisting state to the filesystem.
Limitations
Creating and maintaining a spec is overhead. Tacit knowledge — alternatives considered and rejected, unwritten assumptions — tends to fall through the cracks.
Technique 3: Handoff Notes at Session End — Addressing Causes 2 and 4
Overview
At the end of a session, write down "what was done / what was decided / what comes next." If technique 1 (CLAUDE.md) conveys the project's slow-changing information, technique 3 conveys "what changed in today's session."
Context Savings
Without handoff notes, Claude Code can see what exists by reading code, but cannot recover why a particular implementation was chosen or how far along auxiliary work (test mocks, configuration) is. The longer the gap between sessions, the more the developer forgets as well.
With handoff notes, the previous session's distilled decisions, caveats, and next actions are available as a structured file, loadable at the start of the next session.
What to Write
Tell Claude Code "Write a handoff note" at the end of the session. A four-section format is recommended.
// filename: docs/handoff/2026-07-17.md
# Handoff Note — 2026-07-17
## What I Did
- Implemented password reset for auth
- Used Resend for email (simpler API than SendGrid)
## Decisions
- Password reset token expiry set to 1 hour
- Reset email template built with react-email
## Next Steps
- Implement social login (Google OAuth)
- Start with Supabase Auth Google Provider setup
## Blockers / Caveats
- Resend free tier is 100 emails/month — dev environment uses
a console.log mock to avoid burning the quota
At the start of the next session: Read docs/handoff/2026-07-17.md and start from there.
Anti-Patterns and Remedies
The timing of the write-out is critical. A "batch at the end" approach means a session that terminates unexpectedly leaves nothing behind.
| Anti-Pattern | Symptom | Root Cause | Remedy |
|---|---|---|---|
| Note decay | Notes exist but fail to restore context when read | Full conversation logs pasted instead of structured decisions | Record only distilled conclusions. Not "we used Resend" but "Resend adopted — reason: simpler API than SendGrid." Decision plus rationale, one line each |
| Forgetting to write | Next session starts with a context reset; same explanations repeated | Deep focus during work leaves no mental bandwidth at session end | Tell Claude Code at session start: "Remind me to write a handoff note before we wrap up." Or write at natural checkpoints, not just at the end |
| Scattered storage | AI cannot locate the note file at the next session | Notes saved to the desktop, project root, or other inconsistent locations | Fix a directory such as docs/handoff/ and use date-based filenames (YYYY-MM-DD.md) |
Why It Works
Handoff notes address cause 2 (stateless inference) and cause 4 (no persistent storage) simultaneously. They carry state across sessions via external files.
Persist distilled decisions, not full transcripts. Re-injecting an entire conversation quickly exhausts the context window (cause 3). Focus on recording "why that choice was made" and "what comes next."
Limitations
Three walls remain: (1) forgetting to write, (2) difficulty judging what will matter next during work, (3) the overhead of telling the AI "read this file" each session. These are exactly what technique 5 (automation tools) resolves.
Technique 4: Git Commit Messages and Branch Strategy — Supplementing Cause 4
Overview
If you use git, writing "why" in commit messages turns git log into a decision history that Claude Code can read directly.
Anti-Pattern → Recommended Pattern
| Dimension | Anti-Pattern | Recommended Pattern |
|---|---|---|
| Commit messages | fix bug / update / WIP | fix: 500 error on expired token — UTC/JST comparison mismatch |
| Commit granularity | 100 files changed in a single commit | "One decision = one commit" |
| Branch management | main only; WIP branches abandoned | Feature branches per task, merged on completion. WIP branches either resumed next day or deleted |
Concrete example:
❌ fix bug
❌ update auth
✅ fix: 500 error when using expired password-reset token
- Cause: token_expires_at stored in UTC but compared in JST
- Fix: normalize to UTC before comparison
Branch names serve as a progress board:
main
├── feat/auth-password-reset ← done, merged
├── feat/auth-social-login ← current
└── feat/analytics-monthly ← next
Why It Works
Having Claude Code run git status and git log --oneline -10 at session start recovers a significant amount of context. Git's change history acts as external persistent storage, supplementing cause 4.
Limitations
Git records only code-level changes. Project-management decisions — "what to work on next week," "why this feature was deprioritized" — do not appear in the diff. Combining with techniques 2 and 3 fills the gap.
Technique 5: MCP-Based Automated Session Persistence — Breaking Through the Manual Barrier
Overview
Automates the progress tracking, decision logging, and handoff notes performed manually in techniques 2–4. MCP (Model Context Protocol) — an open standard for AI-to-tool communication — enables tools that handle session handoff end to end.
Structural Difference from Manual Handoff
Manual handoff requires telling Claude Code "write a handoff note" at session end and "read this file" at session start. Automation tools handle both writing and reading autonomously.
The three walls of manual operation — (1) forgetting to write, (2) judging what to write, (3) loading overhead — are structurally eliminated.
Representative Tools
Claude Code Built-in (--continue)
claude --continue restores the previous session (as of July 2026). It replays the full conversation log — effective for short sessions, but long sessions hit the context window ceiling since the entire transcript is restored.
handoff-mcp (v0.24.9)
handoff-mcp is an open-source tool developed by the author (AlphaElements). The following describes its design philosophy and capabilities factually, not as a comparison or recommendation over other tools.
An MCP server that automates technique 3's handoff notes and technique 2's checklists. Instead of the full conversation, it saves only "distilled decisions," "task progress," and "next actions" as structured data in a .handoff/ directory. No cloud account required — all data stays in local text files.
A "project memory" feature automatically injects past decision rationale into the AI's context when related topics arise in future sessions.
The VSCode extension (handoff-vscode v0.9.0) adds a GUI for task lists, session history, and progress tracking.
Cline Memory Bank / Roo Code Memory Bank
Memory management tools for Cline and Roo Code. They save structured snapshots of your project state — tech stack, current status, active tasks. Conceptually close to an auto-updating CLAUDE.md.
How to Choose a Tool
| Tool | What It Persists | Characteristics | Developer |
|---|---|---|---|
claude --continue | Full transcript | Simple, but long sessions overflow the window | Anthropic |
| handoff-mcp | Distilled decisions + task progress | Local files only, structured data | AlphaElements (this site) |
| Cline Memory Bank | Project state snapshot | Close to auto-updating CLAUDE.md | Cline community |
The axis for choosing is what it persists. How each tool handles cause 3 (context window overflow) is the design decision that distinguishes one from another.
Anti-Patterns and Remedies
| Anti-Pattern | Symptom | Root Cause | Remedy |
|---|---|---|---|
| Over-reliance on the tool | Tool is installed but user cannot tell what is being automated | Adopted automation without experience in manual techniques 2–4 | Practice techniques 1–3 manually first; automate once the habit is established |
| Design philosophy mismatch | Gap between what the tool persists and what the user actually needs | Adopted without checking the tool's "what to persist" design | Review the comparison table above and select a tool that matches the workflow |
Regardless of the tool, write at natural checkpoints during the work — not in one batch at the end. If the session terminates unexpectedly, a batch-at-the-end approach leaves nothing behind.
Comparison and Recommended Adoption Order
| Technique | Causes Addressed | Strength | Effort |
|---|---|---|---|
| 1. CLAUDE.md | 1 | Conveying project fundamentals | Low (write once) |
| 2. Spec + checklist | 4 | Tracking progress | Medium (upfront writing) |
| 3. Handoff notes | 2, 4 | Recording day-to-day decisions | High (every session) |
| 4. Git practices | 4 | Code-change history and rationale | Low (part of existing workflow) |
| 5. MCP persistence | 2, 3, 4 | Automating techniques 2–4 | Low (setup only) |
Recommended Adoption Order
Immediately (10 minutes):
- Create a
CLAUDE.mdat the project root and record the tech stack - From the next commit onward, include "why" in each commit message
Within one week:
- At the end of each session, instruct Claude Code to create a handoff note
- Write the project's main features as a checklist in
SPEC.md
After manual habits are established:
- Adopt an MCP-based persistence tool
CLAUDE.md (technique 1) and handoff notes (technique 3) alone produce a noticeable improvement in next-morning session starts. Developing a sense of "what is worth persisting" through manual practice makes it easier to understand and leverage an automation tool when the time comes.
Summary
The "my work never accumulates" problem in Claude Code stems from stateless inference. The solution is not to wait for smarter models but to design the re-injection of information into the context window.
Every technique and tool is an answer to "what goes into the next request." With that lens, you can evaluate any new tool on your own as it appears.