85 agentic tools audited for security incidents · Talk to the lab →
MotionticBook a call
Glossary

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

Durable project memory files and their jobs
FileHoldsChanges during the run
Spec (Prompt.md)Goals, non-goals, constraints, done whenRarely; it is the fixed target
Plan (Plan.md)Milestones, acceptance criteria, validation commandsOnly through recorded decisions
Runbook (Implement.md)How to work: validate, scope diffs, update docsRarely
Status (Documentation.md)Progress, decisions, how to run, known issuesAfter 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.

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.