Group Chat Conversations Guide

Group Chat Conversations Guide

Home > Docs > Advanced > Group Chat Guide

Overview

EverMemOS supports organizing conversations into groups using group_id and group_name. This allows you to:

• Separate messages into logical groups for better organization
• Filter and retrieve memories by group for targeted searches
• Generate better summaries within each group's context
• Isolate memory contexts between different groups

This guide covers how to leverage group-based memory management for various use cases.

Core Concepts

Group ID and Group Name

Key Benefits:

1. Memory Isolation - Memories from different groups are separated, preventing cross-contamination
2. Targeted Retrieval - Query memories from a specific group without irrelevant results
3. Contextual Summaries - Generate summaries that understand the group's context and participants
4. Scalable Organization - Manage thousands of conversations across multiple groups

When to Use Group ID

Starting from v1.2.0, group_id and group_name are truly optional. When omitted, the API automatically creates a default group based on the sender field.

Scenarios Where Group ID is NOT Needed

Example without group_id:

{
  "message_id": "msg_001",
  "create_time": "2025-01-15T10:00:00+00:00",
  "sender": "user_001",
  "content": "I prefer dark roast coffee in the morning"
}

Scenarios Where Group ID is Recommended

Why it matters: Episodic memories are extracted from multiple related messages. When messages share a group_id, the system can build richer context by understanding the relationships between messages from different senders. Without a group_id, each sender's messages are processed independently.

Example with group_id:

{
  "message_id": "msg_001",
  "create_time": "2025-01-15T10:00:00+00:00",
  "sender": "user_001",
  "content": "What should we use for the database?",
  "group_id": "project_alpha",
  "group_name": "Project Alpha Discussion"
}

Use Cases

1. Team/Department Conversations

Organize conversations by team or department within an organization.

{
  "group_id": "dept_engineering",
  "group_name": "Engineering Department"
}

Benefits:

• Keep engineering discussions separate from marketing, sales, etc.
• Generate team-specific insights and summaries
• Track team decisions and action items

2. Project-Based Conversations

Group all conversations related to a specific project.

{
  "group_id": "project_mobile_app_v2",
  "group_name": "Mobile App v2.0 Development"
}

Benefits:

• All project discussions, decisions, and context in one place
• Query project-specific knowledge: "What was decided about the login flow?"
• Generate project progress summaries

3. Channel-Based Conversations (Slack/Discord Style)

Mirror your communication platform's channel structure.

{
  "group_id": "channel_general",
  "group_name": "#general"
}

{
  "group_id": "channel_random",
  "group_name": "#random"
}

Benefits:

• Maintain channel context when building AI assistants
• Search within specific channels
• Channel-specific summaries and insights

4. Customer Support Conversations

Group support tickets or customer interactions.

{
  "group_id": "support_ticket_12345",
  "group_name": "Ticket #12345 - Login Issue"
}

Benefits:

• Track full context of a support case
• Generate case summaries for handoffs
• Query similar past issues

5. Meeting Transcripts

Organize meeting notes and transcripts.

{
  "group_id": "meeting_weekly_standup_2025_02",
  "group_name": "Weekly Standup - February 2025"
}

Benefits:

• Query across all standups: "What blockers were mentioned this month?"
• Generate meeting summaries automatically
• Track action items across meetings

Data Format

Complete Group Chat Structure

{
  "version": "1.0.0",
  "conversation_meta": {
    "group_id": "team_001",
    "name": "Engineering Team",
    "scene": "group_chat",
    "scene_desc": {},
    "user_details": {
      "alice": {
        "full_name": "Alice Smith",
        "role": "user",
        "custom_role": "Tech Lead",
        "extra": {"department": "Engineering"}
      },
      "bob": {
        "full_name": "Bob Jones",
        "role": "user",
        "custom_role": "Senior Engineer"
      }
    },
    "default_timezone": "+00:00"
  },
  "conversation_list": [
    {
      "message_id": "msg_001",
      "create_time": "2025-02-01T10:00:00+00:00",
      "sender": "alice",
      "sender_name": "Alice Smith",
      "role": "user",
      "type": "text",
      "content": "Let's discuss the new API design"
    },
    {
      "message_id": "msg_002",
      "create_time": "2025-02-01T10:01:00+00:00",
      "sender": "bob",
      "sender_name": "Bob Jones",
      "role": "user",
      "type": "text",
      "content": "I think we should use REST with OpenAPI spec"
    }
  ]
}

Key Fields

Processing Group Chats

Step 1: Prepare Your Data

Create a JSON file following the GroupChatFormat specification.

Step 2: Process the Group Chat

uv run python src/bootstrap.py src/run_memorize.py \
  --input your_group_chat.json \
  --scene group_chat \
  --api-url http://localhost:1995/api/v1/memories

Parameters:

• --input: Path to your GroupChatFormat JSON file (required)
• --scene: Memory extraction scene - group_chat or assistant (required)
• --api-url: Memory API endpoint (required unless using --validate-only)
• --validate-only: Only validate the input file format without processing

Step 3: Verify Processing

Check that memories were extracted:

curl -X GET "http://localhost:1995/api/v1/memories/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What was discussed?",
    "group_id": "team_001",
    "memory_types": ["episodic_memory"],
    "retrieve_method": "rrf"
  }'

Retrieving Group Memories

Filter by Group ID

The primary way to retrieve group-specific memories:

import requests

response = requests.get(
    "http://localhost:1995/api/v1/memories/search",
    json={
        "query": "What decisions were made about the API?",
        "group_id": "team_001",  # Filter to this group only
        "memory_types": ["episodic_memory"],
        "retrieve_method": "rrf",
        "top_k": 10
    }
)

memories = response.json()
result = memories.get("result", {})
for group in result.get("memories", []):
    print(f"Group: {group}")

Retrieve Method Options

Memory Type Options

Generating Group Summaries

EverMemOS can generate contextual summaries within a group because it understands:

• Who participated - User details and roles
• What was discussed - Full conversation context
• When it happened - Temporal relationships
• Key decisions - Extracted from conversation flow

Example: Query for Group Summary

response = requests.get(
    "http://localhost:1995/api/v1/memories/search",
    json={
        "query": "Summarize the key decisions and action items",
        "group_id": "team_001",
        "memory_types": ["episodic_memory", "event_log"],
        "retrieve_method": "agentic"  # Use agentic mode for better synthesis
    }
)

Best Practices

1. Consistent Group ID Naming

Use a consistent naming convention:

# Good: Clear, hierarchical naming
team_engineering
project_mobile_v2
tenant_acme_corp
channel_general

# Avoid: Inconsistent or unclear naming
eng
proj1
abc123

2. Include User Details

Providing user details improves memory quality:

"user_details": {
  "alice": {
    "full_name": "Alice Smith",
    "custom_role": "Tech Lead"  // Helps understand context
  }
}

3. Use Appropriate Scene Types

• Use group_chat for multi-person group chats
• Use assistant for 1:1 conversations with an AI assistant

4. Batch Related Messages

Process conversations in logical batches rather than individual messages for better context understanding.

Example Files

• Chinese Sample - Chinese language example
• English Sample - English language example
• Format Specification - Complete format reference

See Also

• Group Chat Format Specification - Complete data format reference
• Batch Operations Guide - Processing multiple messages
• Memory Retrieval Strategies - Optimizing search
• Conversation Metadata Control - Fine-grained metadata management
• API Documentation - Complete API reference