> ## Documentation Index
> Fetch the complete documentation index at: https://mem0-feature-memo-claude-plugin-v1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Chat

> Enable multi-participant conversations and scope each speaker with user_id or agent_id

## Overview

The Group Chat feature helps you use Mem0 with conversations involving multiple participants, such as team meetings or multi-agent conversations. You control which speaker a memory belongs to by scoping each `add()` call with `user_id`, `agent_id`, and `run_id`; Mem0 does not infer that scope automatically from the conversation.

When you scope conversations correctly, Mem0:

* Extracts memories from each participant's messages
* Keeps each participant's memories in a separate profile, addressed by the `user_id` or `agent_id` you assigned them
* Lets you retrieve any participant's memories independently using filters

## How Group Chat Works

Mem0 does not automatically split a multi-participant conversation into separate memories per speaker. A `name` field on a message is stored as context for extraction, but it does not change which `user_id` or `agent_id` the resulting memories are scoped to: that scope is always whatever `user_id`, `agent_id`, or `run_id` you pass to `add()`.

To keep separate memory profiles per participant, scope each participant's messages explicitly: call `add()` once per participant with their own `user_id`, or use `run_id` to group the conversation and filter by participant in your own message metadata.

### Memory Attribution Rules

* Memories are always scoped to the `user_id`, `agent_id`, and `run_id` you pass to `add()`, not to the `name` field on individual messages.
* If you need per-participant memories, call `add()` separately for each participant's messages with that participant's `user_id`.

## Using Group Chat

### Basic Group Chat

Scope each participant's messages with their own `user_id` and a shared `run_id` for the session. Call `add()` once per participant:

<CodeGroup>
  ```python Python theme={null}
  from mem0 import MemoryClient

  client = MemoryClient(api_key="your-api-key")

  # Each participant gets their own user_id; run_id ties them to one session
  client.add(
      [{"role": "user", "content": "Hey team, I think we should use React for the frontend"}],
      user_id="alice", run_id="group_chat_1",
  )
  client.add(
      [{"role": "user", "content": "I'd prefer Vue.js for our use case"}],
      user_id="bob", run_id="group_chat_1",
  )
  response = client.add(
      [{"role": "user", "content": "Consider Angular, it has great enterprise support"}],
      user_id="charlie", run_id="group_chat_1",
  )
  print(response)
  ```

  ```json Output theme={null}
  {
    "event_id": "4d82478a-8d50-47e6-9324-1f65efff5829",
    "status": "PENDING"
  }
  ```
</CodeGroup>

`add()` is asynchronous: it queues extraction and returns immediately. Poll `get_all` (see below) once processing completes to see the extracted memories. Each participant's memory is scoped to the `user_id` you passed, so filtering by `run_id` returns all three, and filtering by a single `user_id` returns just that participant.

### The `name` field does not change scope

The `name` field is stored as extraction context only. Attribution follows the `user_id`/`agent_id`/`run_id` you pass to `add()`, never the `name`. Passing two different names in one `add()` call does **not** split the memories across two profiles:

<CodeGroup>
  ```python Python theme={null}
  # BOTH messages are scoped to user_id="team_session", NOT to "alice"/"bob"
  client.add(
      [
          {"role": "user", "name": "Alice", "content": "I strongly prefer React"},
          {"role": "user", "name": "Bob", "content": "I strongly prefer Vue"},
      ],
      user_id="team_session", run_id="group_chat_2",
  )

  # Every extracted memory lands under user_id="team_session"
  client.get_all(filters={"AND": [{"user_id": "team_session"}]})

  # Nothing is stored under user_id="alice" or user_id="bob"
  client.get_all(filters={"AND": [{"user_id": "alice"}]})  # -> no results from this call
  ```
</CodeGroup>

