Conversation Metadata Control Guide

Conversation Metadata Control Guide

Home > Docs > Advanced > Metadata Control

Overview

EverMemOS uses conversation metadata to provide context for memory extraction and retrieval. Properly configured metadata enables:

• Better memory extraction - Understanding who said what and in what context
• Accurate retrieval filtering - Querying memories by user, group, or time range
• Contextual summaries - Generating summaries that understand participants and relationships
• Multi-tenant isolation - Separating memories between different groups or organizations

This guide explains when and how to control metadata for optimal results.

When to Control Metadata

1. Multi-User Conversations

Use Case: Group chats, team discussions, meetings with multiple participants

Why: Without user_details, EverMemOS cannot distinguish between speakers or understand their roles.

{
  "conversation_meta": {
    "user_details": {
      "alice": {
        "full_name": "Alice Smith",
        "role": "user",
        "custom_role": "Tech Lead",
        "department": "Engineering"
      },
      "bob": {
        "full_name": "Bob Jones",
        "role": "user",
        "custom_role": "Product Manager"
      }
    }
  }
}

Benefits:

• Memory extraction attributes facts to the correct person
• Retrieval can filter by specific user within a group
• Summaries understand organizational context

2. AI Assistant Conversations

Use Case: 1:1 conversations between a user and an AI assistant

Why: The scene and scene_desc fields tell EverMemOS which messages are from the AI (to potentially exclude from personal memory extraction).

{
  "conversation_meta": {
    "scene": "assistant",
    "scene_desc": {
      "description": "Project discussion group chat"
    },
    "user_details": {
      "user_123": {
        "full_name": "John Doe",
        "role": "user"
      },
      "assistant_001": {
        "full_name": "AI Assistant",
        "role": "assistant"
      }
    }
  }
}

Benefits:

• AI responses can be handled differently from user messages
• Personal memories focus on what the user shared, not AI responses

3. Cross-Timezone Teams

Use Case: Distributed teams working across different timezones

Why: The default_timezone ensures timestamps are interpreted correctly when timezone info is missing from individual messages.

{
  "conversation_meta": {
    "default_timezone": "America/Los_Angeles",
    "user_details": {
      "dev_sf": {"full_name": "SF Developer"},
      "dev_tokyo": {"full_name": "Tokyo Developer"}
    }
  }
}

Benefits:

• Temporal queries ("What was discussed yesterday?") work correctly
• Memory ordering is accurate across timezones

4. Categorized Conversations

Use Case: Organizing conversations by type (work, social, family, etc.)

Why: The scene field categorizes conversations for better context understanding and potential filtering.

{
  "conversation_meta": {
    "scene": "group_chat",
    "tags": ["project-alpha", "backend", "Q1-2025"]
  }
}

Benefits:

• Memory extraction understands the context (professional vs casual)
• Tags enable additional filtering and organization

5. Default Configuration Fallback

Use Case: Setting organization-wide defaults that apply when specific group config is missing

Why: EverMemOS supports a default configuration that applies when a specific group_id config is not found.

# Save default config (no group_id)
requests.post(
    "http://localhost:1995/api/v1/memories/conversation-meta",
    json={
        "scene": "group_chat",
        "name": "Default Work Config",
        "default_timezone": "UTC",
        "user_details": {}
    }
)

Benefits:

• New groups automatically inherit sensible defaults
• Reduces configuration overhead for common settings

Metadata Fields Reference

Conversation Metadata (conversation_meta)

User Details (user_details)

Message Metadata

API Operations

Store Message with Metadata

When storing a single message, you can include group and sender metadata:

import requests

response = requests.post(
    "http://localhost:1995/api/v1/memories",
    json={
        "message_id": "msg_001",
        "create_time": "2025-02-01T10:00:00+00:00",
        "sender": "user_123",
        "sender_name": "John",  # Optional display name
        "content": "I prefer Python for backend development",
        "group_id": "team_engineering",
        "group_name": "Engineering Team",
        "role": "user"
    }
)

Search with Metadata Filters

Filter search results by user or group:

# Search within a specific group
response = requests.get(
    "http://localhost:1995/api/v1/memories/search",
    json={
        "query": "What programming languages are preferred?",
        "group_id": "team_engineering",
        "user_id": "user_123",  # Optional: filter to specific user
        "retrieve_method": "rrf",
        "start_time": "2025-01-01T00:00:00+00:00",
        "end_time": "2025-02-01T00:00:00+00:00"
    }
)

