Scratchpads

Temporary workspaces that extend Claude's memory beyond context window limitations, enabling complex multi-step operations and session continuity.

What Are Scratchpads?

Scratchpads are external memory systems that help Claude maintain state, track progress, and coordinate work across sessions. Think of them as Claude's notebook - a place to write down important information, track decisions, and preserve context that would otherwise be lost.

Why Do We Need Them?

Claude has a limited context window (~200k tokens). During complex tasks, this fills up with:

• Code file contents
• Conversation history
• Tool outputs and errors
• Test results and logs

Without scratchpads, critical information gets lost when:

• The context window fills up
• You use /clear to reset the conversation
• You need to coordinate between multiple Claude sessions
• Complex debugging requires tracking multiple hypotheses
• Multi-day projects need session continuity

When to Use Scratchpads

Create a scratchpad when:

• Task complexity - Working on something that will take >30 minutes
• Multiple files - Coordinating changes across many files
• Context pressure - Approaching 75% context capacity
• Debugging - Investigating complex issues with multiple hypotheses
• Coordination - Working with multiple Claude instances or team members
• Session continuity - Need to preserve state across /clear or restarts

Where to Store Scratchpads

1. File-Based Scratchpads (Most Common)

Store as markdown files in your project:

• scratchpads/ directory for project-specific work
• Individual .md files for different tasks
• Version controlled with your code
• Accessible across sessions and team members

2. Memory Tool Storage (For Patterns)

Store reusable patterns in Claude's memory:

• Successful debugging approaches
• Architecture decisions that worked
• Patterns to apply across projects
• Long-term knowledge preservation

How to Create and Use Scratchpads

Creating Scratchpads

Ask Claude to create and maintain a scratchpad for your task:

"Create a scratchpad to track our payment processing implementation"

# Claude will:
# - Create a markdown file in the scratchpads/ directory
# - Update it as you work through the task
# - Track decisions, problems, and solutions
# - Preserve context for future sessions

Simple Examples

Example 1: Debugging Session

"Create a scratchpad for investigating the memory leak in production"

# Now work normally - Claude tracks everything:
"The app memory usage is growing 150MB/hour. Let's investigate."

# Claude updates scratchpad with:
# - Symptoms observed
# - Hypotheses tested
# - Evidence collected  
# - Root cause when found
# - Solution implemented

Example 2: Feature Implementation

"Let's use a scratchpad to track our user authentication implementation"

# Work through the implementation:
"Create a specification for JWT-based authentication"
"Now implement the login endpoint"
"Add tests for the authentication flow"

# Scratchpad maintains:
# - Specification decisions
# - Implementation progress
# - Test coverage status
# - Next steps for handoff

Reading Scratchpads Back

After /clear or in a new session:

# Reference the scratchpad
@scratchpads/adding-user-authentication.md
"Continue where we left off with the authentication implementation"

# Claude reads the scratchpad and resumes with full context

Context Window Management

When Context Fills Up

Claude will naturally manage context, but you can help:

# When approaching limits, Claude might say:
"Context window at 75%. Moving detailed logs to scratchpad..."

# You can also explicitly request:
"Move the API documentation discussion to a scratchpad and keep working"

# After /clear, retrieve what you need:
@scratchpads/api-documentation.md
"What was the decision about authentication?"

Session Handoff Pattern

When stopping work or handing off to another session:

# Session State - 2024-08-31

## What I Was Doing
Implementing Stripe payment integration

## Current Status  
- ✅ Basic payment flow working
- ⏳ Webhook validation in progress
- 📋 Refund handling not started

## Key Decisions
- Using Payment Intents API (not Charges)
- Idempotency keys for safety
- Webhook signatures for security

## Next Steps
1. Complete webhook signature validation
2. Test with Stripe CLI
3. Implement refund flow

## Files Changed
- src/payments/stripe.js
- tests/payments.test.js

Common Scratchpad Patterns

Bug Investigation

Track hypotheses systematically when debugging:

# Memory Leak Investigation

## Symptoms
- Memory grows 150MB/hour
- Started after deployment v3.1.3
- Affects notification service

## Hypotheses
### H1: Database connections ❌
- Tested: Connection pool stable
- Conclusion: Not the cause

### H2: Redis memory ❌  
- Tested: Memory flat in isolation
- Conclusion: Not the cause

### H3: WebSocket listeners ⚠️
- Found: 47,000 orphaned listeners
- Evidence: Growing by 200/minute
- Next: Fix cleanup logic

Multi-Step Operations

Use checklists for complex procedures:

# Database Migration Progress

## Migration Steps
- [x] Backup production data
- [x] Test on staging  
- [x] Validate rollback plan
- [ ] Execute migration ← Current
- [ ] Verify data integrity
- [ ] Update application config
- [ ] Remove maintenance mode

## Issues Log
- Foreign key error on orders table
- Solution: Temporarily disabled constraint
- Impact: +12 minutes to timeline

Test-Driven Development

Track test progress during TDD:

# TDD: User Authentication

## Test Status
✅ 8 passing
❌ 3 failing  
⏸️ 2 pending

## Current Focus
Working on: Profile image upload
Error: Missing multer middleware
Next: Add multipart/form-data handling

Advanced Techniques

Multi-Agent Coordination

Use scratchpads to coordinate between multiple Claude instances:

# Terminal 1: Implementation
claude
"Use impl.md to track what you build"

# Terminal 2: Testing  
claude
"Read impl.md, then update tests.md with results"

# Terminal 3: Review
claude
"Read both impl.md and tests.md, provide review"

Memory Integration

Store successful patterns for reuse:

# After solving a complex problem
"Store this debugging approach in memory - it found the WebSocket leak quickly"

# In future sessions
"Retrieve debugging patterns for memory leaks"

Team Collaboration

Use GitHub Issues as shared scratchpads:

<!-- Issue: [SCRATCHPAD] Feature Implementation -->

## Team Progress
- [ ] @alice Backend API
- [ ] @bob Frontend components  
- [ ] @charlie Integration tests

## Daily Updates
**Today**: API endpoints complete, starting frontend
**Blockers**: Need design approval for UI

Best Practices

Do's

• ✅ Ask Claude to create scratchpads for complex tasks
• ✅ Create scratchpads early in your workflow
• ✅ Keep scratchpads focused on single topics
• ✅ Use checklists for tracking progress
• ✅ Commit scratchpads with related code changes
• ✅ Store reusable patterns in memory

Don'ts

• ❌ Don't create massive, unfocused scratchpads
• ❌ Don't forget to reference scratchpads after /clear
• ❌ Don't mix unrelated topics in one scratchpad
• ❌ Don't rely solely on context without scratchpads for long tasks

Related

• Memory → - Long-term knowledge persistence
• Context Management → - Optimizing conversation efficiency
• Custom Commands → - Automating workflows