Skip to main content

​
Overview

The Conversation Metadata API allows you to set metadata for a chat session, including participant details, scene descriptions, and tags. This metadata directly influences how the LLM extracts and retrieves memories.
Setting accurate user_details helps EverMemOS correctly attribute memories to the right participants and improves personalization in multi-user conversations.

​
Key Field: user_details

The user_details field is a dictionary where each key is a user_id and the value contains participant information:
FieldTypeDescription
full_namestring (required)Display name of the participant
rolestringRole in the conversation (e.g., developer, manager, customer)
extraobjectCustom key-value pairs for additional context

​
How user_details Affects LLM Behavior

Memory Extraction

  • Role-aware summarization: A manager’s decision carries different weight than a developer’s suggestion
  • Name resolution: Correctly links nicknames or mentions to the right person
  • Context enrichment: extra fields (e.g., department, expertise) help the LLM understand domain-specific references

Memory Retrieval

  • Scoped search: Queries can be filtered by participant
  • Relevance boosting: User roles influence ranking when searching for decisions or preferences
  • Relationship inference: LLM can infer connections between users based on roles

​
API Usage

​
Create Conversation Metadata

Use POST /api/v1/memories/conversation-meta to initialize metadata for a new chat session. 
import httpx
import asyncio

async def create_conversation_meta():
    headers = {
        "Authorization": "Bearer <your_api_key>",
        "Content-Type": "application/json"
    }
    
    payload = {
        "version": "1.0",
        "scene": "group_chat",
        "scene_desc": {
            "type": "project_discussion"
        },
        "name": "Product Launch Planning",
        "description": "Weekly sync for Q2 product launch",
        "group_id": "group_product_launch_001",
        "created_at": "2025-01-15T10:00:00+00:00",
        "default_timezone": "Asia/Shanghai",
        "tags": ["product", "launch", "q2"],
        "user_details": {
            "user_alice": {
                "full_name": "Alice Johnson",
                "role": "product_manager",
                "extra": {
                    "department": "Product",
                    "expertise": ["roadmap", "prioritization"]
                }
            },
            "user_bob": {
                "full_name": "Bob Smith",
                "role": "engineer",
                "extra": {
                    "department": "Engineering",
                    "expertise": ["backend", "APIs"]
                }
            },
            "user_carol": {
                "full_name": "Carol Williams",
                "role": "designer",
                "extra": {
                    "department": "Design",
                    "expertise": ["UI/UX", "prototyping"]
                }
            }
        }
    }
    
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.evermind.ai/api/v1/memories/conversation-meta",
            json=payload,
            headers=headers
        )
        print(response.json())

asyncio.run(create_conversation_meta())

​
Best Practices

Call the Metadata API before sending the first message to a new group_id. This ensures all memories are extracted with proper participant attribution from the start.
Roles like product_manager, customer, support_agent help the LLM understand the speaker’s perspective. Avoid generic roles like user or member.
Add fields relevant to your use case:
  • Enterprise: department, title, seniority
  • Education: grade, subjects, learning_style
  • Healthcare: specialty, care_team_role
If a user’s role or information changes, update the Metadata promptly. Outdated metadata can lead to incorrect memory attribution.

​
Schema Reference

​
ConversationMetaCreateRequest

FieldTypeRequiredDescription
versionstring✓Metadata version (e.g., "1.0")
scenestring✓Scenario type: group_chat or assistant
scene_descobject✓Scene description with custom fields
namestring✓Conversation name
descriptionstringConversation description
group_idstring✓Unique identifier for the chat
created_atstring✓ISO 8601 timestamp
default_timezonestringTimezone (e.g., "UTC", "Asia/Shanghai")
user_detailsobjectParticipant details dictionary
tagsarrayList of tags for categorization

​
UserDetailRequest

FieldTypeRequiredDescription
full_namestring✓Participant’s display name
rolestringRole in the conversation
extraobjectAdditional custom fields
For complete API specifications, see the API Reference.