Progress File

A progress file is a structured document — typically in markdown or plain text — that maintains a running record of project status, completed work, pending tasks, key decisions, and important context. It serves as external memory for AI assistants, allowing them to resume work effectively at the start of each new session.

Why progress files exist

AI assistants do not retain memory between sessions. When you start a new conversation with Claude, ChatGPT, or any other AI, it has no recollection of previous conversations. For ongoing projects, this means you would need to re-explain the entire project context every time — unless you maintain a progress file that the AI reads at the start of each session.

What a progress file contains

A well-structured progress file typically includes:

• Project overview: A brief description of what the project is and its goals.
• Current status: What has been completed, what is in progress, and what is blocked.
• Key decisions: Important choices that have been made and why, so the AI does not revisit settled questions.
• Architecture notes: Technical or structural decisions that affect how work should be done.
• Next steps: Prioritised list of what to work on next.
• Open questions: Issues that need resolution before certain work can proceed.
• File map: Key files and their purposes, so the AI knows where to find things.

How to use progress files effectively

• Update at the end of each session: Before ending a work session, ask the AI to update the progress file with what was accomplished and what remains.
• Keep it concise: A progress file that is too long wastes context window space. Summarise completed work and remove outdated details regularly.
• Include the "why": Record not just what was decided but why. This prevents the AI from revisiting decisions without understanding the reasoning behind them.
• Version control: If the project is in a code repository, commit the progress file alongside the code so it stays synchronised.

Progress files vs other memory approaches

Progress files are simpler and more reliable than vector databases or AI memory features for project-based work. They are human-readable, easy to edit, and work with any AI tool. The trade-off is that they require manual maintenance, but this is also an advantage — you control exactly what the AI knows.

Common formats

The most popular format is a markdown file (often named PROGRESS.md, STATUS.md, or similar) at the root of a project directory. Some teams use CLAUDE.md or similar tool-specific files that the AI automatically reads.