Conversation Memory

How it works

Every time you send a message, the agent builds on the full history of your conversation - including every tool call it made, every result it received, and every response it gave. If you ask “visit x.com” and then follow up with “what page did you just visit?”, the agent knows the answer because the entire exchange is preserved.

What gets stored

The conversation history is a structured log of messages between you and the agent. It includes:

• Your messages (the text you type in chat or send via webhook).
• Agent responses, including reasoning and any text the agent produced.
• Tool calls - the exact tool name, arguments, and call ID for every action the agent took (e.g. navigating the browser, running a shell command, reading a file).
• Tool results - what each tool returned (page titles, command output, file contents, etc.).

The system prompt is not stored. It's rebuilt fresh each turn from your current agent config, so changes to persona, model, or tools take effect immediately without clearing history.

History limits

To keep context windows manageable and costs predictable, conversation history is capped at 50 messages. When the cap is reached, the oldest messages are trimmed first. The trimmer is tool-pair-aware: it never splits an assistant message from its tool result, so the agent won't see a dangling tool call without its outcome.

Persistence

Conversation history survives agent restarts and container rebuilds through two layers:

• In-memory cache - while the agent is running, history is held in a fast in-memory map for instant access.
• Control plane session files - after each successful turn, session history is uploaded asstate/sessions/<session_id>.json. On startup, the agent restores those files back into memory.

Sessions

Each agent supports multiple independent conversation sessions. Sessions let you run separate threads of work without them interfering with each other.

• Every agent starts with a default dashboard session.
• You can create new sessions from the session picker in the dashboard. Each session has its own independent conversation history.
• Switching between sessions loads the corresponding history - the agent sees a completely different conversation context.
• Deleting a session clears the active in-memory session.
• Webhooks can target a specific session by including a session_id field in the request body. If omitted, it defaults to dashboard.

Long-term memory

In addition to conversation history, agents have a separate long-term memory system backed by the memory_store, memory_recall, and memory_forget tools. The agent uses these to persist facts, preferences, and notes across sessions. Memories are categorized as:

• Core - permanent facts (e.g. “user prefers dark mode”, “project uses React 19”).
• Daily - session-scoped notes that may be cleaned up over time.
• Conversation - context from the current chat thread.

Long-term memory persists independently of conversation history. Even if you clear a session, stored memories remain available to the agent.

Error handling

If an agent turn fails (provider error, tool crash, timeout), the conversation history is not updated. The next turn retries from the last successful state. This prevents corrupted or partial tool results from polluting the context.

Background tasks

Scheduled tasks (heartbeat checks, cron jobs, event handlers) run with fresh, empty history each time. They don't share conversation context with your chat sessions and don't accumulate history across ticks. This keeps background tasks lightweight and prevents monitoring noise from crowding out your conversation context.