Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Progress Log

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Agent – progress logs support multi-session agent workflows.

Context

At the agentic level, a progress log is a durable record of what’s been attempted, what’s succeeded, and what’s failed during an agentic workflow. Unlike conversation history, which lives in the context window and disappears when the window fills or the session ends, a progress log persists in a file that both humans and agents can read across sessions.

Progress logs address a gap between the transient nature of agent conversations and the persistent nature of software projects. Work happens over days and weeks. Agents forget between sessions. Humans forget between days. The progress log is the shared external memory that keeps both on track.

Problem

How do you maintain continuity across multiple agent sessions when the model has no memory of previous conversations and the human’s memory is imperfect?

A developer works with an agent on a migration project over three weeks. Each session starts from scratch: the agent doesn’t know what was accomplished yesterday, what approaches were tried and failed, or what decisions were made. The developer remembers the broad strokes but not the details. Without a persistent record, work is duplicated, dead-end approaches are retried, and decisions are relitigated.

Forces

  • Model statelessness: each session starts fresh.
  • Human memory decay: details from last week’s session are fuzzy by Monday.
  • Multi-session projects are common for non-trivial work.
  • Team coordination: multiple people may work with agents on the same project, and they need to know what others have done.
  • Overhead: maintaining a log takes time that could be spent on the work itself.

Solution

Maintain a progress log in a plain text or markdown file in the project repository. Update it at natural checkpoints: the end of each session, after completing a significant subtask, or after discovering something important.

A useful progress log entry includes:

Date and scope. When the work happened and what area it covered.

What was accomplished. Specific files changed, features implemented, bugs fixed.

What was tried and failed. Approaches that didn’t work and why. This is the most useful part; it prevents future sessions from wasting time on dead ends.

Decisions made. Architectural choices, tradeoff resolutions, or convention changes, with brief rationale.

What remains. Next steps, open questions, known issues.

The log doesn’t need to be exhaustive. It should capture enough that a future agent session (loaded with the log in its context) can pick up where the last session left off without retracing steps.

Hooks can automate log updates: a session-end hook can prompt the agent to append a summary to the log file before the conversation closes.

Tip

Include your progress log in the agent’s context at the start of each session. A brief instruction like “Read PROGRESS.md before starting” gives the agent awareness of past work, failed approaches, and outstanding decisions, dramatically reducing wasted effort.

How It Plays Out

A developer is migrating a codebase from one ORM to another. The project takes two weeks. At the end of each session, she asks the agent to append a summary to PROGRESS.md. The log grows to about thirty entries. When she starts each new session, the agent reads the log and immediately knows: the User model and Order model have been migrated, the Payment model migration was attempted but reverted because of a foreign key issue, and the next step is to resolve that issue before continuing.

A team of three developers works with agents on different parts of the same project. The shared progress log lets each developer see what the others’ agents have accomplished, what approaches failed, and what decisions were made. The log replaces a daily standup for the agentic portion of the work.

Example Prompt

“Before starting, read PROGRESS.md to see what was done in previous sessions. When you finish today’s work, append a summary of what you accomplished and what the next step should be.”

Consequences

Progress logs provide continuity that neither model memory nor human memory can reliably offer. They prevent wasted effort, preserve institutional knowledge, and serve as an audit trail. They also improve agent performance by giving each session a running start.

The cost is the discipline of maintaining the log. If updates are skipped, the log becomes stale and misleading, worse than no log at all. The remedy is automation: hooks that prompt for log updates at the end of sessions, and a team norm that treats log maintenance as part of the work, not an afterthought.

  • Depends on: Agent — progress logs support multi-session agent workflows.
  • Uses: Memory — memory captures learnings; progress logs capture actions and outcomes.
  • Uses: Hook — hooks can automate log updates.
  • Uses: Compaction — compaction summaries can feed the progress log.
  • Enables: Thread-per-Task — the progress log provides the context bridge between threads.
  • Uses: Context Engineering — the log is context loaded at the start of each session.