Agent Memory

Agents can carry information throughout a single run or across conversations or agent instances. Short-term memory is handled through agent state that stores conversation history and tool results for a single run. Long-term memory is managed by Mem0 and agents can use it to store facts, preferences, or context across multiple conversations and multiple agent instances.

Agent State

State is a centralized storage all tools can read from and write to. It's a structured way to share data between tools and the Agent, maintain conversation history, and store intermediate results for one run.

When you call an Agent, the only information it has is what's in the prompt and the data it was trained on. If an Agent has tools and is part of a conversational system, it's useful to give it additional information, such as its past conversations, the tools it has called, and their results. You'll usually also want to allow the Agent to change this data as it goes along or share it between tools. For example, a tool that searches the web for information may need to store the search results in the state so that other tools can use it. Such external data that the Agent can read and modify is called the Agent's state.

Information stored in the state is available only during the current run. When the chat ends, the state is cleared.

Conversation History

State automatically stores the conversation history in the messages field. This field uses list[ChatMessage] type. By default, it appends new messages to the list so that they're included in the conversation history.

The stored messages include:

• User messages
• System messages
• LLM responses (including tool calls)
• Tool results

Defining What Data is Stored in State

You can define:

• What data is stored in the state. You can choose which tool inputs and outputs are stored in the state.
• The type of the data. State supports standard Python types:
  • Basic types: str,int, float, bool
  • Lists: list, list[str], list[int], list[Document]
  • Union types: Union[str, int], Optional[str]
  • Custom classes and data classes
• How the data is merged when it's updated.

To learn about how tools interact with Agent state, see Tools and Agent State.

Long-Term Memory with Mem0

Conversation history and Agent state are scoped to a single session. When a conversation ends, that data doesn't carry over. For use cases where you want the Agent to remember facts, preferences, or context across multiple conversations, you can add long-term memory backed by Mem0.

Mem0 automatically extracts structured facts from conversations using an LLM, stores them as vector embeddings, and retrieves relevant memories using semantic search.

Mem0 memory consists of two tools that work together:

• Store memories: Stores information as a long-term memory.
• Retrieve memories: Searches past memories relevant to the current conversation.

You can add both tools to an agent or just one, depending on your needs.

Memory Shared Across Agents

Memories are scoped by user ID, which the agent passes with every memory operation. Each user gets their own private set of memories, stored and retrieved independently. Even when multiple users interact with the same agent, they never see each other's memories.

Memories stored in Mem0 are available to all Agents connected to the same Mem0 account. This means that if you create multiple Agents in your workspace, they will all be able to access the same memories for a given user.

How It Works

When a user sends a message, the Agent can retrieve memories to pull in relevant facts from previous conversations before generating a response. After the conversation, the agent can store new information for future sessions.

Requirements

To use Mem0 memory, you need a Mem0 API key.

Configuration Options

Option	Description
Mem0 API key	The workspace secret that holds your Mem0 API key. The same key is used for both tools.
Memory writer	Toggle to give the Agent the ability to store memories.
Memory retriever	Toggle to give the Agent the ability to search past memories.
Top k (retriever)	The maximum number of memories the retriever returns per call. Defaults to five.

You can also customize the tool names and descriptions shown to the LLM for each sub-tool.

Chat History Granularity Beta

When an agent pipeline runs in a multi-turn conversation, the platform replays past conversation turns to the agent on each new request. You can control how much of the chat history is replayed using the chat history granularity setting in the pipeline YAML or through the API.

You can choose between two modes:

• QUERY_ANSWER (default): Only the user's query and the agent's final answer from each past turn are included. This is compact and works well for most conversational use cases.
• ALL_MESSAGES: Every message from each past turn is included — tool calls, tool results, reasoning steps, and the final answer. Use this mode when the agent needs the full context of previous interactions, for example when follow-up requests depend on which tools were called or what results they returned.

Chat History Granularity in the Pipeline YAML

You can also set the granularity directly in the pipeline YAML configuration under the history key:

history:
  granularity: all_messages

Accepted values are all_messages and query_answer (lowercase). The pipeline YAML setting acts as a default and is overridden by any value passed explicitly in the API request.

Priority Order

The effective granularity is determined in this order:

1. Explicit value passed in the API request (chat_history_granularity field).
2. Value set in the pipeline YAML (history.granularity).
3. Default: QUERY_ANSWER.