To keep Alice's and Bob's memories in separate profiles, call `add()` once per participant with their own `user_id`, as shown in [Basic Group Chat](#basic-group-chat) above.

## Retrieving Group Chat Memories

### Get All Memories for a Session

Retrieve all memories from a specific group chat session:

<CodeGroup>
  ```python Python theme={null}
  # Get all memories for a specific run_id
  # Use wildcard "*" for user_id to match all participants
  filters = {
      "AND": [
          {"user_id": "*"},
          {"run_id": "group_chat_1"}
      ]
  }

  all_memories = client.get_all(filters=filters, page=1)
  print(all_memories)
  ```

  ```json Output theme={null}
  {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
          {
              "id": "147559a8-c5f7-44d0-9418-91f53f7a89a4",
              "memory": "suggests considering Angular because it has great enterprise support",
              "user_id": "charlie",
              "run_id": "group_chat_1",
              "created_at": "2025-06-21T05:51:11.007223-07:00",
              "updated_at": "2025-06-21T05:51:11.626562-07:00"
          },
          {
              "id": "1d8b8f39-7b17-4d18-8632-ab1c64fa35b9",
              "memory": "prefers Vue.js for our use case",
              "user_id": "bob",
              "run_id": "group_chat_1",
              "created_at": "2025-06-21T05:51:08.675301-07:00",
              "updated_at": "2025-06-21T05:51:09.319269-07:00"
          },
          {
              "id": "4d82478a-8d50-47e6-9324-1f65efff5829",
              "memory": "prefers using React for the frontend",
              "user_id": "alice",
              "run_id": "group_chat_1",
              "created_at": "2025-06-21T05:51:05.943223-07:00",
              "updated_at": "2025-06-21T05:51:06.982539-07:00"
          }
      ]
  }
  ```
</CodeGroup>

### Get Memories for a Specific Participant

Retrieve memories from a specific participant in a group chat:

<CodeGroup>
  ```python Python theme={null}
  # Get memories for a specific participant
  filters = {
      "AND": [
          {"user_id": "charlie"},
          {"run_id": "group_chat_1"}
      ]
  }

  charlie_memories = client.get_all(filters=filters, page=1)
  print(charlie_memories)
  ```

  ```json Output theme={null}
  {
      "count": 1,
      "next": null,
      "previous": null,
      "results": [
          {
              "id": "147559a8-c5f7-44d0-9418-91f53f7a89a4",
              "memory": "suggests considering Angular because it has great enterprise support",
              "user_id": "charlie",
              "run_id": "group_chat_1",
              "created_at": "2025-06-21T05:51:11.007223-07:00",
              "updated_at": "2025-06-21T05:51:11.626562-07:00"
          }
      ]
  }
  ```
</CodeGroup>

### Search Within Group Chat Context

Search for specific information within a group chat session:

<CodeGroup>
  ```python Python theme={null}
  # Search within group chat context
  filters = {
      "AND": [
          {"user_id": "charlie"},
          {"run_id": "group_chat_1"}
      ]
  }

  search_response = client.search(
      query="What are the tasks?",
      filters=filters
  )
  print(search_response)
  ```

  ```json Output theme={null}
  {
      "results": [
          {
              "id": "147559a8-c5f7-44d0-9418-91f53f7a89a4",
              "memory": "suggests considering Angular because it has great enterprise support",
              "user_id": "charlie",
              "run_id": "group_chat_1",
              "created_at": "2025-06-21T05:51:11.007223-07:00",
              "updated_at": "2025-06-21T05:51:11.626562-07:00"
          }
      ]
  }
  ```
</CodeGroup>

## Message Format Requirements

### Required Fields

Each message must include:

* `role`: The participant's role (`"user"`, `"assistant"`, `"agent"`)
* `content`: The message content
* `name` (optional): The participant's name, stored as context for extraction. It does not change which `user_id` or `agent_id` a memory is scoped to.

### Example Message Structure

```json theme={null}
{
  "role": "user",
  "name": "Alice",
  "content": "I think we should use React for the frontend"
}
```

### Roles

* **`user`**: Human participants
* **`assistant`**: AI assistants

## Best Practices

1. **Consistent Scoping**: Use a consistent `user_id` (or `agent_id`) per participant across sessions so their memories stay in one profile.

2. **Clear Role Assignment**: Ensure each participant has the correct role (`user`, `assistant`, or `agent`) for proper memory categorization.

3. **Session Management**: Use meaningful `run_id` values to organize group chat sessions and enable easy retrieval.

4. **Memory Filtering**: Use filters to retrieve memories from specific participants or sessions when needed.

5. **Async Processing**: Memory additions are processed asynchronously by default, which is ideal for large group conversations.

6. **Search Context**: Leverage the search functionality to find specific information within group chat contexts.

## Use Cases

* **Team Meetings**: Track individual team member preferences and contributions
* **Customer Support**: Maintain separate memory profiles for different customers
* **Multi-Agent Systems**: Manage conversations with multiple AI assistants
* **Collaborative Projects**: Track individual preferences and expertise areas
* **Group Discussions**: Maintain context for each participant's viewpoints

If you have any questions, please feel free to reach out to us using one of the following methods:

<Snippet file="get-help.mdx" />