Your agent needs a context snapshot — here's how to build one that survives crashes

Your agent was three hours into a complex refactoring when Claude hit a rate limit. When it came back online, it had forgotten everything — the architecture decisions, the files it had changed, the tests it was planning to write. You're back to square one.

This happens because most agents treat context like RAM — volatile memory that disappears the moment something goes wrong. But your agent's working context is actually your most valuable asset. It's the difference between an agent that can pick up where it left off and one that starts from scratch every time.

Here's the pattern that fixes it: context snapshots.

The Problem: Context Evaporation

When your agent crashes, rate limits, or hits a context window, it loses:

• What it was working on and why
• The decisions it made along the way
• The files it modified (and how they connect)
• The next steps in its plan
• The specific requirements and constraints

Most people solve this by making their initial prompt longer. Wrong approach. You need durable context that persists across sessions.

Context Snapshots: The Pattern

Every 15 minutes (or before any risky operation), your agent writes a snapshot file:

# CONTEXT_SNAPSHOT.md
## Current Task
Refactoring user authentication system to support OAuth2

## Progress So Far
- ✅ Extracted AuthService interface (auth/service.py)
- ✅ Created OAuth2Provider class (auth/oauth2.py) 
- ✅ Updated User model with oauth fields
- 🔄 Currently: Writing integration tests
- ❌ Next: Update login endpoints

## Key Decisions
- Using authlib instead of custom OAuth (faster, more secure)
- Keeping existing username/password as fallback
- Storing OAuth tokens encrypted in user_tokens table

## Files Modified
- auth/models.py (added oauth_provider, oauth_id fields)
- auth/service.py (new file, interface definition)
- auth/oauth2.py (new file, OAuth2Provider class)
- requirements.txt (added authlib==1.2.1)

## Next Steps
1. Finish test_oauth2_integration.py
2. Update auth/views.py login endpoint
3. Add OAuth callback route
4. Update frontend login form

## Context Notes
- Client wants Google + GitHub OAuth only
- Must maintain existing user accounts
- Deploy needs staging test first

This isn't just a status update — it's a complete context restoration kit.

The Implementation

Add this to your agent's system prompt:

Before starting any multi-step task, create/update CONTEXT_SNAPSHOT.md with:
- Current task and why you're doing it
- Progress checklist (✅ done, 🔄 current, ❌ next)
- Key decisions made and reasoning
- Files modified and their relationships
- Specific next steps
- Important constraints or requirements

Update this file every 15 minutes or before risky operations.
If you crash/restart, read this file first to restore context.

The magic happens when your agent restarts. Instead of asking "What should I work on?", it reads the snapshot and immediately knows where it left off.

Why This Works

Context snapshots solve the three biggest agent reliability problems:

1. Crash Recovery: Your agent can pick up mid-task instead of starting over

2. Context Window Management: When you hit limits, the snapshot preserves the essential working memory

3. Handoff Protocol: You can review progress and redirect without losing momentum

Pro tip: Keep snapshots in your project root, not hidden folders. You want to see them in your file tree as a constant reminder of what your agent is thinking.

The Advanced Version

Once you've got basic snapshots working, add these upgrades:

• Timestamped snapshots: Keep the last 3 snapshots so you can roll back if your agent goes off track
• Dependency mapping: Track which files depend on each other
• Decision justification: Force your agent to explain why it made each choice
• Risk assessment: Flag operations that could break things

This pattern transforms your agent from a stateless tool into a persistent worker that actually remembers what it's doing. The difference is night and day — especially on complex, multi-session projects.

Your agent stops being a goldfish and starts being a colleague.