Context Save/Restore Commands

Commands

/context-save - Save current session context
/context-restore - Restore context from a previous session

Description

Claude Code sessions are stateless - when you start a new session, all context about what you were working on is lost. These commands solve that by persisting key context to a structured file that can be loaded in the next session.

Behavior

/context-save

1. Gather current session state:
   • What task you're working on
   • Key architectural decisions made
   • Files modified and why
   • Open questions and blockers
   • Next steps planned
2. Write to .claude/context/{timestamp}.md
3. Update .claude/context/latest.md symlink

/context-restore

1. Read .claude/context/latest.md (or specified file)
2. Summarize the saved context
3. Verify referenced files still exist and haven't changed unexpectedly
4. Resume from where the previous session left off

Context File Format

Copy
# Session Context
**Saved**: 2026-03-25 14:30 UTC
**Task**: Implementing rate limiting for API endpoints
**Branch**: feature/rate-limiting

## Current State
Phase: EXECUTE (step 3 of 7)
Last completed: Created Redis rate limiter middleware

## Decisions Made
1. Using sliding window algorithm (not token bucket) because [reason]
2. Rate limits stored in Redis with 60s TTL
3. Per-user limits, not per-IP (authenticated API)

## Files Modified
- `src/middleware/rateLimiter.ts` - NEW: Core rate limiting middleware
- `src/config/limits.ts` - NEW: Rate limit configuration
- `src/routes/api.ts` - Modified: Applied middleware to routes

## Open Questions
- Should we return rate limit headers (X-RateLimit-Remaining)?
- What's the appropriate limit for the /search endpoint?

## Next Steps
1. Add rate limit response headers
2. Create per-endpoint configuration
3. Add bypass for admin users
4. Write integration tests
5. Update API documentation

## Key Code References
- Rate limiter entry point: src/middleware/rateLimiter.ts:42
- Redis connection: src/lib/redis.ts
- Existing auth middleware pattern: src/middleware/auth.ts

Rules

1. Save frequently - especially before complex decisions or long breaks
2. Be specific about decisions and their rationale
3. Include file paths for all relevant code
4. Note open questions so the next session can address them
5. Keep history - don't delete old context files, they serve as a decision log

Directory Structure

.claude/context/
  latest.md           -> symlink to most recent
  2026-03-25-1430.md  -> session context
  2026-03-24-0900.md  -> previous session
  2026-03-23-1600.md  -> older session

Examples

Copy
# Save current context before ending session
/context-save

# Restore the most recent context
/context-restore

# Restore a specific session
/context-restore 2026-03-24-0900

# List all saved contexts
/context-restore --list