Managing Message History

Long conversations exceed context windows. Use @before_model middleware to trim or rebuild history, RemoveMessage to delete specific messages, and SummarizationMiddleware to compress old turns into a summary.

Quick Reference

→@before_model decorator — runs before every model call; return updated messages to trim
→RemoveMessage(id=REMOVE_ALL_MESSAGES) — wipes the slate; pass replacement messages alongside
→RemoveMessage(id=m.id) — deletes a specific message by ID
→SummarizationMiddleware(model, trigger=('tokens', N), keep=('messages', N)) — auto summarizes
→@after_model — runs after model response; use to filter or validate before state is written

Why You Need to Manage History

Every message costs tokens. As a conversation grows, the full history eventually hits the model's context window — and the call fails or gets silently truncated. Beyond token limits, most models perform worse over long contexts: they get distracted by stale content, take longer, and cost more. Three strategies exist: trim (drop old messages), delete (remove specific messages), and summarize (compress old turns).

Trimming with @before_model

The recommended approach for agents built with create_agent is a @before_model middleware function. It runs before every model call, receives the current state, and can return a modified messages list. Use RemoveMessage(id=REMOVE_ALL_MESSAGES) to replace the full history with a smaller, reconstructed list.

Deleting Specific Messages

RemoveMessage lets you delete individual messages by their ID — useful for removing a specific response, clearing tool call artifacts, or pruning the oldest N messages.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.