How to Manage Context Across Long Claude Code Sessions

Mar 10, 2026

The Problem

I started a new Claude Code session to continue work on a feature I’d been building for three days. The first five minutes were spent re-explaining the architecture. The next three minutes, re-stating my preferences. Another two minutes describing the constraints I’d already mentioned twice before.

Ten minutes lost to context rebuild. Every session.

The worst part? I knew I’d repeat this tomorrow. And the day after. Context loss was eating my productivity.

Why Context Management Matters

For quick fixes and single-session work, context loss is a minor annoyance. But when projects span multiple days or weeks, the problem compounds:

Session 1: ████████████ Full context
Session 2: ██████████░░ Lost 2 minutes re-explaining
Session 3: ████████░░░░ Lost 4 minutes
Session 4: ██████░░░░░░ Lost 6 minutes
Session 5: ████░░░░░░░░ Lost 8 minutes

A Reddit user with 1000+ sessions put it bluntly:

“After 1000+ sessions the one thing that scales is the CLAUDE.md file - not hooks or plugins, but structured context.”

The top comment (100 score) added:

“Most elaborate setups solve one of two things: reducing the cost of re-establishing context across sessions, or automating feedback loops.”

I was hitting the first problem hard. I needed a solution that scaled.

The CLAUDE.md Foundation

My first attempt at solving context loss was adding everything to CLAUDE.md:

# Project Name

## Architecture
[200 words describing every component...]

## Coding Standards
[150 words of rules...]

## Testing Strategy
[100 words on test coverage...]

## Deployment Process
[Another 100 words...]

## API Endpoints
[List of all 47 endpoints...]

...and so on for 300 lines

This backfired. Every session started with Claude reading all 300 lines. Most was irrelevant to what I was doing. Context was there, but it was noisy.

What Actually Works

The official documentation says CLAUDE.md should be “concise, dense, human-readable.” Project-specific patterns, not generic advice. I rewrote it:

# Payment Service

Handles subscription billing via Stripe.

## Commands

| Command | Description |
|---------|-------------|
| `npm run dev` | Start on port 3001 |
| `npm test` | Run tests (requires Docker) |
| `npm run db:migrate` | Run migrations |

## Architecture

src/ routes/ # Express endpoints services/ # Business logic models/ # Prisma schemas

## Key Files

- `services/stripe.ts` - All Stripe integration
- `routes/webhooks.ts` - Stripe webhook handlers

## Gotchas

- Stripe test mode requires TEST_API_KEY in .env
- Webhooks need Stripe CLI for local testing
- Always use `stripeTestData` fixture in tests

28 lines. Every line earns its place.

What to Include

From the official documentation and my experience, the essential sections:

Commands table - How to run, test, build
Architecture overview - Where things live (keep it brief)
Key files - Important files with one-line purposes
Gotchas - Non-obvious issues that bite repeatedly

Skip generic coding standards. Skip comprehensive API lists. Skip deployment runbooks. Add those to separate docs and reference them in CLAUDE.md if truly needed.

The Session Handoff Pattern

Even with a good CLAUDE.md, I still lost decisions made mid-session. Claude would suggest an approach on Monday, I’d agree, and by Wednesday nobody remembered why.

A Reddit user shared their solution:

“I always do an /init and instruct it to always create a plan, a todo and a session_handoff. Last instruction in the CLAUDE.md is to read the previous files at startup.”

I tried it. Here’s the setup:

Step 1: Update CLAUDE.md

## Session Workflow

At session start:
1. Read plan.md (current implementation plan)
2. Read todo.md (active tasks)
3. Read session_handoff.md (previous session notes)

At session end:
- Update session_handoff.md with:
  - What was accomplished
  - What's blocked
  - What to continue next session
  - Important decisions made

Step 2: Create Template Files

# Implementation Plan

## Goal
Integrate Stripe billing for subscription tiers

## Approach
1. Create subscription models in Prisma
2. Build Stripe customer sync
3. Implement webhook handlers
4. Add frontend billing UI

## Progress
- [x] Create subscription models
- [x] Build Stripe customer sync
- [ ] Implement webhook handlers (in progress)
- [ ] Add frontend billing UI

# Session Handoff - 2026-03-10

## Accomplished
- Completed subscription models with proper indexes
- Stripe customer sync working in test mode

## Blocked
- Webhook testing needs Stripe CLI setup
- Waiting on product team for tier pricing

## Next Steps
- Finish webhook handlers (see plan.md)
- Set up local webhook testing with Stripe CLI

## Decisions
- Using Stripe webhooks over polling (simpler, more reliable)
- Storing Stripe customer ID on User model (not separate table)
- Test mode API key committed to repo (test only, safe)

The handoff file became my session memory. Each session started with Claude reading three files. Total context restore: under 30 seconds.

Leveraging Hooks for Automatic Context

