A long-running AI agent should not treat its conversation history as its source of truth. Context can be truncated, summaries can omit details and a model can misread an earlier decision. The system needs explicit, inspectable state outside the conversation.

This is an engineering pattern, not a claim that an agent can be made infallible. External memory reduces ambiguity only when it is kept current and checked against the real system.

Separate facts, decisions and working notes

Do not put everything into one growing scratchpad. Keep three distinct records:

  • Task state: the objective, current milestone, status, outstanding work and evidence required to finish.
  • Decision log: consequential choices, alternatives considered and reasons for the selected approach.
  • Working notes: temporary findings that may be discarded when the task ends.

A compact task record might look like this:

task: "Add export support"
status: "in_progress"
current_step: "Implement CSV serializer"
constraints:
  - "Keep existing JSON export unchanged"
  - "Do not add runtime dependencies"
verification:
  - "CSV contract tests pass"
  - "Exported file opens in spreadsheet software"
last_verified_commit: "abc1234"

The commit identifier is important: it ties the recorded state to a real repository snapshot.

Use a read–act–verify loop

For each consequential operation:

  1. Read the current task state and relevant project files.
  2. Check that assumptions still match the repository or service.
  3. Make one bounded change.
  4. Run the relevant test or inspect the external result.
  5. Update the task state with what actually happened.
  6. Record a decision only if it will matter later.

Do not record an intended action as completed. "Tests should pass" is a plan; a recorded successful test run is evidence.

Make checkpoints recoverable

A checkpoint should let another session continue without reconstructing the whole conversation. Include:

  • the objective and scope;
  • the current branch and commit;
  • changed files;
  • commands already run and their outcomes;
  • known failures and unresolved risks;
  • the next safe action.

Keep credentials, personal data and sensitive production values out of these records. Store references to secure systems rather than copying secrets into agent memory.

Make memory bounded and auditable

More stored context is not automatically better. Old notes can conflict with current code. Give records dates, ownership and expiry conditions. Prefer current source files, tests and configuration over remembered descriptions.

Useful controls include:

  • version-controlled project instructions;
  • append-only decision records for important choices;
  • explicit status fields;
  • periodic pruning of obsolete notes;
  • checks that compare recorded state with repository state.

Avoid writing a memory update after every trivial tool call. Update at meaningful boundaries: a decision, a verified milestone, a failure or a handoff.

Design for interruption

An agent may stop unexpectedly. The workflow should remain safe if it resumes later or a different person takes over.

Use idempotent operations where possible. Before destructive changes, re-read the target and verify the expected version. For deployments, record the exact commit and deployment identifier. For external actions, require the appropriate human approval.

Measure the outcome

Evaluate the workflow using recovery time after interruption, stale-state errors, repeated work, failed operations and human correction rate. Do not use vague claims such as "zero-shot reliability" without a defined test and measured result.

External memory is useful when it makes state easier to inspect and recover. It is not a substitute for source control, tests, permissions or human judgment.