The add() operation is a basic part of Mem0's memory management system. It's how you store information your application or agent can later recall. Whether you're saving user preferences, maintaining conversation context, or building consistent AI personalities, understanding how to use add() effectively is key to building memory-enhanced AI applications.

The Basics of add()

The basic structure of the add() operation is:

client.add(
    messages,           # Required: Content to store
    user_id=None,       # Optional: For user-specific memories
    agent_id=None,      # Optional: For agent-specific memories
    run_id=None,        # Optional: For session-specific memories
    metadata=None,      # Optional: For adding context to the memories stored
    output_format="v1.0" # Optional: Format version for memory operations (v1.0 is the default)
)

client.add(
    messages,           # Required: Content to store
    user_id=None,       # Optional: For user-specific memories
    agent_id=None,      # Optional: For agent-specific memories
    run_id=None,        # Optional: For session-specific memories
    metadata=None,      # Optional: For adding context to the memories stored
    output_format="v1.0" # Optional: Format version for memory operations (v1.0 is the default)
)

client.add(
    messages,           # Required: Content to store
    user_id=None,       # Optional: For user-specific memories
    agent_id=None,      # Optional: For agent-specific memories
    run_id=None,        # Optional: For session-specific memories
    metadata=None,      # Optional: For adding context to the memories stored
    output_format="v1.0" # Optional: Format version for memory operations (v1.0 is the default)
)

add() also accepts a custom_categories parameter for classifying memories into domain-specific buckets beyond Mem0's defaults; see Understanding Custom Categories for how that works.

The Different Types of Memories

The add() operation allows you to store memories in two different contexts:

• Long-term memories

• Session-based memories

Let's dive into how to use each one.

1. Long-term Memories

Use this when you need to store information that should persist across multiple sessions:

# Example 1: Storing student learning preferences
messages = [
    {"role": "user", "content": "I'm Sarah. I prefer visual learning and need closed captions for videos."},
    {"role": "assistant", "content": "Hi Sarah! I understand you're a visual learner and require closed captions."}
]

client.add(messages, user_id="sarah", output_format="v1.1")

# Example 2: Storing a single piece of information
client.add(
    "Takes advanced piano lessons every Tuesday", 
    user_id="sarah", 
    metadata={"category": "musical_skills"}
)

# Example 1: Storing student learning preferences
messages = [
    {"role": "user", "content": "I'm Sarah. I prefer visual learning and need closed captions for videos."},
    {"role": "assistant", "content": "Hi Sarah! I understand you're a visual learner and require closed captions."}
]

client.add(messages, user_id="sarah", output_format="v1.1")

# Example 2: Storing a single piece of information
client.add(
    "Takes advanced piano lessons every Tuesday", 
    user_id="sarah", 
    metadata={"category": "musical_skills"}
)

# Example 1: Storing student learning preferences
messages = [
    {"role": "user", "content": "I'm Sarah. I prefer visual learning and need closed captions for videos."},
    {"role": "assistant", "content": "Hi Sarah! I understand you're a visual learner and require closed captions."}
]

client.add(messages, user_id="sarah", output_format="v1.1")

# Example 2: Storing a single piece of information
client.add(
    "Takes advanced piano lessons every Tuesday", 
    user_id="sarah", 
    metadata={"category": "musical_skills"}
)

To store a memory, you need to provide:

• either a user_id or agent_id , this binds the memory and provides context when retrieving memories in the future.

• the messages parameter can accept either a string or a list of message dictionaries

• optional metadata to attach additional context for the memories, e.g., the category the memory belongs to

add() also supports includes and excludes parameters for controlling which parts of a conversation get stored in the first place; useful when you want the AI to remember technical preferences but ignore small talk, for example. See Customizing Memory in Mem0 for the full pattern.

2. Session-Based Memories

Short-term memories in Mem0 are crucial for managing session-specific information. For instance, during a customer support session, Mem0 can retain details such as the customer's recent queries, issues they're facing, and their preferred communication style. This allows support agents to maintain context throughout the session, providing quick, personalized assistance without requiring the user to repeat information. Once the session ends, the memory resets, ensuring that temporary information doesn’t carry over unnecessarily, keeping interactions fresh for the next session.

messages = [
    {"role": "user", "content": "I'm planning a trip to Japan next month."},
    {"role": "assistant", "content": "That's exciting! Would you like some recommendations?"}
]

client.add(
    messages,
    user_id="alex123",    # Required: Who the session belongs to
    run_id="trip-planning-2024",  # Required: Unique session identifier
    output_format="v1.1"
)

messages = [
    {"role": "user", "content": "I'm planning a trip to Japan next month."},
    {"role": "assistant", "content": "That's exciting! Would you like some recommendations?"}
]

client.add(
    messages,
    user_id="alex123",    # Required: Who the session belongs to
    run_id="trip-planning-2024",  # Required: Unique session identifier
    output_format="v1.1"
)

messages = [
    {"role": "user", "content": "I'm planning a trip to Japan next month."},
    {"role": "assistant", "content": "That's exciting! Would you like some recommendations?"}
]

client.add(
    messages,
    user_id="alex123",    # Required: Who the session belongs to
    run_id="trip-planning-2024",  # Required: Unique session identifier
    output_format="v1.1"
)

For short-term memories, you need to include either a user_id or agent_id and a run_id. This associates the session to a particular user or agent.

Output Formats

Mem0 supports two output formats:

# Default format (v1.0)
client.add(messages, user_id="alex")

# Enhanced format (v1.1) - Recommended
client.add(messages, user_id="alex", output_format="v1.1")

# Default format (v1.0)
client.add(messages, user_id="alex")

# Enhanced format (v1.1) - Recommended
client.add(messages, user_id="alex", output_format="v1.1")

# Default format (v1.0)
client.add(messages, user_id="alex")

# Enhanced format (v1.1) - Recommended
client.add(messages, user_id="alex", output_format="v1.1")

The difference is that v1.0 returns a basic operation status, whether it was successful or not, and v1.1 has detailed information about memory operations. For example, add operations return the saved memory and the event type, which is ADD. Search operations return the memory and other details like the conversation that the memory was extracted from.

# example v1.0 output

{'message': 'ok'}

# example v1.1 output

{
    "results": [
        {
            "memory": "Name is Alex",
            "event": "ADD"
        },
        {
            "memory": "Is a vegetarian",
            "event": "ADD"
        },
        {
            "memory": "Is allergic to nuts",
            "event": "ADD"
        }
    ]
}

# example v1.0 output

{'message': 'ok'}

# example v1.1 output

{
    "results": [
        {
            "memory": "Name is Alex",
            "event": "ADD"
        },
        {
            "memory": "Is a vegetarian",
            "event": "ADD"
        },
        {
            "memory": "Is allergic to nuts",
            "event": "ADD"
        }
    ]
}

# example v1.0 output

{'message': 'ok'}

# example v1.1 output

{
    "results": [
        {
            "memory": "Name is Alex",
            "event": "ADD"
        },
        {
            "memory": "Is a vegetarian",
            "event": "ADD"
        },
        {
            "memory": "Is allergic to nuts",
            "event": "ADD"
        }
    ]
}

Conclusion

The add() operation is your primary tool for storing memories in Mem0. By understanding its parameters and best practices, you can effectively manage different types of memories in your AI applications. Always use the appropriate identifiers, consider the persistence requirements of your memories, and leverage metadata for better organization. Once memories are stored, Mem0's search() operation is how you retrieve them — basic queries, output formats, and advanced filtering by user_id, agent_id, and date range.

View Mem0's documentation to learn more about integrating our memory features. You can also reach out to us at [email protected].