Add count()support to message history (#517)

Changes for #495 

- Add count method to `BaseMessageHistory`, `MessageHistory`,
`SemanticMessageHistory`
- Add supporting tests to  `test_message_history.py`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds a new abstract `count()` method to `BaseMessageHistory`, which is
a small interface change that can break any downstream custom history
implementations; runtime behavior depends on Redis query counting
semantics.
> 
> **Overview**
> Adds a `count(session_tag=None)` API to both `MessageHistory` and
`SemanticMessageHistory`, implemented via `CountQuery` to return the
number of stored messages (optionally scoped to a provided
`session_tag`).
> 
> Updates integration tests to assert counts before/after `clear()`, and
extends the message history user guide notebook with a new section
demonstrating `.count()` usage.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
119f11d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: GDaamn

docs/user_guide/07_message_history.ipynb

@@ -27,7 +27,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 33,
    "metadata": {
     "execution": {
      "iopub.execute_input": "2026-02-16T15:14:26.666540Z",
@@ -55,7 +55,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 34,
    "metadata": {
     "execution": {
      "iopub.execute_input": "2026-02-16T15:14:26.853637Z",
@@ -172,7 +172,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 35,
    "metadata": {
     "execution": {
      "iopub.execute_input": "2026-02-16T15:14:26.881966Z",
@@ -370,6 +370,33 @@
     "    print(message)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Retrieving message counts\n",
+    "\n",
+    "To get the total number of  messages stored in a session, use the `.count()` method.  \n",
+    "You can optionally pass a `session_tag` argument to retrieve the count for a different conversation session."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 38,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Total messages in the session: 7\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(f\"Total messages in the session: {chat_history.count()}\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

redisvl/extensions/message_history/base_history.py

@@ -49,6 +49,15 @@ def drop(self, id_field: Optional[str] = None) -> None:
         """
         raise NotImplementedError
 
+    def count(self, session_tag: Optional[str] = None) -> int:
+        """Count the number of messages in the conversation history.
+
+        Args:
+            session_tag (Optional[str]): The session tag to filter messages by.
+                If None, counts all messages in the history.
+        """
+        raise NotImplementedError
+
     @property
     def messages(self) -> Union[List[str], List[Dict[str, str]]]:
         """Returns the full chat history."""

redisvl/extensions/message_history/message_history.py

@@ -14,7 +14,7 @@
 from redisvl.extensions.message_history import BaseMessageHistory
 from redisvl.extensions.message_history.schema import ChatMessage, MessageHistorySchema
 from redisvl.index import SearchIndex
-from redisvl.query import FilterQuery
+from redisvl.query import CountQuery, FilterQuery
 from redisvl.query.filter import Tag
 from redisvl.utils.utils import serialize
 
@@ -88,6 +88,16 @@ def drop(self, id: Optional[str] = None) -> None:
 
         self._index.client.delete(self._index.key(id))  # type: ignore
 
+    def count(self, session_tag=None):
+        query = CountQuery(
+            filter_expression=(
+                Tag(SESSION_FIELD_NAME) == session_tag
+                if session_tag
+                else self._default_session_filter
+            )
+        )
+        return self._index.query(query)
+
     @property
     def messages(self) -> Union[List[str], List[Dict[str, str]]]:
         """Returns the full message history."""

redisvl/extensions/message_history/semantic_history.py

@@ -18,7 +18,7 @@
     SemanticMessageHistorySchema,
 )
 from redisvl.index import SearchIndex
-from redisvl.query import FilterQuery, RangeQuery
+from redisvl.query import CountQuery, FilterQuery, RangeQuery
 from redisvl.query.filter import Tag
 from redisvl.utils.utils import deprecated_argument, serialize, validate_vector_dims
 from redisvl.utils.vectorize import BaseVectorizer, HFTextVectorizer
@@ -140,6 +140,16 @@ def drop(self, id: Optional[str] = None) -> None:
 
         self._index.client.delete(self._index.key(id))  # type: ignore
 
+    def count(self, session_tag=None):
+        query = CountQuery(
+            filter_expression=(
+                Tag(SESSION_FIELD_NAME) == session_tag
+                if session_tag
+                else self._default_session_filter
+            )
+        )
+        return self._index.query(query)
+
     @property
     def messages(self) -> Union[List[str], List[Dict[str, str]]]:
         """Returns the full message history."""

tests/integration/test_message_history.py

@@ -330,6 +330,13 @@ def test_standard_clear(standard_history):
     assert empty_context == []
 
 
+def test_standard_count(standard_history):
+    standard_history.store("some prompt", "some response")
+    assert standard_history.count() == 2
+    standard_history.clear()
+    assert standard_history.count() == 0
+
+
 # test semantic message history
 @requires_hf
 def test_semantic_specify_client(client, hf_vectorizer):
@@ -631,6 +638,14 @@ def test_semantic_drop(semantic_history):
     ]
 
 
+@requires_hf
+def test_semantic_count(semantic_history):
+    semantic_history.store("first prompt", "first response")
+    assert semantic_history.count() == 2
+    semantic_history.clear()
+    assert semantic_history.count() == 0
+
+
 def test_different_vector_dtypes(client, redis_url):
     skip_if_no_redisearch(client)
     try: