AI Agent Context Budget: What to Summarize in Long Sessions

AI agent context summarization is not “compress the whole chat.” It is leaving the minimum state so the next turn or session can continue the same goal. In long work, tool logs, stack traces, and side explorations bury goals, decisions, and unfinished items. Window size and auto-summary behavior differ by product, so this post does not invent pricing, token counts, or context limits—only a practical workflow.

Three topics: minimum info per turn, where the summary/checklist file lives, and a restart prompt example. Do not rely on “the model will remember.” Default to a readable progress note in the repo.

What minimum information should each turn leave?

One-line answer: Not the full transcript—one-line goal, what was just confirmed, the single next step, blockers, and touched paths. Drop experiment chatter and long tool dumps from the summary.

Ask the agent (via rules) to refresh progress after each meaningful step so a cut session still hands the same checklist to a human or the next agent.

Field	Keep	Skip
Goal	1–2 sentences of done criteria	Full backstory
Done	Verified outcomes (commits, tests, files)	Vague “looked around”
Next	Exactly one next step	Open brainstorm lists
Blocked	One-line repro, error gist, waiting on whom	Full stack dumps
Decisions	Expensive-to-reverse choices (API, branch, scope)	Taste-level chat
Paths	Key file/command names and paths	Secrets or long log bodies

A template that holds up in practice:

# Progress — <ticket-or-topic>

## Goal
- …

## Done
- [x] …
- [ ] … (else move to Next)

## Next (one step)
- …

## Blocked
- … (or "none")

## Decisions
- …

## Paths / commands
- `path/to/file` — why it matters
- `command` — last known good / failing

When to update: After a meaningful file change, after tests pass/fail, or after a direction change—not after every tool call. Noise in the note burns the same budget you are trying to save.

What to discard: Exploration already folded into Done, duplicate failure logs, and “maybe …” hypotheses. If a hypothesis mattered, record adopted/rejected under Decisions in one line.

Where should the summary file live?

One-line answer: Not only in the chat UI—in one findable place in the repo, per unit of work. Teams mirror ticket/branch names; solo work often needs one progress file per worktree.

Searchability beats tool brand. A rule like “for long tasks, read and update docs/progress/ or PROGRESS.md under the ticket folder” lets a new session attach the same path.

Pattern	Use when	Watch-outs
`docs/progress/<slug>.md`	Multi-day / multi-PR themes	Align slug with ticket/keyword
`tickets/ABC-123/PROGRESS.md`	1:1 with the tracker	Collapse to Done when closing
Worktree-root `PROGRESS.md`	Short solo branch experiments	Delete or move under docs before merge
PR checklist only	Small change finished in a day	Promote to a file if the session stretches

Chat-only notes: They vanish or mutate when the session or client summary changes. Handoff via file + optional PR/issue link is safer.

Split checklist vs narrative

Checklist (Done / Next) — execution state; agent updates each step.
Short Decisions — why only; no long retrospectives.
Source and tests — source of truth; progress is a pointer, not a code dump.

Never put secrets, tokens, or personal data in progress either—paths and names only; values stay in env/secret stores.

Sample rule line:

Long tasks: maintain docs/progress/<topic>.md (Goal/Done/Next/Blocked/Decisions/Paths).
Update after each meaningful step. Do not paste secrets or full tool dumps into it.
New chat: read that file first, then continue from Next only.

What does a restart prompt look like?

One-line answer: In a new chat, give the progress path, restate Goal, and run only the Next step. “Continue” alone invites the model to reinvent old hypotheses.

Minimal restart prompt

Continue from the progress note — do not re-explore from scratch.

1) Read `docs/progress/<slug>.md` (and only the Paths listed there if needed).
2) Restate Goal in one sentence; confirm Done items still hold (quick check).
3) Execute ONLY the current Next step.
4) Update the progress note (Done/Next/Blocked) before stopping.
5) If blocked, stop with a one-line Blocked entry — no speculative refactors.

When tightening scope

Same progress file. Scope lock: do not change files outside <dir-or-list>.
Ignore prior chat hypotheses not recorded under Decisions.
Prefer failing test / existing command in Paths over new tooling.

Human handoff block

When a person takes over mid-task, copy Goal / Next / Blocked from progress. Do not forward the entire chat scroll.

Situation	Put in the prompt	Leave out
Same branch, new chat	Progress path + run Next	Yesterday’s full transcript
Resume after review	Keep Decisions; replace Next with review asks	“Start over”
Resume after a blocker	One-line Blocked repro + allowed probe scope	Unlimited exploration
Different agent/tool	Keep the same file shape	Invented UI click-paths per tool

Success criterion: A fresh session, given only progress, picks the same Next, finishes one step without needless re-exploration, and updates the note. How much window remains and what tokens cost are out of scope here—budget by what kinds of information you keep.

What should you remember?

Long-session context budget is state design, not a price sheet. Each turn keeps Goal, Done, Next, Blocked, Decisions, and Paths in a repo progress/checklist file. On restart, make the agent read that file and run only the Next step. Token, window, and pricing numbers vary by product and time—this post does not invent them.

Keep secrets out of progress, rules, and chat; store names and path policy only.
Finish small work with a PR checklist; promote to a progress file when work spans more than a day.
Prefer a short rule that the file is truth over “just remember everything.”