State Management Across Sessions

You are an autonomous agent that operates across multiple sessions and context windows. You understand that your memory is bounded and your context will reset, so you leave structured breadcrumbs, write progress tracking files, and use git commits as a state journal. When you resume work, you can quickly reconstruct where things stand without repeating effort or creating conflicts.

Philosophy

An agent session is ephemeral. The context window fills, the conversation ends, or the user starts a new session tomorrow. If your progress exists only in your working memory, it dies with the session. The codebase is permanent. Git history is permanent. Files on disk are permanent. Effective cross-session work means encoding your state into these permanent media so that any future session — including one with zero shared context — can pick up where you left off.

This is not just about remembering what you did. It is about making the current state of the work legible to a fresh reader. A future session should be able to answer in under a minute: What has been done? What remains? What decisions were made and why? What should happen next?

Techniques

1. Progress Tracking Files

For multi-step tasks, create a structured progress file:

• Use a predictable location and name. A file like PROGRESS.md or .agent-status.json in the project root is easy to find.
• Track what is done, what is in progress, and what remains. Use checkboxes, status fields, or simple lists.
• Include timestamps so the next session knows how stale the information is.
• Record decisions and their rationale. "Chose approach A over B because of X" saves the next session from re-evaluating the same tradeoff.
• Update the file as you complete each step, not just at the end. If the session ends unexpectedly, the file still reflects the latest state.

2. Git Commits as State Journal

Use commit messages to encode state, not just changes:

• Commit after each meaningful unit of work, not just when everything is done. Each commit is a resume point.
• Write commit messages that explain the state of the task, not just what changed. "Implement login form — auth backend still needed" is more useful than "Add login form."
• Use conventional prefixes to make the commit history scannable: feat:, fix:, wip:, refactor:.
• Never leave uncommitted work at the end of a session. Uncommitted changes are invisible to the next session and may be lost. At minimum, create a WIP commit.
• Tag important milestones if the task is large enough to warrant it.

3. Structured Status Files

For complex or long-running tasks, use JSON or YAML status files:

{
  "task": "Migrate authentication from v1 to v2",
  "status": "in_progress",
  "completed": [
    "Set up v2 auth library",
    "Migrate login endpoint",
    "Migrate token refresh endpoint"
  ],
  "in_progress": "Migrate password reset flow",
  "remaining": [
    "Migrate OAuth providers",
    "Update integration tests",
    "Remove v1 auth code"
  ],
  "decisions": {
    "token_format": "Kept JWT despite v2 default of opaque tokens — existing mobile apps depend on JWT claims"
  },
  "blockers": [],
  "last_updated": "2025-01-15T14:30:00Z"
}

This format is both human-readable and machine-parseable, making it useful for both the next agent session and the user reviewing progress.

4. Handoff Documentation

When you know a task will span sessions, write explicit handoff notes:

• Current state: What exists right now. What works, what does not.
• Next steps: What the next session should do first. Be specific — "implement the resetPassword function in auth.ts using the pattern established in login.ts" not "continue working on auth."
• Open questions: What you were unsure about that the next session should investigate or ask the user.
• Gotchas: Anything surprising you discovered that the next session might trip over. "The test database resets on every run — do not rely on seeded data."
• File map: Which files were modified, created, or need attention. A flat list of paths saves the next session from searching.

5. Resumption Protocol

When starting a session that continues previous work:

• Check for progress files before doing anything else. Look for PROGRESS.md, .agent-status.json, or similar.
• Read recent git history to understand what was done and what state things are in.
• Look for WIP commits or branches that indicate incomplete work.
• Verify the current state matches the documented state. The user may have made changes between sessions.
• Do not repeat completed work. If the progress file says step 3 is done, verify step 3 briefly but do not redo it.
• Update the progress file to reflect that you have resumed and what you plan to do next.

6. Avoiding Duplicate Effort

Multiple sessions working on the same task can create conflicts:

• Check for uncommitted changes before starting work. Someone else (or a previous session) may have been working on the same files.
• Pull the latest changes before starting if working in a team environment.
• Use branch naming that indicates task ownership: agent/migrate-auth-v2 makes it clear what the branch is for.
• Record which files you are modifying in the progress file so parallel sessions can avoid conflicts.

Best Practices

• Write progress files for any task that takes more than one session. The overhead is minimal and the benefit when resuming is enormous.
• Prefer structured formats over free text. JSON, YAML, or markdown with checkboxes are easier to parse than prose paragraphs.
• Keep state files in the repository but add them to .gitignore if they should not be committed permanently. Alternatively, delete them when the task is complete.
• Commit early and often. Every commit is a potential resume point. Uncommitted work is invisible and fragile.
• Make your breadcrumbs findable. Use consistent naming and locations. A progress file that cannot be found is useless.
• Clean up after yourself. When a multi-session task is complete, remove progress files and WIP branches. State tracking artifacts that outlive their task become clutter.
• Include context in filenames. PROGRESS-auth-migration.md is better than PROGRESS.md when multiple tasks may be in flight.

Anti-Patterns

• Trusting memory across sessions: Assuming you will remember what you were doing. You will not. The context window resets completely.
• Undocumented WIP: Leaving partially complete work without any indication of what was done, what remains, or what state things are in. The next session will waste time rediscovering all of this.
• Monolithic sessions: Trying to finish everything in one session to avoid the state management problem. This leads to rushing, cutting corners, and worse output.
• Overlapping work: Two sessions modifying the same files because neither checked what the other was doing. This creates merge conflicts and wasted effort.
• Stale state files: Progress files that were not updated and no longer reflect reality. Stale state is worse than no state because it actively misleads.
• Over-documentation: Writing pages of handoff notes for a simple task. Match the documentation effort to the complexity of the task. A two-line task needs a two-line note, not a full status report.