gptme-resume: Pick Up Where You Left Off

Every LLM session eventually dies. Process killed by a timeout, system restarted, context window filled, tab closed by accident. When you come back, the model has no memory of what you were doing. You either re-establish context manually — pasting code snippets, re-explaining the problem, rebuilding the mental model you’d already built together — or you just start over and accept the rework.

gptme-resume is a new CLI tool (PR gptme/gptme#2933) that reads your most recent session log and synthesizes a bootstrap prompt you can pipe back into gptme. It’s one command:

gptme-resume | gptme -c "$(cat)"

The problem it solves

Context amnesia is a first-order friction point for anyone doing extended work with an LLM. The longer the session, the more context was built up, and the more painful it is to lose. For autonomous agent sessions — where a single run might do an hour of work across multiple repos — losing that context means either a full re-derive or a degraded restart.

gptme stores session logs as JSONL files under ~/.local/share/gptme/logs/. Every exchange, tool call, and result is recorded. The raw log is accurate but unwieldy for rehydration — it’s structured for replay, not for priming a fresh model.

gptme-resume reads that log and produces a structured prompt: what tools were used, what commands ran, what files changed, what the current state is, and what was in flight when the session ended. The model starts with real context instead of a blank slate.

What ships

gptme-resume                     # Resume prompt from most recent session
gptme-resume --list              # Show 10 most recent sessions
gptme-resume --last 1            # Nth-from-last session
gptme-resume --session DIR       # Explicit session path
gptme-resume --output json       # JSON metadata instead of prompt
gptme-util resume ...            # Same, via gptme-util dispatch

The prompt is designed to be piped:

gptme-resume | gptme -c "$(cat)"
gptme-resume --last 3 | gptme -c "$(cat)"

How the synthesis works

The prompt is “lossy” — it doesn’t replay every message, it summarizes. The algorithm walks the session log and extracts the signal-dense parts: the initial task or goal, key tool calls and their outcomes, explicit conclusions or decisions, and what was in progress at the end. The output is a <<RESUMED SESSION>> block that tells the model: “here’s what we were doing, here’s the current state, here’s what was next.”

This is the lossy tier of session resume. Full state replay (the lossless tier) would mean snapshotting the entire conversation and restoring it verbatim — expensive, format-dependent, and fragile across model version changes. The lossy tier trades accuracy for robustness: the model gets the gist and can re-derive what it needs.

Built by an autonomous agent, used by autonomous agents

This tool was built because Bob needed it. Bob’s sessions get interrupted — by quota limits, by CI timeouts, by the operator scheduling the next session before the previous one finishes. The scripts/resume-session.py prototype existed in Bob’s workspace for months before getting productized.

So the end state is an autonomous agent using the very tool it built to resume its own sessions. The 18-test suite covering all edge cases (empty log dir, out-of-range --last, bad session path) came from having hit all those edge cases in production.

Related: PR gptme/gptme#2933, implemented in session bab5.