Long-Running-Agent-Session-Management

Long-Running Agent Session Management

AI coding agents are stateless — each session begins with zero memory of prior work. For projects spanning hours or days, this is a fundamental failure mode: agents rediscover problems, re-read files, and lose track of completed work. Session management externalizes state into artifacts the agent reads at startup, bridging the gap between sessions.

The Core Problem

• Each new session is a blank slate — no recollection of what was built, broken, or partially completed
• Without intervention, agents either attempt to “one-shot” an entire application (exhausting context mid-feature) or prematurely declare victory after partial progress
• The Context-Rot problem compounds over long projects: growing context degrades response quality before state can even be lost between sessions

The Initializer + Coding Agent Pattern

A two-phase architecture separates first-run setup from ongoing work (see Agent-Harness-Components):

• Initializer agent (runs once): creates init.sh to bootstrap the environment, generates a structured JSON progress file with a comprehensive feature list (200+ items), and makes an initial commit
• Coding agent (all subsequent sessions): follows the session startup protocol, works on one feature at a time, updates the progress file, commits, and leaves code in a clean state

The Session Startup Protocol

Every coding session executes these steps before any implementation:

1. Run init.sh — validate the environment and catch any broken state
2. Read git log — determine what was last worked on
3. Read the progress file — review completed and incomplete features
4. Select the highest-priority incomplete feature and begin

This protocol lets an agent orient completely from artifacts without any prior session’s context.

Progress File Design: JSON Over Markdown

The progress file uses JSON, not Markdown. The reason: agents are less likely to unintentionally overwrite or restructure JSON due to its strict schema. Each feature entry tracks description, validation steps, and pass/fail status. Agents are explicitly instructed that removing or editing tests is unacceptable.

The Clean State Principle

Every session must end with code in a mergeable state:

• No half-finished work committed
• A descriptive git commit per feature serves as the next session’s briefing
• Git history enables git revert as a recovery mechanism
• The previous session’s commit + progress file becomes the next session’s starting context

This mirrors human engineering handoff practices: leaving documentation precise enough that the next engineer (or agent) can orient without asking questions. The discipline must be airtight because agents cannot ask.

Context Isolation and Subagents

For parallel or distributed work, Sub-Agents-Context-Isolation extends this pattern: each subagent receives only the context slice it needs, reducing token waste and preventing cross-task contamination.

Related Concepts

• Agent-Harness-Components
• Context-Rot
• Sub-Agents-Context-Isolation
• Dual-Agent-Design
• Adaptive-Context-Compaction

Sources

• Anthropic (2025). “Effective Harnesses for Long-Running Agents.” Anthropic Engineering Blog.

  • Introduces the initializer + coding agent pattern, JSON progress file design, session startup protocol, and clean-state commit principle
  • Available: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

• Xu, Wujiang; Liang, Zujie; Mei, Kai; Gao, Hang; Tan, Juntao; Zhang, Yongfeng (2025). “A-MEM: Agentic Memory for LLM Agents.” arXiv preprint, arXiv:2502.12110. Accepted to NeurIPS 2025.

  • Proposes dynamic memory organization for LLM agents using interconnected knowledge networks through dynamic indexing; directly parallels the progress-file-as-external-memory pattern
  • Available: https://arxiv.org/abs/2502.12110

• Hu, Yuyang et al. (2025). “Memory in the Age of AI Agents.” arXiv preprint, arXiv:2512.13564.

  • Establishes a three-dimensional framework for agent memory (forms, functions, dynamics); provides conceptual vocabulary for why external progress files function as working memory persisting across stateless sessions
  • Available: https://arxiv.org/abs/2512.13564

• Simple Thread (2021). “Checklist for Handing Off a Software Project.” Simple Thread.

  • Human parallel for the clean-state commit principle: state documentation, test coverage as executable documentation, and environment setup scripts so a new engineer can orient without the previous engineer present
  • Available: https://www.simplethread.com/handing-off-a-software-project/

• ByteBridge (2025). “AI Agents’ Context Management Breakthroughs and Long-Running Task Execution.” Medium / ByteBridge.

  • Documents Claude’s context editing feature (dropping oldest tool outputs near context limits) — the hardware-layer complement to the software-layer progress-file pattern
  • Available: https://bytebridge.medium.com/ai-agents-context-management-breakthroughs-and-long-running-task-execution-d5cee32aeaa4

Note

This content was drafted with assistance from AI tools for research, organization, and initial content generation. All final content has been reviewed, fact-checked, and edited by the author to ensure accuracy and alignment with the author’s intentions and perspective.