Problem
Claude Code and similar AI coding agents operate within a finite context window. When compaction occurs or a session is restarted with /clear, the agent loses track of the current plan, decisions made, architectural context, and progress state. This leads to repeated work, contradictory decisions, and the agent "forgetting" critical constraints mid-task.
Solution
Create persistent markdown files that the agent reads at session start and updates during work.
<!-- PLAN.md -->
# Current Plan
## Phase 1: Auth system (COMPLETE)
- [x] JWT middleware
- [x] Login/signup endpoints
## Phase 2: Dashboard API (IN PROGRESS)
- [x] GET /api/metrics
- [ ] GET /api/activity-feed
- [ ] WebSocket real-time updates
## Phase 3: Frontend
- [ ] Dashboard page
- [ ] Activity feed component
<!-- STATE.md -->
# Session State
## Current Task
Implementing GET /api/activity-feed endpoint
## Key Decisions
- Using cursor-based pagination (not offset) for activity feed
- Activity events stored in `activity_events` table, not denormalized
- Rate limiting at 100 req/min per user
## Blocked On
- Nothing currently
## Last Updated
2026-02-10T14:30:00Z
<!-- NOTES.md -->
# Implementation Notes
## Auth
- Token expiry set to 24h, refresh tokens to 7d
- Password hashing uses argon2id (not bcrypt) per security review
## Database
- Using Drizzle ORM with PostgreSQL
- Migrations in /drizzle/migrations, run with `pnpm db:migrate`
Add instructions to CLAUDE.md to use these files:
## Context Persistence
- Read PLAN.md, STATE.md, and NOTES.md at the start of every session
- Update STATE.md when switching tasks or making key decisions
- Mark completed items in PLAN.md as you finish them
- Add non-obvious implementation details to NOTES.md
Use a skill to reload context after compaction:
---
name: resume
description: Resume work after compaction or session restart
---
Read PLAN.md, STATE.md, and NOTES.md to restore full context.
Summarize current state and ask what to work on next.
Why It Works
Markdown files on disk survive compaction events, session restarts, and even machine reboots. By writing state to files rather than relying on conversation history, the agent has a durable external memory. The CLAUDE.md instruction ensures the agent proactively reads these files, and the structured format (checklists, headers, key-value pairs) makes the context easy to parse without wasting tokens on prose.
Context
- Compaction events (sometimes called "concussion events") are the biggest source of context loss in long Claude Code sessions
- This pattern works with any AI coding agent, not just Claude Code
- Keep files focused and short -- a 50-line STATE.md is better than a 500-line dump
- Consider committing these files to a
.ai/directory if you want them versioned but out of the main source tree - The
/resumeskill pattern lets you restore context in one command after/clear