fix: prevent timestamp collision in ChatMessage ID generation

- Add UUID suffix to ChatMessage entry_id to ensure uniqueness
- Update ID format from 'session:timestamp' to 'session:timestamp:uuid'
- Add test for rapid message creation with same timestamp
- Fixes #449"

Author: nkanu17

redisvl/extensions/message_history/schema.py

@@ -1,4 +1,5 @@
 from typing import Dict, List, Optional
+from uuid import uuid4
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
@@ -14,7 +15,7 @@
 )
 from redisvl.redis.utils import array_to_buffer
 from redisvl.schema import IndexSchema
-from redisvl.utils.utils import current_timestamp, deserialize
+from redisvl.utils.utils import current_timestamp
 
 
 class ChatMessage(BaseModel):
@@ -44,8 +45,11 @@ def generate_id(cls, values):
         if TIMESTAMP_FIELD_NAME not in values:
             values[TIMESTAMP_FIELD_NAME] = current_timestamp()
         if ID_FIELD_NAME not in values:
+            # Add UUID suffix to prevent timestamp collisions when creating
+            # multiple messages rapidly (e.g., in add_messages or store)
+            unique_suffix = uuid4().hex[:8]
             values[ID_FIELD_NAME] = (
-                f"{values[SESSION_FIELD_NAME]}:{values[TIMESTAMP_FIELD_NAME]}"
+                f"{values[SESSION_FIELD_NAME]}:{values[TIMESTAMP_FIELD_NAME]}:{unique_suffix}"
             )
         return values
 

tests/unit/test_message_history_schema.py

@@ -3,7 +3,7 @@
 
 from redisvl.extensions.message_history.schema import ChatMessage
 from redisvl.redis.utils import array_to_buffer
-from redisvl.utils.utils import create_ulid, current_timestamp, deserialize, serialize
+from redisvl.utils.utils import create_ulid, current_timestamp, serialize
 
 
 def test_chat_message_creation():
@@ -41,7 +41,13 @@ def test_chat_message_default_id_generation():
         timestamp=timestamp,
     )
 
-    assert chat_message.entry_id == f"{session_tag}:{timestamp}"
+    # ID should start with session:timestamp and have a UUID suffix for uniqueness
+    assert chat_message.entry_id.startswith(f"{session_tag}:{timestamp}:")
+    # Verify the UUID suffix is 8 hex characters
+    parts = chat_message.entry_id.split(":")
+    assert len(parts) == 3
+    assert len(parts[2]) == 8
+    assert all(c in "0123456789abcdef" for c in parts[2])
 
 
 def test_chat_message_with_tool_call_id():
@@ -164,3 +170,29 @@ def test_chat_message_invalid_role():
             session_tag=session_tag,
             timestamp=timestamp,
         )
+
+
+def test_chat_message_unique_ids_for_rapid_creation():
+    """Test that rapidly created messages get unique IDs even with same timestamp."""
+    session_tag = create_ulid()
+    timestamp = current_timestamp()
+
+    # Create multiple messages with the same session and timestamp
+    messages = []
+    for i in range(10):
+        msg = ChatMessage(
+            role="user",
+            content=f"Message {i}",
+            session_tag=session_tag,
+            timestamp=timestamp,
+        )
+        messages.append(msg)
+
+    # All IDs should be unique
+    ids = [msg.entry_id for msg in messages]
+    assert len(ids) == len(set(ids)), "All message IDs should be unique"
+
+    # All IDs should start with the same session:timestamp prefix
+    expected_prefix = f"{session_tag}:{timestamp}:"
+    for msg_id in ids:
+        assert msg_id.startswith(expected_prefix)