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.