feat: Add memory_verbose flag to provide visibility into memory operations (#2858)

Co-Authored-By: Joe Moura <joao@crewai.com>

src/crewai/crew.py

@@ -113,6 +113,10 @@ class Crew(BaseModel):
         default=False,
         description="Whether the crew should use memory to store memories of it's execution",
     )
+    memory_verbose: bool = Field(
+        default=False,
+        description="Whether to show verbose logs about memory operations",
+    )
     memory_config: Optional[Dict[str, Any]] = Field(
         default=None,
         description="Configuration for the memory to be used for the crew.",
@@ -257,7 +261,7 @@ class Crew(BaseModel):
         """Set private attributes."""
         if self.memory:
             self._long_term_memory = (
-                self.long_term_memory if self.long_term_memory else LongTermMemory()
+                self.long_term_memory if self.long_term_memory else LongTermMemory(memory_verbose=self.memory_verbose)
             )
             self._short_term_memory = (
                 self.short_term_memory
@@ -265,16 +269,17 @@ class Crew(BaseModel):
                 else ShortTermMemory(
                     crew=self,
                     embedder_config=self.embedder,
+                    memory_verbose=self.memory_verbose,
                 )
             )
             self._entity_memory = (
                 self.entity_memory
                 if self.entity_memory
-                else EntityMemory(crew=self, embedder_config=self.embedder)
+                else EntityMemory(crew=self, embedder_config=self.embedder, memory_verbose=self.memory_verbose)
             )
             if hasattr(self, "memory_config") and self.memory_config is not None:
                 self._user_memory = (
-                    self.user_memory if self.user_memory else UserMemory(crew=self)
+                    self.user_memory if self.user_memory else UserMemory(crew=self, memory_verbose=self.memory_verbose)
                 )
             else:
                 self._user_memory = None

src/crewai/memory/entity/entity_memory.py

@@ -10,7 +10,7 @@ class EntityMemory(Memory):
     Inherits from the Memory class.
     """
 
-    def __init__(self, crew=None, embedder_config=None, storage=None, path=None):
+    def __init__(self, crew=None, embedder_config=None, storage=None, path=None, memory_verbose=False):
         if hasattr(crew, "memory_config") and crew.memory_config is not None:
             self.memory_provider = crew.memory_config.get("provider")
         else:
@@ -36,10 +36,15 @@ class EntityMemory(Memory):
                     path=path,
                 )
             )
-        super().__init__(storage)
+        super().__init__(storage, memory_verbose=memory_verbose)
 
     def save(self, item: EntityMemoryItem) -> None:  # type: ignore # BUG?: Signature of "save" incompatible with supertype "Memory"
         """Saves an entity item into the SQLite storage."""
+        if self.memory_verbose:
+            memory_type = self.__class__.__name__
+            self._logger.log("info", f"{memory_type}: Saving entity: {item.name} ({item.type})", color="cyan")
+            self._logger.log("info", f"{memory_type}: Description: {item.description[:100]}{'...' if len(item.description) > 100 else ''}", color="cyan")
+            
         if self.memory_provider == "mem0":
             data = f"""
             Remember details about the following entity:

src/crewai/memory/long_term/long_term_memory.py

@@ -14,12 +14,18 @@ class LongTermMemory(Memory):
     LongTermMemoryItem instances.
     """
 
-    def __init__(self, storage=None, path=None):
+    def __init__(self, storage=None, path=None, memory_verbose=False):
         if not storage:
             storage = LTMSQLiteStorage(db_path=path) if path else LTMSQLiteStorage()
-        super().__init__(storage)
+        super().__init__(storage, memory_verbose=memory_verbose)
 
     def save(self, item: LongTermMemoryItem) -> None:  # type: ignore # BUG?: Signature of "save" incompatible with supertype "Memory"
+        if self.memory_verbose:
+            memory_type = self.__class__.__name__
+            self._logger.log("info", f"{memory_type}: Saving task: {item.task[:100]}{'...' if len(item.task) > 100 else ''}", color="cyan")
+            self._logger.log("info", f"{memory_type}: Agent: {item.agent}", color="cyan")
+            self._logger.log("info", f"{memory_type}: Quality: {item.metadata.get('quality')}", color="cyan")
+            
         metadata = item.metadata
         metadata.update({"agent": item.agent, "expected_output": item.expected_output})
         self.storage.save(  # type: ignore # BUG?: Unexpected keyword argument "task_description","score","datetime" for "save" of "Storage"

src/crewai/memory/memory.py

@@ -1,6 +1,7 @@
 from typing import Any, Dict, List, Optional
 
 from crewai.memory.storage.rag_storage import RAGStorage
+from crewai.utilities.logger import Logger
 
 
 class Memory:
@@ -8,8 +9,10 @@ class Memory:
     Base class for memory, now supporting agent tags and generic metadata.
     """
 
-    def __init__(self, storage: RAGStorage):
+    def __init__(self, storage: RAGStorage, memory_verbose: bool = False):
         self.storage = storage
+        self.memory_verbose = memory_verbose
+        self._logger = Logger(verbose=memory_verbose)
 
     def save(
         self,
@@ -20,6 +23,11 @@ class Memory:
         metadata = metadata or {}
         if agent:
             metadata["agent"] = agent
+        
+        if self.memory_verbose:
+            memory_type = self.__class__.__name__
+            agent_info = f" from agent '{agent}'" if agent else ""
+            self._logger.log("info", f"{memory_type}: Saving{agent_info}: {value[:100]}{'...' if len(str(value)) > 100 else ''}", color="cyan")
 
         self.storage.save(value, metadata)
 
@@ -29,6 +37,15 @@ class Memory:
         limit: int = 3,
         score_threshold: float = 0.35,
     ) -> List[Any]:
-        return self.storage.search(
+        if self.memory_verbose:
+            memory_type = self.__class__.__name__
+            self._logger.log("info", f"{memory_type}: Searching for: {query}", color="cyan")
+            
+        results = self.storage.search(
             query=query, limit=limit, score_threshold=score_threshold
         )
+        
+        if self.memory_verbose and results:
+            self._logger.log("info", f"{memory_type}: Found {len(results)} results", color="cyan")
+            
+        return results

src/crewai/memory/short_term/short_term_memory.py

@@ -14,7 +14,7 @@ class ShortTermMemory(Memory):
     MemoryItem instances.
     """
 
-    def __init__(self, crew=None, embedder_config=None, storage=None, path=None):
+    def __init__(self, crew=None, embedder_config=None, storage=None, path=None, memory_verbose=False):
         if hasattr(crew, "memory_config") and crew.memory_config is not None:
             self.memory_provider = crew.memory_config.get("provider")
         else:
@@ -39,7 +39,7 @@ class ShortTermMemory(Memory):
                     path=path,
                 )
             )
-        super().__init__(storage)
+        super().__init__(storage, memory_verbose=memory_verbose)
 
     def save(
         self,

src/crewai/memory/user/user_memory.py

@@ -11,7 +11,7 @@ class UserMemory(Memory):
     MemoryItem instances.
     """
 
-    def __init__(self, crew=None):
+    def __init__(self, crew=None, memory_verbose=False):
         try:
             from crewai.memory.storage.mem0_storage import Mem0Storage
         except ImportError:
@@ -19,7 +19,7 @@ class UserMemory(Memory):
                 "Mem0 is not installed. Please install it with `pip install mem0ai`."
             )
         storage = Mem0Storage(type="user", crew=crew)
-        super().__init__(storage)
+        super().__init__(storage, memory_verbose=memory_verbose)
 
     def save(
         self,

tests/memory_verbose_test.py

@@ -0,0 +1,122 @@
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from crewai.agent import Agent
+from crewai.crew import Crew
+from crewai.memory.memory import Memory
+from crewai.memory.short_term.short_term_memory import ShortTermMemory
+from crewai.memory.short_term.short_term_memory_item import ShortTermMemoryItem
+from crewai.task import Task
+from crewai.utilities.logger import Logger
+
+
+def test_memory_verbose_flag_in_crew():
+    """Test that memory_verbose flag is correctly set in Crew"""
+    agent = Agent(
+        role="Researcher",
+        goal="Research goal",
+        backstory="Researcher backstory",
+    )
+    task = Task(
+        description="Test task",
+        expected_output="Test output",
+        agent=agent,
+    )
+    crew = Crew(agents=[agent], tasks=[task], memory=True, memory_verbose=True)
+    assert crew.memory_verbose is True
+
+
+def test_memory_verbose_logging_in_memory():
+    """Test that memory operations are logged when memory_verbose is enabled"""
+    storage = MagicMock()
+    
+    mock_logger = MagicMock(spec=Logger)
+    
+    memory = Memory(storage=storage, memory_verbose=True)
+    
+    memory._logger = mock_logger
+    
+    memory.save("test value", {"test": "metadata"}, "test_agent")
+    mock_logger.log.assert_called_once()
+    args = mock_logger.log.call_args[0]
+    assert args[0] == "info"
+    assert "Saving" in args[1]
+    
+    mock_logger.log.reset_mock()
+    memory.search("test query")
+    assert mock_logger.log.call_count == 2
+    first_call_args = mock_logger.log.call_args_list[0][0]
+    assert first_call_args[0] == "info"
+    assert "Searching" in first_call_args[1]
+    second_call_args = mock_logger.log.call_args_list[1][0]
+    assert "Found" in second_call_args[1]
+
+
+def test_no_logging_when_memory_verbose_disabled():
+    """Test that no logging occurs when memory_verbose is disabled"""
+    storage = MagicMock()
+    
+    mock_logger = MagicMock(spec=Logger)
+    
+    memory = Memory(storage=storage, memory_verbose=False)
+    
+    memory._logger = mock_logger
+    
+    memory.save("test value", {"test": "metadata"}, "test_agent")
+    mock_logger.log.assert_not_called()
+    
+    memory.search("test query")
+    mock_logger.log.assert_not_called()
+
+
+def test_memory_verbose_in_short_term_memory():
+    """Test that memory_verbose flag is correctly passed to ShortTermMemory"""
+    with patch('crewai.memory.short_term.short_term_memory.RAGStorage') as mock_storage_class:
+        mock_storage = MagicMock()
+        mock_storage_class.return_value = mock_storage
+        
+        memory = ShortTermMemory(memory_verbose=True)
+        assert memory.memory_verbose is True
+        
+        mock_logger = MagicMock(spec=Logger)
+        memory._logger = mock_logger
+        
+        memory.save("test value", {"test": "metadata"}, "test_agent")
+        mock_logger.log.assert_called_once()
+
+
+def test_memory_verbose_passed_from_crew_to_memory():
+    """Test that memory_verbose flag is correctly passed from Crew to memory instances"""
+    with patch('crewai.crew.LongTermMemory') as mock_ltm, \
+         patch('crewai.crew.ShortTermMemory') as mock_stm, \
+         patch('crewai.crew.EntityMemory') as mock_em, \
+         patch('crewai.crew.UserMemory') as mock_um:
+        
+        mock_ltm_instance = MagicMock()
+        mock_stm_instance = MagicMock()
+        mock_em_instance = MagicMock()
+        mock_um_instance = MagicMock()
+        
+        mock_ltm.return_value = mock_ltm_instance
+        mock_stm.return_value = mock_stm_instance
+        mock_em.return_value = mock_em_instance
+        mock_um.return_value = mock_um_instance
+        
+        agent = Agent(
+            role="Researcher",
+            goal="Research goal",
+            backstory="Researcher backstory",
+        )
+        task = Task(
+            description="Test task",
+            expected_output="Test output",
+            agent=agent,
+        )
+        
+        crew = Crew(agents=[agent], tasks=[task], memory=True, memory_verbose=True, memory_config={})
+        
+        mock_ltm.assert_called_once_with(memory_verbose=True)
+        mock_stm.assert_called_with(crew=crew, embedder_config=None, memory_verbose=True)
+        mock_em.assert_called_with(crew=crew, embedder_config=None, memory_verbose=True)
+        mock_um.assert_called_with(crew=crew, memory_verbose=True)