Conversational memory

Hosted agents can carry a conversation across several invocations. Choose who keeps the history: AgentOS (session mode) or your code (stateless mode). Without either, every call starts fresh.

This is conversation memory only. AgentOS has no separate long-term memory store; for data an agent should keep between conversations, have it write a file with write_resource or a record with records_create (see Knowledge files).

Session mode (AgentOS keeps the history)

On the first call, set start_session. The response includes a session_id issued by AgentOS. Pass that session_id on each later call, and AgentOS replays the conversation to the agent automatically.

const first = await client.invoke(
  { message: "What's the weather in London?" },
  { startSession: true },
);

// Later, in the same conversation:
const followUp = await client.invoke(
  { message: "What about Paris?" }, // the agent remembers the previous turn
  { sessionId: first.sessionId! },
);

Store the session_id alongside your own record (a chat thread, a ticket) so you can continue the conversation later.

• Session IDs come from AgentOS. You can't choose your own. An unknown or expired session_id returns 404; start a new session instead.
• A session belongs to one agent. Using a session_id with a different agent returns 400.
• Only recent messages are replayed. The agent sees the latest 30 messages; older ones drop out of its context. Each message is capped at 20,000 characters.
• Sessions expire. A conversation is deleted after 24 hours with no new message.
• external_user_id (SDK: externalUserId / external_user_id) is optional. Set it when starting a session to record your own end-user id on the conversation. It is only accepted together with start_session or session_id.

The user side of each turn is the input object you sent; the assistant side is the agent's output.

Stateless mode (your code keeps the history)

Pass a history array with the earlier turns. AgentOS uses it as context for this call and stores nothing, so you are responsible for saving and replaying the history.

const { output } = await client.invoke(
  { message: "What about Paris?" },
  {
    history: [
      { role: "user", content: "What's the weather in London?" },
      { role: "assistant", content: "It's 12°C and cloudy in London." },
    ],
  },
);

Each history entry has:

• role: "user" or "assistant"
• content: the message text, up to 20,000 characters

You can send up to 50 turns.

No memory (independent calls)

Omit start_session, session_id and history. Each invocation is independent, with no prior context.

const { output } = await client.invoke({ query: "Summarise this report" });

Managing conversations

Use the control plane (conversations.list, conversations.get, conversations.delete) or the matching MCP tools to list conversations, read a conversation's messages, or delete one.

To clear everything an agent has recorded, use Reset history in the agent's Configuration → Settings tab. It deletes the agent's runs, events, findings, reports and conversations, and cannot be undone.

Choosing a mode