Manage Conversation Metadata

Get Metadata (with fallback to default)

# Get specific group's metadata
response = requests.get(
    "http://localhost:1995/api/v1/memories/conversation-meta",
    json={"group_id": "team_engineering"}
)

# Get default config
response = requests.get(
    "http://localhost:1995/api/v1/memories/conversation-meta",
    json={}
)

Save/Update Metadata (Full Replace)

response = requests.post(
    "http://localhost:1995/api/v1/memories/conversation-meta",
    json={
        "group_id": "team_engineering",
        "scene": "group_chat",
        "name": "Engineering Team",
        "description": "Backend engineering team discussions",
        "default_timezone": "America/Los_Angeles",
        "user_details": {
            "alice": {
                "full_name": "Alice Smith",
                "role": "user",
                "custom_role": "Tech Lead"
            }
        },
        "tags": ["engineering", "backend"]
    }
)

Partial Update Metadata

Update only specific fields without replacing the entire record:

response = requests.patch(
    "http://localhost:1995/api/v1/memories/conversation-meta",
    json={
        "group_id": "team_engineering",
        "name": "Backend Engineering Team",  # Only update name
        "tags": ["engineering", "backend", "python"]  # Update tags
    }
)

Fields that can be partially updated:

• name
• description
• scene_desc
• tags
• default_timezone
• user_details (replaces entire user_details object)

Delete Memories with Metadata Filters

# Delete all memories for a specific user in a group
response = requests.delete(
    "http://localhost:1995/api/v1/memories",
    json={
        "user_id": "user_123",
        "group_id": "team_engineering"
    }
)

Use Cases

1. Customer Support System

Track support conversations with customer context:

{
  "conversation_meta": {
    "group_id": "support_ticket_12345",
    "scene": "assistant",
    "scene_desc": {"description": "Support conversation with customer"},
    "name": "Ticket #12345 - Login Issue",
    "tags": ["support", "login", "high-priority"],
    "user_details": {
      "customer_abc": {
        "full_name": "Jane Customer",
        "role": "user",
        "extra": {"account_tier": "enterprise"}
      },
      "support_bot": {
        "full_name": "Support Assistant",
        "role": "assistant"
      }
    }
  }
}

2. Meeting Transcription

Capture meeting context with participant roles:

{
  "conversation_meta": {
    "group_id": "meeting_standup_2025_02_01",
    "scene": "group_chat",
    "name": "Daily Standup - Feb 1, 2025",
    "default_timezone": "America/New_York",
    "tags": ["standup", "daily", "sprint-23"],
    "user_details": {
      "pm_sarah": {
        "full_name": "Sarah Johnson",
        "custom_role": "Scrum Master"
      },
      "dev_mike": {
        "full_name": "Mike Chen",
        "custom_role": "Senior Developer"
      },
      "dev_lisa": {
        "full_name": "Lisa Park",
        "custom_role": "Frontend Developer"
      }
    }
  }
}

3. Personal AI Assistant

Track personal conversations with the AI:

{
  "conversation_meta": {
    "group_id": "personal_assistant_john",
    "scene": "assistant",
    "scene_desc": {"description": "Personal assistant conversation with John"},
    "name": "John's Personal Assistant",
    "user_details": {
      "john": {
        "full_name": "John Doe",
        "role": "user"
      },
      "claude_assistant": {
        "full_name": "Claude",
        "role": "assistant"
      }
    }
  }
}

Best Practices

1. Always Provide User Details

Even for simple conversations, providing user_details improves memory quality:

"user_details": {
  "user_123": {"full_name": "John Doe"}
}

2. Use Consistent User IDs

Use the same sender ID across all messages from the same person. The ID in messages must match keys in user_details.

3. Include Timezone Information

Always include timezone in message timestamps or set default_timezone:

"create_time": "2025-02-01T10:00:00-05:00"

4. Use Appropriate Scene Types

• assistant: Use for 1:1 human-AI conversations
• group_chat: Use for multi-person group chats and meetings

5. Leverage Tags for Organization

Tags provide additional filtering and categorization without affecting the core metadata structure.

See Also

• Group Chat Guide - Multi-participant conversations
• Group Chat Format Specification - Complete schema reference
• Batch Operations - Processing conversations in batch
• API Documentation - Complete API reference