Conversational memory

Hosted agents can maintain conversation history across multiple invocations. There are three modes — choose based on whether AgentOS or your code manages the history.

Session mode (AgentOS manages history)

Pass a session_id in your invoke request. AgentOS stores the full conversation history for that session and replays it automatically on each subsequent call.

const { output } = await client.invoke(
  { message: "What's the weather in London?" },
  { sessionId: "user-123-thread-456" },
);

// Later, in the same session:
const { output: followUp } = await client.invoke(
  { message: "What about Paris?" }, // context from the previous message is remembered
  { sessionId: "user-123-thread-456" },
);

# Via HTTP
curl -X POST https://agentos-ai.dev/api/v1/agents/<agentId>/invoke \
  -H "Authorization: Bearer aos_ws_..." \
  -H "Content-Type: application/json" \
  -d '{ "input": { "message": "What is the weather?" }, "session_id": "user-123" }'

Session IDs are arbitrary strings — use whatever makes sense for your application: user-<id>, ticket-<id>, a UUID, etc. Each session ID is an independent conversation thread scoped to the agent.

Sessions are stored per-agent. The same session_id used with different agents creates separate histories.

Stateless mode (your code manages history)

Pass a history array containing the conversation turns. AgentOS uses it as context for the current call but does not persist it — you are responsible for storing and replaying 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

No memory (independent calls)

Omit both session_id and history. Each invocation is treated independently — no prior context is included.

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

Viewing conversation history

Open any run in the dashboard and click the Conversation tab to see the full message history for that invocation.

Choosing a mode

	Session	Stateless	None
Who stores history	AgentOS	Your code	N/A
Cross-call persistence	Automatic	Manual	No
Best for	Chat interfaces, support bots	Apps with their own DB	Single-turn tasks