diff --git a/src/Progressable.php b/src/Progressable.php
index a12076c..0997237 100644
--- a/src/Progressable.php
+++ b/src/Progressable.php
@@ -428,6 +428,22 @@ public function setStatusMessage(?string $message): static {
         return $this;
     }
 
+    /**
+     * Merge metadata for this progress instance.
+     *
+     * @param  array<string, mixed>  $metadata
+     */
+    public function mergeMetadata(array $metadata): static {
+        $this->metadata = array_merge($this->metadata, $metadata);
+
+        // Update storage with new metadata if we have a unique name
+        if (isset($this->overallUniqueName)) {
+            $this->updateLocalProgressData($this->progress);
+        }
+
+        return $this;
+    }
+
     /**
      * Get the status message for this progress instance.
      */
diff --git a/tests/ProgressableTest.php b/tests/ProgressableTest.php
index 2a21740..40f5003 100644
--- a/tests/ProgressableTest.php
+++ b/tests/ProgressableTest.php
@@ -469,4 +469,20 @@ public function test_metadata_and_message_stored_together(): void {
         $this->assertEquals('Processing...', $localData['message']);
         $this->assertEquals(['step' => 1], $localData['metadata']);
     }
+
+    public function test_merge_metadata(): void {
+        $this->setOverallUniqueName('test_merge_metadata_'.$this->testId);
+        $this->setMetadata(['key1' => 'value1']);
+
+        $this->mergeMetadata(['key2' => 'value2', 'key1' => 'new_value1']);
+
+        $this->assertEquals('new_value1', $this->getMetadataValue('key1'));
+        $this->assertEquals('value2', $this->getMetadataValue('key2'));
+
+        // Verify storage
+        $progressData = $this->getOverallProgressData();
+        $storedMetadata = $progressData[$this->getLocalKey()]['metadata'];
+        $this->assertEquals('new_value1', $storedMetadata['key1']);
+        $this->assertEquals('value2', $storedMetadata['key2']);
+    }
 }