Skip to content

Latest commit

 

History

History
402 lines (306 loc) · 10.7 KB

GROUP_CHAT_GUIDE.md

File metadata and controls

402 lines (306 loc) · 10.7 KB

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

Field Description Example
group_id Unique identifier for the group "team_engineering", "project_alpha"
group_name Human-readable display name "Engineering Team", "Project Alpha"

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

Use Case Description
Knowledge Base Ingesting documents or content from a single source where cross-message correlation isn't needed
Persona Building Building user profiles/personas from individual interactions
Simple Q&A Single-user chatbot interactions without complex context

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

Use Case Description
Multi-User Conversations Group chats where multiple participants interact and context between messages matters
User + AI Assistant Conversations between a user and AI where you want correlated episodic memories
Project/Topic Organization When you need to query and organize memories by logical groupings
Meeting Transcripts Multi-participant discussions where speaker context is important

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

Field Required Description
group_id No Unique identifier for filtering and retrieval (see When to Use Group ID)
name No Human-readable group name
scene No Scene type: assistant (1:1 with AI) or group_chat (group chat)
user_details No Participant information for context

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

Method Description
keyword BM25 keyword retrieval
vector Vector semantic retrieval
hybrid Combined keyword + vector
rrf RRF fusion retrieval (keyword + vector)
agentic LLM-guided multi-round retrieval

Memory Type Options

Type Description
episodic_memory Conversation episodes and events
profile User profile information
foresight Prospective memory
event_log Atomic facts extracted from episodes

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

See Also