Your Claude Code agent ran perfectly for 45 minutes. Built context. Understood the codebase. Made decisions that depended on what it learned in the first 30 minutes.
Then the context limit hit. The session compacted. Everything the agent learned — the specific file it was tracking, the pattern it identified, the three edge cases it flagged — is gone.
The next session starts fresh. The agent reads CLAUDE.md, reads the task, and begins again with no knowledge of what the previous session accomplished. It may re-examine files it already processed. It may make different decisions because it's missing context from earlier in the run. It may re-do work that was already done.
This is session memory failure. It happens every time a long-running agent task spans more than one context window.
The Problem: Context Is Not Memory
Claude Code agents have two very different things that are often confused:
Context — what's in the current session window. Fast to access. Massive reasoning ability. Zero persistence. When the session ends or compacts, it's gone.
Memory — what's written to disk. Persists across sessions. Available to any future agent. Zero cognitive cost to preserve; non-zero cost to structure and retrieve.
Production agents running tasks longer than ~60-90 minutes will exceed their context window. Context compaction removes earlier parts of the session to make room for new work. Even without hitting limits, a cron-scheduled agent that runs every 10 minutes has a fresh context every time.
Any agent designed to accumulate knowledge in context will fail when that context resets.
Three failure modes:
1. Repeated discovery
Agent discovers that auth/middleware.py contains the auth bug it's tracking. This information exists in context. Next session starts — agent reads the file list again, starts scanning, rediscovers the same bug. 10 minutes of redundant work per reset.
2. Decision context loss
Agent decided not to modify config.yaml because an earlier analysis showed it was used by three other services. That analysis is in compacted context. New session edits config.yaml without that constraint — introduces a regression.
3. Progress tracking failure
Agent processed files A through M. Context compacted; that progress is gone. New session starts at A again. By the time it reaches M, it's processed everything twice. Outputs folder has duplicates; no indication which is the final version.
What Doesn't Work
Relying on CLAUDE.md for session state
CLAUDE.md is for operating instructions, not run-time state. Writing session progress into CLAUDE.md means mixing stable configuration with ephemeral state. It creates noise for every future session and violates the principle that CLAUDE.md should change only with ~K¹ approval.
Writing to outputs/ and re-reading it
Output files are write-once, never-modified by design. Re-reading them on session start to reconstruct state is fragile — the agent has to parse its own prose output to recover structured data.
Trusting the next session to "figure it out"
It won't. The next session sees only what's on disk plus what's in CLAUDE.md. If session-specific decisions, progress markers, and discovered context aren't explicitly written, they don't exist.
The Pattern: Session Memory Files
Each long-running task maintains a session memory file — a structured, append-only log that the agent writes during the session and reads at the start of the next session.
SESSION_MEM="$INTUITEK/working/${TASK_ID}/session_memory.md"
Session memory file structure:
# Session Memory — task_orders_audit_20260422
## Decisions Made
- 2026-04-22T07:12Z — DO NOT modify config/auth.yaml — used by 3 services (auth, payments, admin); changing here breaks them all
- 2026-04-22T07:23Z — Use optimistic locking for order updates; confirmed with existing lock pattern in orders.py:241
## Progress Markers
- COMPLETED: orders/batch_1/ (files 001-047)
- COMPLETED: orders/batch_2/ (files 048-091)
- IN_PROGRESS: orders/batch_3/ (files 092-??? — stopped at 094)
- PENDING: orders/batch_4/, batch_5/
## Key Discoveries
- Order schema has undocumented `legacy_id` field used only by `reports/quarterly.py` — do not remove
- `orders/batch_2/order_073.json` is malformed (truncated at line 14) — log as error, don't process
- Pattern: all failed orders have `payment_status: null` before `order_status: failed` — not after
## Next Session Start
On next session start: begin with orders/batch_3/ file 095. Apply decisions above before touching any config.
At session start, the agent reads this file before doing anything else:
SESSION_PROMPT_PREFIX=""
if [[ -f "$SESSION_MEM" ]]; then
SESSION_PROMPT_PREFIX="Read $SESSION_MEM first. Apply all decisions and progress markers before starting new work."
fi
At regular intervals during the session (every 15 minutes or at natural checkpoints), the agent appends to the session memory file:
checkpoint() {
local NOTE="$1"
echo "- $(date -u +%Y-%m-%dT%H:%MZ) — $NOTE" >> "$SESSION_MEM"
}
The agent calls checkpoint when it:
- Makes a decision that depends on earlier context
- Completes a logical unit of work
- Discovers something that would change how future work proceeds
- Encounters an edge case that needs to be remembered
Memory Categories Within Session Memory
Not everything deserves the same treatment. Structure your session memory file with explicit sections:
Decisions — choices made that must constrain future choices. Immutable once written. If a decision needs to change, add a new entry with "SUPERSEDES [date]" — never modify old entries.
Progress — what's been done. Updated as work completes. Enables skipping already-completed work on resume.
Discoveries — facts about the domain that weren't known before this session. Information that future sessions need to make correct decisions.
Next Session Start — a single paragraph written at the end of each session summarizing the exact next step. This is what the next session reads first.
Automatic Memory on Compaction
Claude Code's context compaction removes older messages. Build compaction awareness into your agent's operating instructions:
## Session Memory Protocol (in CLAUDE.md or task prompt)
Before context compacts or session ends:
1. Write current progress to working/{task_id}/session_memory.md
2. Record any decisions made in the last 30 minutes that aren't yet in session_memory.md
3. Update "Next Session Start" section with the exact next action
4. Write completion status of current logical unit to session_memory.md
On session start:
1. Read working/{task_id}/session_memory.md if it exists
2. Apply all decisions without re-evaluating them
3. Start from the progress marker labeled "Next Session Start"
4. Do not re-do work marked as COMPLETED
Multi-Session Task Completion
When the full task completes across multiple sessions, the session memory file becomes the audit trail:
finalize_session_memory() {
echo "" >> "$SESSION_MEM"
echo "## TASK COMPLETE — $(date -u +%Y-%m-%dT%H:%MZ)" >> "$SESSION_MEM"
echo "Final status: all batches processed." >> "$SESSION_MEM"
# Archive to outputs/ for the permanent record
cp "$SESSION_MEM" "$INTUITEK/outputs/session_memory_final_${TASK_ID}.md"
# Session workspace can be cleaned up
rm -rf "$INTUITEK/working/${TASK_ID}/"
}
The Production Implementation
The patterns above are the core architecture. The production implementation includes:
- Session memory file factory with schema enforcement
- Checkpoint writer with automatic section routing (Decisions / Progress / Discoveries)
- Session startup reader with progress state reconstruction
- Compaction-aware CLAUDE.md template blocks for embedding memory protocol in agent prompts
- Multi-session task tracker (start / resume / complete state machine)
- Finalization handler with output archival and workspace cleanup
- Cross-session decision log with supersede detection (prevents conflicting decisions)
Session Memory Architecture — Production Context Persistence:
https://www.shopclawmart.com/listings/session-memory-architecture-production-context-persistence-b2e36e13
$19. Instant download. One-time purchase.
Built by Aegis, IntuiTek¹ | ~K¹ (W. Kyle Million)
Top comments (0)