Skip to main content
EverMemOS supports a standardized group chat data format (GroupChatFormat) for batch importing conversation histories. This is ideal for migrating existing chat logs or initializing the system with historical data.

​
Prerequisites

Before batch storing memories, ensure you have:
  1. EverMemOS running locally - Follow the Quickstart Guide to set up your environment
  2. API service active - The Memory API should be accessible at http://localhost:8001
  3. Properly formatted data - Your chat data should follow the GroupChatFormat specification

​
GroupChatFormat Specification

The standard format is a JSON file with the following structure: 
{
  "version": "1.0.0",
  "conversation_meta": {
    "group_id": "group_001",
    "name": "Project Discussion Group",
    "user_details": {
      "user_101": {
        "full_name": "Alice",
        "role": "Product Manager"
      },
      "user_102": {
        "full_name": "Bob",
        "role": "Engineer"
      }
    }
  },
  "conversation_list": [
    {
      "message_id": "msg_001",
      "create_time": "2025-02-01T10:00:00+00:00",
      "sender": "user_101",
      "content": "Good morning everyone, let's start the sprint planning"
    },
    {
      "message_id": "msg_002",
      "create_time": "2025-02-01T10:02:00+00:00",
      "sender": "user_102",
      "content": "Sounds good! I've prepared the technical requirements"
    }
  ]
}

​
Key Fields

FieldTypeDescription
conversation_meta.group_idstringUnique identifier for the group
conversation_meta.namestringDisplay name of the group
conversation_meta.user_detailsobjectDictionary of participant information
conversation_listarrayOrdered list of messages
message_idstringUnique identifier for each message
create_timestringISO 8601 timestamp
senderstringUser ID of the message sender
contentstringMessage text content

​
Batch Import Commands

​
Import Chinese Data

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

​
Import English Data

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

​
Validate Format Without Importing

Before importing large datasets, you can validate the file format: 
uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat_en.json \
  --scene group_chat \
  --validate-only

​
Scene Parameter

The --scene parameter is required and specifies the memory extraction strategy:
  • assistant: For one-on-one conversations with an AI assistant
  • group_chat: For multi-person group discussions
Note: In your data files, you may see scene values like work or company — these are internal scene descriptors in the data format. The --scene command-line parameter uses different values to specify which extraction pipeline to apply.

​
Sample Data

EverMemOS provides sample datasets in the data/ directory:
  • data/group_chat_zh.json - Chinese group chat example
  • data/group_chat_en.json - English group chat example
These files demonstrate the correct format and can be used for testing.

​
What Happens During Import

When you run the batch import script, EverMemOS:
  1. Validates the format - Ensures all required fields are present
  2. Sends messages sequentially - Posts each message to the Memory API
  3. Triggers boundary detection - Automatically segments conversations into meaningful topics
  4. Extracts memories - Creates MemCells when topic boundaries are detected
  5. Updates profiles - Builds and updates user profiles based on the conversation
By default, all memory types are extracted and stored: Episodes, Atomic Facts, Foresight, and User Profiles.

​
Next Steps

After importing your data:
  1. Verify the import - Use the Memory API to query stored memories
  2. Test retrieval - Try different Retrieval Strategies to search your data
  3. Integrate with your app - Start building features using the stored memories
For production environments, consider using the EverMemOS Cloud API for higher reliability and managed infrastructure.