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

# Chat History in Agents

> Configure and access agent conversation history.

Agents with storage enabled automatically have access to the run history of the session (also called the "conversation history" or "chat history").

<Note>
  For all forms of session history, you need to have a database assigned to the agent. See [Storage](/database/overview) for more details.
</Note>

We can give the Agent access to the chat history in the following ways:

## Agent-Level History

* You can set `add_history_to_context=True` and `num_history_runs=5` to add the inputs and responses from the last 5 runs automatically to every request sent to the agent.
* You can be more granular about how many messages to add to include in the list sent to the model, by setting `num_history_messages`.
* You can set `read_chat_history=True` to provide a `get_chat_history()` tool to your agent allowing it to read any message in the entire chat history.
* You can set `read_tool_call_history=True` to provide a `get_tool_call_history()` tool to your agent allowing it to read tool calls in reverse chronological order.
* You can enable `search_past_sessions` to allow searching through previous sessions.

<Tip>
  Working with agent history can be tricky. Experiment with the above settings to find the best fit for your use case.
  See the [History Reference](#history-reference) for help on how to use the different history features.
</Tip>

## History Reference

<Tabs>
  <Tab title="Simple History">
    Start with **Agent History in Context** for basic conversation continuity:

    ```python theme={null}
    agent = Agent(
        db=SqliteDb(db_file="tmp/agent.db"),
        add_history_to_context=True,
        num_history_runs=5,
    )
    ```
  </Tab>

  <Tab title="Long Conversations">
    Add **Chat History Tool** when agents need to search history:

    ```python theme={null}
    agent = Agent(
        db=SqliteDb(db_file="tmp/agent.db"),
        read_chat_history=True,  # Agent decides when to look up
    )
    ```
  </Tab>

  <Tab title="Multi-Session Memory">
    Enable **Multi-Session Search** for cross-session continuity:

    ```python theme={null}
    agent = Agent(
        db=SqliteDb(db_file="tmp/agent.db"),
        search_past_sessions=True,
        num_past_sessions_to_search=10,
    )
    ```
  </Tab>
</Tabs>

<Note>
  **Database Requirement**: All history features require a database configured on the agent. See [Storage](/database/overview) for setup.
</Note>

<Tip>
  **Performance Tip**: More history = larger context = slower and costlier requests. Start with `num_history_runs=3` and increase only if needed.
</Tip>

### Add history to the agent context

To add the history of the conversation to the context, you can set `add_history_to_context=True`.
This will add the inputs and responses from the last 3 runs (that is the default) to the context of the agent.
You can change the number of runs by setting `num_history_runs=n` where `n` is the number of runs to include.

You can either set `add_history_to_context=True` on the `Agent` or on the `run()` method directly.
See the [Persistent Session with History](/history/agent/persistent-session-history) example for a complete implementation.

Learn more in the [Context Engineering](/context/overview) documentation.

## Read the chat history

To read the chat history, you can set `read_chat_history=True`.
This will provide a `get_chat_history()` tool to your agent allowing it to read any message in the entire chat history.

See the [Chat History Management](/history/agent/chat-history) page for a complete implementation.

## Search the session history

In some scenarios, you might want to fetch messages from across multiple sessions to provide context or continuity in conversations.

Set `search_past_sessions=True` to give the agent two tools: `search_past_sessions()` returns previews of recent sessions, and `read_past_session(session_id)` returns the full conversation for a specific session.

* `num_past_sessions_to_search`: Maximum number of past sessions to search. Defaults to 20.
* `num_past_session_runs_in_search`: Number of runs per session shown in the preview. Defaults to 3.

<Tip>
  Keep `num_past_sessions_to_search` low to avoid filling up the context length of the model, which can lead to performance issues.
</Tip>

## Developer Resources

<CardGroup cols={2}>
  <Card title="Chat History Example" icon="message" iconType="duotone" href="/history/agent/chat-history">
    Retrieve stored messages from agent conversations with get\_chat\_history().
  </Card>

  <Card title="Persistent Session with History" icon="database" iconType="duotone" href="/history/agent/persistent-session-history">
    Control how much conversation history is included using num\_history\_runs.
  </Card>
</CardGroup>