> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.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](https://agno-v2.mintlify.site/database/overview.md) for more details.

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.

## History Reference

**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,
)
```

**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
)
```

**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,
)
```

> [!NOTE]
>
> **Database Requirement**: All history features require a database configured on the agent. See [Storage](https://agno-v2.mintlify.site/database/overview.md) for setup.

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

### 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](https://agno-v2.mintlify.site/history/agent/persistent-session-history.md) example for a complete implementation.

Learn more in the [Context Engineering](https://agno-v2.mintlify.site/context/overview.md) 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](https://agno-v2.mintlify.site/history/agent/chat-history.md) 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.

## Developer Resources

> **[Chat History Example](https://agno-v2.mintlify.site/history/agent/chat-history.md)**
>
> Retrieve stored messages from agent conversations with get\_chat\_history().

> **[Persistent Session with History](https://agno-v2.mintlify.site/history/agent/persistent-session-history.md)**
>
> Control how much conversation history is included using num\_history\_runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.