What is durable project memory for coding agents?
Durable project memory is a set of files, typically a spec, a plan, a runbook and a status log, that a long-running coding agent reads and updates so a multi-hour or multi-session build stays on target.
OpenAI's guide "Run long horizon tasks with Codex" names the idea in a heading: the key idea is durable project memory. In the run it describes, GPT-5.3-Codex at extra high reasoning worked for about 25 hours uninterrupted, used about 13M tokens and wrote about 30,000 lines of code, anchored by four markdown files.
The files do what a context window cannot. They hold the target, the plan and the current status in a place every step can re-read, so the agent does not drift into building something impressive but wrong.
OpenAI's four files
Prompt.md: the spec
Goals and non-goals, hard constraints such as performance and platform, deliverables, and a "done when" section. Its job is to freeze the target.
Plan.md: milestones
Milestones small enough to finish in one loop, acceptance criteria with validation commands for each, a stop-and-fix rule, decision notes to avoid going back and forth, and the intended architecture.
Implement.md: the runbook
Treat the plan as the source of truth, run validation after every milestone and fix failures immediately, keep diffs scoped, and keep the documentation file current.
Documentation.md: status
Current milestone status, decisions and reasons, how to run and demo the project, and known issues. It doubles as a shared memory and audit log.
The same idea elsewhere
Anthropic's "Effective harnesses for long-running agents" (2025-11-26) reaches a similar design from a different angle: an initializer agent writes a JSON list of over 200 features, all marked failing, a progress log and a startup script, and each coding session reads them, works one feature, commits to git and updates the log.
Anthropic's memory tool documentation turns this into a general pattern: set up memory files deliberately in a first session, read them at the start of each session, update them at the end, and mark a feature complete only after end-to-end verification.
Where it fails
Status drifts from reality
A status file that says done when the tests fail is worse than no file. Validation commands in the plan, run at every milestone, keep the two in step.
The agent edits the target
If the spec or acceptance criteria can be rewritten mid-run, the agent can make the work easier instead of finishing it. Anthropic's harness allows agents to change only a pass field.
Vague done criteria
Without a concrete "done when", long runs either stop early or keep polishing.
Durable project memory and AGENTS.md
AGENTS.md and similar root files hold standing guidance for any task in a repository: conventions, commands, where docs live. Durable project memory is specific to one piece of work and changes as it progresses. Most long runs use both: the root file for how the repo works, the project files for what this run is building and how far it has got.
How Motiontic's engineers apply it
Motiontic's engineers write the spec and the done criteria with the client before a long agent run starts, keep validation commands in the plan, and review the status log at each milestone. The files stay in the repository, so the record of decisions outlives the run.
Durable project memory files and their jobs
| File | Holds | Changes during the run |
|---|---|---|
| Spec (Prompt.md) | Goals, non-goals, constraints, done when | Rarely; it is the fixed target |
| Plan (Plan.md) | Milestones, acceptance criteria, validation commands | Only through recorded decisions |
| Runbook (Implement.md) | How to work: validate, scope diffs, update docs | Rarely |
| Status (Documentation.md) | Progress, decisions, how to run, known issues | After every milestone |
Common questions
What is durable project memory?
It is a small set of files, usually a spec, plan, runbook and status log, that a coding agent reads and updates throughout a long task so it keeps the same target across hours or sessions.
How long can a coding agent run with durable project memory?
OpenAI's published example ran for about 25 hours uninterrupted and wrote about 30,000 lines of code, guided by four markdown files.
Is durable project memory the same as AGENTS.md?
No. AGENTS.md gives standing guidance for any work in a repository. Durable project memory describes one project's target, plan and progress, and changes as the work moves forward.
Related
Long-running agent
Agents that work for hours or days, and the state that lets them pick up where they stopped.
AGENTS.md
A README for coding agents: the file an agent reads first in a repo.
"Done when" criteria
Completion written down as checks before the agent starts, not judged after.
Initializer agent
The one-off first session that sets up everything later agent sessions rely on.
AI agent development
Agents that do real work for users, with the evals, traces and guardrails to keep them in production.
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.