# Understanding Mem0's add() Operation

**Taranjeet Singh**  
October 12, 2024

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:

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

## 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:

```python
# 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 list of message dictionaries
- optional `metadata` to attach additional context for the memories eg the `category` the memory belongs to

### 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 like the customer's recent queries, issues they're facing, and preferences for communication style. This allows support agents to maintain context within the session, providing quick, personalized assistance without needing 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.

```python
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)
```python
client.add(messages, user_id="alex")
```

### Enhanced format (v1.1) - Recommended
```python
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
```json
{'message': 'ok'}
```

#### example v1.1 output
```json
{
    "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.

View Mem0's [documentation](https://docs.mem0.ai/?ref=mem0.ai) to learn more about integrating our memory features. You can also reach out to us at [founders@mem0.ai](mailto:founders@mem0.ai).