Every developer using AI coding assistants has hit this wall: you're deep into a complex feature, the session is humming along perfectly, and then — compaction. Or a crash. Or you just need to close your laptop.
When you come back, the AI has no memory of what you built. You spend 20–30 minutes re-explaining context before you can write a single line of code again.
I lost track of how many hours I burned on this before I built a systematic fix. Here's the 5-minute setup that solved it.
The Real Problem
AI coding sessions aren't like regular files. They're not saved anywhere by default. When a Claude Code session compacts (or crashes, or you close it), you lose:
- The exact decisions you made and why
- Dead ends you already explored
- The mental model the AI had built about your codebase
- Architectural choices that would have taken another hour to re-explain
This isn't a bug — it's how stateless AI works. But it doesn't have to be your problem.
The Fix: A Session State System
The approach that works: treat your AI session state like code. Version it. Make it explicit.
Step 1: Create a SESSION.md in your project root (2 minutes)
# Session State
## What We're Building
[One paragraph description of the current feature/task]
## Decisions Made
- [Decision 1] — Reason: [why]
- [Decision 2] — Reason: [why]
## Dead Ends (Don't Revisit)
- Tried approach X, abandoned because Y
## Current Status
[Last thing completed, next thing to do]
## Key Files
- `src/auth/token.ts` — handles JWT rotation (complex, don't touch without context)
- `api/routes.ts` — entry point for all API calls
Step 2: Add a CLAUDE.md that auto-loads it (1 minute)
# Project Context
Always read SESSION.md before starting any task. It contains critical decisions and current state.
After completing any significant task, update SESSION.md with:
- What was done
- Any decisions made and why
- Any approaches that failed
This is the key insight: Claude Code reads CLAUDE.md automatically at session start. So your context loads automatically.
Step 3: End every session with one update (2 minutes)
Before closing Claude Code, type:
Update SESSION.md with what we accomplished today and what the next step is.
That's it. The AI writes the handoff notes itself.
What This Looks Like in Practice
Here's a real SESSION.md after 3 days of work on an auth system:
# Session State — Auth Refactor
## What We're Building
Migrating from session cookies to JWT tokens. Backend is done. Working on frontend token refresh.
## Key Decisions
- Using httpOnly cookies for JWT storage (not localStorage) — security requirement from Sarah
- 15-minute access token, 7-day refresh token — matches existing session policy
- NOT using refresh token rotation yet — too complex, deferred to v2
## Dead Ends
- Tried intercepting with axios — response interceptor caused infinite loop on 401
- Tried fetch wrapper approach — too much to refactor at once
- Current approach: custom useAuth hook handles refresh logic
## Status
Completed: token storage, login flow, logout
Next: handle token expiry during long-running forms (user fills out form, token expires mid-fill)
## Gotchas
- `api/auth/refresh` returns 200 even on failure (legacy bug, don't fix now)
- Test user credentials are in `.env.test`, not `.env`
New session startup time: under 2 minutes instead of 20+.
Why This Works Better Than Other Approaches
vs. just using CLAUDE.md for everything: CLAUDE.md is for permanent project context. SESSION.md is for the current work-in-progress. Mixing them creates noise.
vs. copying chat history: Chat history is verbose and contains all the failed attempts. SESSION.md is curated — only the decisions and state that matter.
vs. tools that sync context automatically: Those tools are great but add complexity. This works with zero dependencies, zero configuration, across any AI coding tool.
The Compaction Problem Specifically
If you're using Claude Code and hitting compaction mid-session (where the context window fills up and older messages get summarized), there's an additional trick:
When you see the compaction warning, immediately run:
Before compaction happens: update SESSION.md with our current decisions and exact next step.
This creates a checkpoint. After compaction, the AI resumes from SESSION.md instead of trying to reconstruct context from the compressed history.
The Bigger Picture
AI coding sessions are genuinely powerful. But they're only as powerful as the context they have. A 5-minute investment in structured session state compounds across every session — each one starts faster, loses less, and builds on previous work instead of starting over.
The developers getting the most out of AI coding tools aren't the ones with the best prompts. They're the ones who've built systems to preserve context across sessions.
If you have a different approach to session state management, I'd love to hear it in the comments — this is a problem the community is still figuring out together.
If You Want This Automated
The manual approach above works, but it requires discipline. I built Mantra to automate it — it creates visual checkpoints of your Claude Code, Cursor, Gemini CLI, and Codex sessions automatically, so you can browse your session history and restore context with one click.
Think of it as time travel for your AI coding sessions. Free download at https://mantra.gonewx.com?utm_source=devto&utm_medium=article&utm_campaign=devto-article-launch (macOS, Windows, Linux).
The Three Things Mantra Actually Does
Since several people asked what's under the hood — here's exactly what Mantra handles:
▶ Replay — Every session is a timeline. Click any message and your codebase jumps to the exact Git state from that moment. The TimberLine scrubber lets you drag through the conversation like rewinding a video. Context is never truly lost.
⚙️ Control — One MCP gateway shared across Claude Code, Cursor, Gemini CLI, and Codex. Add a tool or integration once — every AI assistant you use picks it up automatically. Skills Hub manages your prompt patterns across projects so you're not copy-pasting the same instructions everywhere.
🔒 Secure — Before you share any session or screenshot, a local Rust engine automatically scans for API keys, passwords, and tokens. One-click redaction. Everything stays on your machine.
No cloud. No sign-up. Free. → https://mantra.gonewx.com?utm_source=devto&utm_medium=article&utm_campaign=devto-article-launch
Top comments (0)