The context window problem for long-running agents isn't what most people think. It's not just that the window fills up — it's that agents lose track of decisions they made earlier, repeat work they've already done, and become inconsistent with their own prior outputs. We've spent significant time on memory patterns that address this practically.
The working memory document
The most effective pattern we've found is the 'working memory document' — a structured markdown file that the agent maintains and updates throughout its session. It contains: decisions made and their rationale, files examined and their current state, tasks completed and pending, and open questions. The agent reads this at the start of each new context window.
# Working Memory — Refactor: Auth Middleware
## Decisions Made
- Chose JWT over session cookies (stateless requirement confirmed with Marco)
- Using RS256 (not HS256) — keys already provisioned in secrets
- Keeping legacy /api/v1/session endpoint for 90-day deprecation window
## Files Examined
- src/middleware/auth.ts — main target, currently 340 lines
- src/lib/jwt.ts — existing JWT utilities (use these, don't duplicate)
- tests/middleware/auth.test.ts — needs updating after changes
## Completed
- [x] Extracted token parsing into jwt.ts utilities
- [x] Added RS256 verification
## Pending
- [ ] Update session renewal logic
- [ ] Migrate tests
- [ ] Update OpenAPI specPersistence vs. summarization
We initially tried summarizing context at window boundaries. This loses too much. The working memory document approach preserves the structural decisions and state without trying to compress the reasoning. An agent can reconstruct 'why' from the document, even if it doesn't remember the conversation that produced the decision.
- Working memory documents are committed to the branch alongside code changes
- The agent updates the document at natural checkpoints (before/after each major step)
- Reviewers can read the document to understand why the agent made specific choices
- If a session is interrupted and resumed, the new session starts by reading the document