Agentic Workflows: State Files for Memory Between Runs

Every new agent session starts with amnesia. It does not remember what we decided yesterday. It does not know which task is next. Giving the agent context again from scratch is slow and error-prone. State files fix this.

The Pattern

I keep a STATE.md file at the project root. The agent reads it at session start. It contains three things: the current position (phase, task, status), the decisions already made, and the blockers or concerns in play.

## Current Position
- Phase: 3 (authentication)
- Task: 3.2 (JWT refresh rotation)
- Status: in progress
 
## Decisions
- Using jose library (not pyjwt)
- 15-minute access, 7-day refresh
- Refresh rotates on use
 
## Concerns
- Cookie storage vs localStorage: pending security review

Session one writes this file. Session two reads it. Session twenty still reads the same file, updated. The agent picks up mid-thought without re-explanation.

Why Markdown Not JSON

I use markdown because humans read it too. When I check on the project state between agent sessions, I read the same file the agent does. There is only one source of truth. JSON would save twenty characters and cost the human readability.

The Update Discipline

The agent updates STATE.md at the end of every session as part of the task. This is a prompt-level habit: 'Before ending, update STATE.md with what changed.' After two weeks it is automatic. After two months the file is richer than any changelog I would have written myself.

What Not To Put In It

Secrets. API keys. Anything that would leak. The state file is committed to git. If it cannot be public, it does not go here. Use environment variables and the normal secrets story for those.

State files are the simplest memory mechanism that works. No database, no embedding store, no vector search. A text file the agent reads and writes. Boring and effective.