Persistence & History
Relevant source files
The following files were used as context for generating this wiki page:
Persistence and History in the browser-use framework encompass the mechanisms for maintaining state across browser sessions and recording the step-by-step execution of AI agents. This includes the storage of browser artifacts like cookies and traces, as well as the structured logging of agent actions, model outputs, and environment states for debugging, validation, and replaying tasks.
The system is designed to allow agents to "remember" past interactions through a short-term message history and a long-term execution history. Long-term history can be exported to JSON files or visualized as GIFs, while session persistence is handled via cookie files and Playwright tracing.
Sources: browser_use/agent/service.py, browser_use/browser/context.py:35-100
Session Persistence
The framework provides native support for persisting browser sessions using cookies. This allows agents to maintain authenticated states (e.g., being logged into Twitter or LinkedIn) without re-authenticating in every run.
Cookie Management
The BrowserContextConfig class includes a cookies_file parameter. When provided, the BrowserContext loads existing cookies during initialization and automatically saves updated cookies when the context is closed or when the browser state is retrieved.
The following table describes the configuration options related to session persistence:
| Option | Type | Default | Description |
|---|---|---|---|
cookies_file | str | None | None | Path to the JSON file for cookie persistence. |
trace_path | str | None | None | Directory where Playwright trace ZIP files are saved. |
save_downloads_path | str | None | None | Path where files downloaded by the agent are stored. |
Sources: browser_use/browser/context.py:80-110, browser_use/browser/context.py:315-325
Agent Execution History
The agent maintains a comprehensive record of its execution via the AgentHistoryList. This list stores AgentHistory objects, each representing a single "step" in the task.
History Data Structure
Each history item captures the relationship between the model's intent and the resulting environment change.
AgentOutput*: Contains the model's reasoning (AgentBrain), including page summaries, evaluations, and the chosen actions.
- ActionResult: Captures the outcome of the action, including extracted content or error messages.
- BrowserStateHistory: Records the URL, page title, and a base64 screenshot of the browser at that specific step.
Sources: browser_use/agent/views.py:45-120, browser_use/agent/service.py:305-325
Conversation & Trace Logging
For debugging and fine-tuning, the framework supports saving the literal conversation between the agent and the LLM, as well as high-level visual traces.
Conversation Backups
If save_conversation_path is configured in the Agent, the system writes the raw prompt and model response for every step into individual text files. This is useful for auditing the specific context provided to the model at any given point.
Sources: browser_use/agent/service.py:460-480
Visual History (GIF Generation)
The Agent can compile its execution history into an animated GIF. This process overlays the agent's current goal and step number onto the screenshots captured during the run.
Sources: browser_use/agent/service.py:720-800
Message Memory & Token Management
Short-term memory is managed by the MessageManager. It tracks the sequence of messages sent to the LLM and ensures they stay within the model's context window.
Token Trimming
When the message history exceeds the max_input_tokens limit, the MessageManager implements a trimming logic. It prioritizes keeping the system prompt and task instructions while removing or compressing older state messages.
| Feature | Logic |
|---|---|
| Vision Trimming | Removes high-resolution images from older messages to save tokens. |
| Proportional Cut | Truncates text content of the oldest messages by a calculated percentage. |
| Sensitive Data | Replaces actual secrets with <secret>key</secret> placeholders before storage. |
Sources: browser_use/agent/message_manager/service.py:190-250, browser_use/agent/message_manager/service.py:270-300
Replaying History
The Agent class provides a rerun_history method that allows for re-executing a previously saved AgentHistoryList.
Index Matching Logic
Because DOM indices (highlight indices) can change between runs even on the same website, the replayer does not rely on raw IDs. Instead, it uses the HistoryTreeProcessor to find the historical element in the current page's DOM tree based on its structural properties (XPath, attributes) and updates the action's index before execution.
Sources: browser_use/agent/service.py:640-700
Summary
Persistence and History in browser-use provide a robust framework for stateful web automation. By combining Playwright's session management with custom structured history tracking, the project enables sophisticated debugging, auditability, and the ability to resume or replay complex web tasks across different sessions.