Snapshot Agent Working Memory Before Long Tools

Long tool calls drop context when they time out or return noise. Snapshotting agent working memory before long tools saves the plan, open questions, and last decision. Retries can resume instead of reinventing the thread.

Pin model versions so snapshot format stays stable across runs: pin model versions in agent config like dep locks.

Decide What Counts as Working Memory

Store goals, constraints, file cursors, and the next intended tool. Skip raw tool dumps. Keep the snapshot small enough to reload fast. Diff it in PRs when the schema changes, like prompt diffs: diff prompt changes in PR review like code diffs.

Name fields clearly. Ambiguous keys become silent bugs after a model bump.

Write the Snapshot Just Before Expensive Steps

Triggers: shell over thirty seconds, multi-file edits, network fetches, and MCP calls. Cheap local reads can skip. Logging latency budgets shows which steps deserve a snapshot: log tool-call latency budgets for each agent step.

If a step regularly exceeds budget, snapshot earlier and shrink the tool scope.

Store Snapshots With the Run Id

One folder per run. Include timestamp and step name. Failed overnight fixtures already teach this pattern: record failed agent runs as overnight fixtures. Replays should load the last good snapshot, not the latest noisy one.

Encrypt if snapshots can hold customer text. Rotate access with the same weekly token hold used for tools: rotate agent tool tokens on a weekly calendar hold.

Resume Rules Beat Blind Restarts

On failure, reload snapshot, mark the failed tool as dirty, and ask for a narrower retry. Blind restarts burn tokens and duplicate side effects. Combine with path allowlists so resumes cannot write outside the fence: quarantine new MCP servers behind read-only profiles until write scope is proven.

Human review should see snapshot diffs when a run is promoted to production automation.

Test Resume Paths in CI

Inject a fake timeout after snapshot. Assert the agent continues from the saved plan. Without that test, snapshot code is theater.

Keep fixtures small. One plan, one failed tool, one resume.

Prune Old Snapshots

Retain a week of successful runs and longer for failures under review. Disk fill is a silent outage for agents. Document retention next to the agent config.

When schema changes, migrate or invalidate old snapshots. Mixed formats cause worse errors than a clean restart.

Tell humans where snapshots live in the run UI. Hidden state that only the agent knows becomes undebuggable. A one-click restore to step N is enough for most ops cases.

Avoid snapshotting huge file contents. Store paths and hashes instead so resumes stay fast and private.

When tools mutate external systems, include a compensation hint in the snapshot, such as the ticket id created. Resumes without cleanup hints duplicate side effects. Humans should see that hint in the run timeline.

Load tests should include snapshot write failure. If the store is down, fail closed before the long tool rather than running unprotected.

FAQ

Is this the same as chat history?
No. It is a structured plan state, not the full transcript.

How large should a snapshot be?
Aim under a few kilobytes of structured fields.

Where should we store them?
Beside run logs with the same access controls.

Do we snapshot after every tool?
No. Snapshot before long or side-effecting tools.

What if the snapshot itself is wrong?
Version it and allow a human to pick an earlier step.

Can snapshots hold secrets?
Prefer redaction. If needed, encrypt and rotate keys.