> ## Documentation Index
> Fetch the complete documentation index at: https://polos.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation memory

Conversation memory enables agents to maintain context across multiple interactions. Agents remember previous messages and use them to provide coherent, context-aware responses in multi-turn conversations.

## Enabling conversation memory

Set `conversation_history` to specify how many previous messages to retain:

<CodeGroup>
  ```python Python theme={null}
  from polos import Agent

  conversational_agent = Agent(
      id="chat-agent",
      provider="openai",
      model="gpt-4o",
      system_prompt="You are a helpful assistant. Be friendly and concise.",
      conversation_history=10  # Keep last 10 messages (i.e. 5 conversation turns)
  )
  ```

  ```typescript TypeScript theme={null}
  import { defineAgent } from "@polos/sdk";
  import { openai } from "@ai-sdk/openai";

  const conversationalAgent = defineAgent({
    id: "chat-agent",
    model: openai("gpt-4o"),
    systemPrompt: "You are a helpful assistant. Be friendly and concise.",
    conversationHistory: 10, // Keep last 10 messages (i.e. 5 conversation turns)
  });
  ```
</CodeGroup>

The agent automatically manages conversation history - no manual bookkeeping required.
**Defaults to conversation\_history=10** when you don't specify anything.

## Using conversation IDs

Group related messages using `conversation_id`.

Works with `agent.run()`:

<CodeGroup>
  ```python Python theme={null}
  client = PolosClient()
  result = await research_agent.run(
      client,
      user_message,
      conversation_id=conversation_id
  )
  ```

  ```typescript TypeScript theme={null}
  const client = PolosClient.fromEnv();
  const result = await researchAgent.run(
    client,
    userMessage,
    { conversationId }
  );
  ```
</CodeGroup>

and `agent.stream()`:

<CodeGroup>
  ```python Python theme={null}
  stream = await research_agent.stream(
      client,
      user_message,
      conversation_id=conversation_id
  )
  ```

  ```typescript TypeScript theme={null}
  const stream = await researchAgent.stream(
    client,
    userMessage,
    { conversationId }
  );
  ```
</CodeGroup>

**How it works:**

1. Agent retrieves past messages for this `conversation_id`
2. Includes them in the LLM context
3. Stores the new message after generating a response

## Example

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from polos import PolosClient

  async def main():
      conversation_id = "user-123-session-1"
      client = PolosClient()

      # Turn 1
      response1 = await my_agent.run(
          client,
          "My name is Alice and I love Python.",
          conversation_id=conversation_id
      )
      print(response1.result)

      # Turn 2 - Agent remembers Alice and Python
      response2 = await my_agent.run(
          client,
          "What's my favorite programming language?",
          conversation_id=conversation_id
      )
      print(response2.result)  # "Your favorite programming language is Python"

      # Turn 3 - Agent remembers the name
      response3 = await my_agent.run(
          client,
          "What's my name?",
          conversation_id=conversation_id
      )
      print(response3.result)  # "Your name is Alice"

  if __name__ == "__main__":
      asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { PolosClient } from "@polos/sdk";

  async function main() {
    const conversationId = "user-123-session-1";
    const client = PolosClient.fromEnv();

    // Turn 1
    const response1 = await myAgent.run(
      client,
      "My name is Alice and I love Python.",
      { conversationId }
    );
    console.log(response1.result);

    // Turn 2 - Agent remembers Alice and Python
    const response2 = await myAgent.run(
      client,
      "What's my favorite programming language?",
      { conversationId }
    );
    console.log(response2.result); // "Your favorite programming language is Python"

    // Turn 3 - Agent remembers the name
    const response3 = await myAgent.run(
      client,
      "What's my name?",
      { conversationId }
    );
    console.log(response3.result); // "Your name is Alice"
  }

  main();
  ```
</CodeGroup>

## History limits

The `conversation_history` parameter controls the maximum number of messages retained:

<CodeGroup>
  ```python Python theme={null}
  # Keep last 20 messages
  agent = Agent(
      id="agent",
      conversation_history=20
  )
  ```

  ```typescript TypeScript theme={null}
  // Keep last 20 messages
  const agent = defineAgent({
    id: "agent",
    conversationHistory: 20,
  });
  ```
</CodeGroup>

**What happens when the limit is exceeded:**

* Oldest messages are dropped
* Most recent messages (in this example, 20 messages) are kept
* Agent always has the latest context