After using the handoff pattern for a month, I noticed I kept forgetting to update session_handoff.md at session end. Sometimes I’d close the terminal and lose everything.

Hooks solved this. But I started small.

Hook 1: Session Start Reminder

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "If session_handoff.md exists in the project, briefly summarize what was accomplished last session and what's next."
          }
        ]
      }
    ]
  }
}

This prompts Claude to review the handoff file at session start. No manual reminder needed.

Hook 2: Decision Capture

I noticed important decisions were scattered across chat history, never making it to session_handoff.md. I added a hook:

{
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "If this edit made an important architectural decision, suggest adding it to session_handoff.md under the Decisions section."
        }
      ]
    }
  ]
}

Now when I make a significant choice, Claude reminds me to document it.

When Hooks Over-Engineer

I considered adding more hooks:

Auto-update plan.md progress
Sync decisions to a knowledge base
Generate session summaries automatically

I stopped. The Reddit insight rang true:

“The point where minimal setups start to lose is longer projects spanning many sessions, when rebuilding context becomes the biggest time sink.”

My hooks addressed context loss. Adding more would solve problems I didn’t have.

The rule: hooks should reduce manual work, not create new workflows.

Progressive Context Strategy

After experimenting, I settled on three levels of context management:

Level 1: Minimal (Single Session Projects)

Just CLAUDE.md with the basics.

CLAUDE.md only
├── Commands table
├── Architecture (brief)
└── Gotchas

Good for: Bug fixes, single features, quick prototypes

Level 2: Handoff (Multi-Session Projects)

Add session continuity files.

CLAUDE.md
├── Commands table
├── Architecture
├── Gotchas
└── Session workflow instructions

plan.md           # What we're building
todo.md           # Active tasks
session_handoff.md # Session memory

Good for: Features spanning 2-5 sessions, ongoing maintenance

Level 3: Automated (Long Projects)

Add hooks for automatic context management.

Level 2 +
├── SessionStart hook (auto-load context)
├── PostToolUse hook (capture decisions)
└── (optional) MCP servers for external memory

Good for: Large projects, team collaboration, 10+ sessions

Choosing Your Level

How long will this project take?
       │
       ├── Single session ──────────────────▶ Level 1
       │
       ├── 2-5 sessions ────────────────────▶ Level 2
       │
       └── 5+ sessions or team project ─────▶ Level 3

Start at Level 1. Upgrade when you feel the pain.

Common Mistakes

Mistake 1: Over-Engineering Early

I built a Level 3 setup for a two-day project. The overhead exceeded the benefit. Start minimal, add complexity when context loss becomes your biggest time sink.

Mistake 2: Letting CLAUDE.md Go Stale

CLAUDE.md becomes outdated. Claude operates on wrong assumptions. Schedule a monthly review:

[ ] Commands still accurate?
[ ] Architecture reflects current structure?
[ ] Gotchas still relevant?
[ ] Any new gotchas to add?

Mistake 3: Hook Overload

Each hook adds cognitive overhead. Every PostToolUse hook fires on every edit. More hooks = slower operations = more interruptions. Focus on high-impact automation only.

Mistake 4: Ignoring Session Boundaries

Without planning for session end, context evaporates. The last 5 minutes of a session should be updating session_handoff.md. Make it a habit.

Quick Start Template

For your next project, try this minimal setup:

# [Project Name]

[One-line description]

## Commands

| Command | Description |
|---------|-------------|
| `npm run dev` | Start dev server |
| `npm test` | Run tests |
| `npm run build` | Production build |

## Architecture

src/ components/ # [purpose] services/ # [purpose] utils/ # [purpose]

## Gotchas

- [First non-obvious thing]
- [Second non-obvious thing]

Add session_handoff.md when the project spans multiple sessions. Add hooks when manual context management becomes tedious.

Claude Code’s architecture separates concerns intentionally:

CLAUDE.md: Always-on context (loaded every session)
Skills: On-demand workflows (invoked when needed)
MCP: External connections (database, APIs)
Hooks: Automation (triggered by events)

Each addresses a specific problem. CLAUDE.md is the foundation for context management. Skills, MCP, and hooks are optional enhancements.

The official documentation reinforces this:

“CLAUDE.md provides concise, dense, human-readable project context.”

Dense beats verbose. Specific beats generic. Updated beats comprehensive.

Summary

After months of experimentation and insights from developers with 1000+ sessions, the winning approach is clear:

CLAUDE.md is the foundation - Keep it concise, project-specific, and updated
Session handoff files bridge gaps - plan.md, todo.md, and session_handoff.md provide continuity
Hooks automate what you forget - But stop before you over-engineer
Start minimal, upgrade when painful - Level 1, then Level 2, then Level 3

The developer who’s run 1000+ sessions was right: CLAUDE.md scales. Everything else is optimization.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion Source
👨‍💻 Claude Code Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!