From 556b996208d3408931197190237cc571eb8b1ded Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Fri, 14 Aug 2026 21:26:51 +0000
Subject: [PATCH 1/2] feat(api): api update

---
 .stats.yml                                    |  4 +-
 src/supermemory/_client.py                    | 16 ++++++
 src/supermemory/resources/documents.py        | 52 +++++++++++++++++++
 src/supermemory/types/client_add_params.py    |  9 ++++
 src/supermemory/types/document_add_params.py  |  9 ++++
 .../types/document_batch_add_params.py        | 20 +++++++
 .../types/document_update_params.py           | 10 ++++
 tests/api_resources/test_client.py            |  2 +
 tests/api_resources/test_documents.py         |  8 +++
 9 files changed, 128 insertions(+), 2 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index 54c6b10..b8afe25 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 26
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/supermemory--inc/supermemory-new-5ad0e09495301abdcb7a5a63738ce5841248518504e122003219230ef35ed439.yml
-openapi_spec_hash: 6462e423d826118caba0292cd5956178
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/supermemory--inc/supermemory-new-4bec4aac7a4fd11299c105dd60bc086c0aaf51d5cd0f63075efefa56bc19a67f.yml
+openapi_spec_hash: f87b9769f91d448f4eb797c37ef4d061
 config_hash: cde97ef3188581c5f4924c633ec33ddb
diff --git a/src/supermemory/_client.py b/src/supermemory/_client.py
index b6f5e0a..2cc89e4 100644
--- a/src/supermemory/_client.py
+++ b/src/supermemory/_client.py
@@ -254,6 +254,7 @@ def add(
         container_tag: str | Omit = omit,
         container_tags: SequenceNotStr[str] | Omit = omit,
         custom_id: str | Omit = omit,
+        document_date: str | Omit = omit,
         dreaming: Literal["instant", "dynamic"] | Omit = omit,
         entity_context: str | Omit = omit,
         filepath: str | Omit = omit,
@@ -280,6 +281,12 @@ def add(
           custom_id: Optional custom ID of the document. Max 100 characters, alphanumeric with
               hyphens, underscores, and dots only.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates against this instead of the ingestion time, and documents in a
+              batch are processed oldest-first so newer facts correctly supersede older ones.
+              Set this whenever you backfill historical content.
+
           dreaming: Processing mode. "dynamic" (default) groups related documents together so
               memories form from coherent, logical units rather than one isolated entry at a
               time. "instant" processes each document on its own right away, and bills one
@@ -315,6 +322,7 @@ def add(
                     "container_tag": container_tag,
                     "container_tags": container_tags,
                     "custom_id": custom_id,
+                    "document_date": document_date,
                     "dreaming": dreaming,
                     "entity_context": entity_context,
                     "filepath": filepath,
@@ -611,6 +619,7 @@ async def add(
         container_tag: str | Omit = omit,
         container_tags: SequenceNotStr[str] | Omit = omit,
         custom_id: str | Omit = omit,
+        document_date: str | Omit = omit,
         dreaming: Literal["instant", "dynamic"] | Omit = omit,
         entity_context: str | Omit = omit,
         filepath: str | Omit = omit,
@@ -637,6 +646,12 @@ async def add(
           custom_id: Optional custom ID of the document. Max 100 characters, alphanumeric with
               hyphens, underscores, and dots only.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates against this instead of the ingestion time, and documents in a
+              batch are processed oldest-first so newer facts correctly supersede older ones.
+              Set this whenever you backfill historical content.
+
           dreaming: Processing mode. "dynamic" (default) groups related documents together so
               memories form from coherent, logical units rather than one isolated entry at a
               time. "instant" processes each document on its own right away, and bills one
@@ -672,6 +687,7 @@ async def add(
                     "container_tag": container_tag,
                     "container_tags": container_tags,
                     "custom_id": custom_id,
+                    "document_date": document_date,
                     "dreaming": dreaming,
                     "entity_context": entity_context,
                     "filepath": filepath,
diff --git a/src/supermemory/resources/documents.py b/src/supermemory/resources/documents.py
index e87c339..10a0e40 100644
--- a/src/supermemory/resources/documents.py
+++ b/src/supermemory/resources/documents.py
@@ -67,6 +67,7 @@ def update(
         container_tags: SequenceNotStr[str] | Omit = omit,
         content: str | Omit = omit,
         custom_id: str | Omit = omit,
+        document_date: str | Omit = omit,
         filepath: str | Omit = omit,
         filter_by_metadata: Dict[str, Union[str, float, bool, SequenceNotStr[str]]] | Omit = omit,
         metadata: Dict[str, Union[str, float, bool, SequenceNotStr[str]]] | Omit = omit,
@@ -102,6 +103,13 @@ def update(
           custom_id: Optional custom ID of the document. This could be an ID from your database that
               will uniquely identify this document.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates ('yesterday', 'last quarter') against this instead of the
+              ingestion time, and documents in a batch are processed oldest-first so newer
+              facts correctly supersede older ones. Set this whenever you backfill historical
+              content.
+
           filepath: Optional file path for the document (e.g., '/documents/reports/file.pdf'). Used
               by supermemoryfs to map documents to filesystem paths.
 
@@ -137,6 +145,7 @@ def update(
                     "container_tags": container_tags,
                     "content": content,
                     "custom_id": custom_id,
+                    "document_date": document_date,
                     "filepath": filepath,
                     "filter_by_metadata": filter_by_metadata,
                     "metadata": metadata,
@@ -262,6 +271,7 @@ def add(
         container_tag: str | Omit = omit,
         container_tags: SequenceNotStr[str] | Omit = omit,
         custom_id: str | Omit = omit,
+        document_date: str | Omit = omit,
         dreaming: Literal["instant", "dynamic"] | Omit = omit,
         entity_context: str | Omit = omit,
         filepath: str | Omit = omit,
@@ -288,6 +298,12 @@ def add(
           custom_id: Optional custom ID of the document. Max 100 characters, alphanumeric with
               hyphens, underscores, and dots only.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates against this instead of the ingestion time, and documents in a
+              batch are processed oldest-first so newer facts correctly supersede older ones.
+              Set this whenever you backfill historical content.
+
           dreaming: Processing mode. "dynamic" (default) groups related documents together so
               memories form from coherent, logical units rather than one isolated entry at a
               time. "instant" processes each document on its own right away, and bills one
@@ -323,6 +339,7 @@ def add(
                     "container_tag": container_tag,
                     "container_tags": container_tags,
                     "custom_id": custom_id,
+                    "document_date": document_date,
                     "dreaming": dreaming,
                     "entity_context": entity_context,
                     "filepath": filepath,
@@ -345,6 +362,7 @@ def batch_add(
         container_tag: str | Omit = omit,
         container_tags: SequenceNotStr[str] | Omit = omit,
         content: None | Omit = omit,
+        document_date: str | Omit = omit,
         dreaming: Literal["instant", "dynamic"] | Omit = omit,
         entity_context: str | Omit = omit,
         filepath: str | Omit = omit,
@@ -372,6 +390,13 @@ def batch_add(
               containerized by. This can be an ID for your user, a project ID, or any other
               identifier you wish to use to group documents.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates ('yesterday', 'last quarter') against this instead of the
+              ingestion time, and documents in a batch are processed oldest-first so newer
+              facts correctly supersede older ones. Set this whenever you backfill historical
+              content.
+
           dreaming: Processing mode. "dynamic" (default) groups related documents together so
               memories form from coherent, logical units rather than one isolated entry at a
               time. "instant" processes each document on its own right away, and bills one
@@ -413,6 +438,7 @@ def batch_add(
                     "container_tag": container_tag,
                     "container_tags": container_tags,
                     "content": content,
+                    "document_date": document_date,
                     "dreaming": dreaming,
                     "entity_context": entity_context,
                     "filepath": filepath,
@@ -670,6 +696,7 @@ async def update(
         container_tags: SequenceNotStr[str] | Omit = omit,
         content: str | Omit = omit,
         custom_id: str | Omit = omit,
+        document_date: str | Omit = omit,
         filepath: str | Omit = omit,
         filter_by_metadata: Dict[str, Union[str, float, bool, SequenceNotStr[str]]] | Omit = omit,
         metadata: Dict[str, Union[str, float, bool, SequenceNotStr[str]]] | Omit = omit,
@@ -705,6 +732,13 @@ async def update(
           custom_id: Optional custom ID of the document. This could be an ID from your database that
               will uniquely identify this document.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates ('yesterday', 'last quarter') against this instead of the
+              ingestion time, and documents in a batch are processed oldest-first so newer
+              facts correctly supersede older ones. Set this whenever you backfill historical
+              content.
+
           filepath: Optional file path for the document (e.g., '/documents/reports/file.pdf'). Used
               by supermemoryfs to map documents to filesystem paths.
 
@@ -740,6 +774,7 @@ async def update(
                     "container_tags": container_tags,
                     "content": content,
                     "custom_id": custom_id,
+                    "document_date": document_date,
                     "filepath": filepath,
                     "filter_by_metadata": filter_by_metadata,
                     "metadata": metadata,
@@ -865,6 +900,7 @@ async def add(
         container_tag: str | Omit = omit,
         container_tags: SequenceNotStr[str] | Omit = omit,
         custom_id: str | Omit = omit,
+        document_date: str | Omit = omit,
         dreaming: Literal["instant", "dynamic"] | Omit = omit,
         entity_context: str | Omit = omit,
         filepath: str | Omit = omit,
@@ -891,6 +927,12 @@ async def add(
           custom_id: Optional custom ID of the document. Max 100 characters, alphanumeric with
               hyphens, underscores, and dots only.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates against this instead of the ingestion time, and documents in a
+              batch are processed oldest-first so newer facts correctly supersede older ones.
+              Set this whenever you backfill historical content.
+
           dreaming: Processing mode. "dynamic" (default) groups related documents together so
               memories form from coherent, logical units rather than one isolated entry at a
               time. "instant" processes each document on its own right away, and bills one
@@ -926,6 +968,7 @@ async def add(
                     "container_tag": container_tag,
                     "container_tags": container_tags,
                     "custom_id": custom_id,
+                    "document_date": document_date,
                     "dreaming": dreaming,
                     "entity_context": entity_context,
                     "filepath": filepath,
@@ -948,6 +991,7 @@ async def batch_add(
         container_tag: str | Omit = omit,
         container_tags: SequenceNotStr[str] | Omit = omit,
         content: None | Omit = omit,
+        document_date: str | Omit = omit,
         dreaming: Literal["instant", "dynamic"] | Omit = omit,
         entity_context: str | Omit = omit,
         filepath: str | Omit = omit,
@@ -975,6 +1019,13 @@ async def batch_add(
               containerized by. This can be an ID for your user, a project ID, or any other
               identifier you wish to use to group documents.
 
+          document_date: When this document's content is from, as opposed to when it was uploaded.
+              Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+              relative dates ('yesterday', 'last quarter') against this instead of the
+              ingestion time, and documents in a batch are processed oldest-first so newer
+              facts correctly supersede older ones. Set this whenever you backfill historical
+              content.
+
           dreaming: Processing mode. "dynamic" (default) groups related documents together so
               memories form from coherent, logical units rather than one isolated entry at a
               time. "instant" processes each document on its own right away, and bills one
@@ -1016,6 +1067,7 @@ async def batch_add(
                     "container_tag": container_tag,
                     "container_tags": container_tags,
                     "content": content,
+                    "document_date": document_date,
                     "dreaming": dreaming,
                     "entity_context": entity_context,
                     "filepath": filepath,
diff --git a/src/supermemory/types/client_add_params.py b/src/supermemory/types/client_add_params.py
index fcdf98a..5d181a3 100644
--- a/src/supermemory/types/client_add_params.py
+++ b/src/supermemory/types/client_add_params.py
@@ -32,6 +32,15 @@ class ClientAddParams(TypedDict, total=False):
     Max 100 characters, alphanumeric with hyphens, underscores, and dots only.
     """
 
+    document_date: Annotated[str, PropertyInfo(alias="documentDate")]
+    """When this document's content is from, as opposed to when it was uploaded.
+
+    Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+    relative dates against this instead of the ingestion time, and documents in a
+    batch are processed oldest-first so newer facts correctly supersede older ones.
+    Set this whenever you backfill historical content.
+    """
+
     dreaming: Literal["instant", "dynamic"]
     """Processing mode.
 
diff --git a/src/supermemory/types/document_add_params.py b/src/supermemory/types/document_add_params.py
index b503831..48cca16 100644
--- a/src/supermemory/types/document_add_params.py
+++ b/src/supermemory/types/document_add_params.py
@@ -32,6 +32,15 @@ class DocumentAddParams(TypedDict, total=False):
     Max 100 characters, alphanumeric with hyphens, underscores, and dots only.
     """
 
+    document_date: Annotated[str, PropertyInfo(alias="documentDate")]
+    """When this document's content is from, as opposed to when it was uploaded.
+
+    Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+    relative dates against this instead of the ingestion time, and documents in a
+    batch are processed oldest-first so newer facts correctly supersede older ones.
+    Set this whenever you backfill historical content.
+    """
+
     dreaming: Literal["instant", "dynamic"]
     """Processing mode.
 
diff --git a/src/supermemory/types/document_batch_add_params.py b/src/supermemory/types/document_batch_add_params.py
index 0369f41..6afaeb6 100644
--- a/src/supermemory/types/document_batch_add_params.py
+++ b/src/supermemory/types/document_batch_add_params.py
@@ -30,6 +30,16 @@ class DocumentBatchAddParams(TypedDict, total=False):
 
     content: None
 
+    document_date: Annotated[str, PropertyInfo(alias="documentDate")]
+    """When this document's content is from, as opposed to when it was uploaded.
+
+    Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+    relative dates ('yesterday', 'last quarter') against this instead of the
+    ingestion time, and documents in a batch are processed oldest-first so newer
+    facts correctly supersede older ones. Set this whenever you backfill historical
+    content.
+    """
+
     dreaming: Literal["instant", "dynamic"]
     """Processing mode.
 
@@ -111,6 +121,16 @@ class DocumentsUnionMember0(TypedDict, total=False):
     document.
     """
 
+    document_date: Annotated[str, PropertyInfo(alias="documentDate")]
+    """When this document's content is from, as opposed to when it was uploaded.
+
+    Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+    relative dates ('yesterday', 'last quarter') against this instead of the
+    ingestion time, and documents in a batch are processed oldest-first so newer
+    facts correctly supersede older ones. Set this whenever you backfill historical
+    content.
+    """
+
     dreaming: Literal["instant", "dynamic"]
     """Processing mode.
 
diff --git a/src/supermemory/types/document_update_params.py b/src/supermemory/types/document_update_params.py
index 8437b2d..be9466a 100644
--- a/src/supermemory/types/document_update_params.py
+++ b/src/supermemory/types/document_update_params.py
@@ -45,6 +45,16 @@ class DocumentUpdateParams(TypedDict, total=False):
     document.
     """
 
+    document_date: Annotated[str, PropertyInfo(alias="documentDate")]
+    """When this document's content is from, as opposed to when it was uploaded.
+
+    Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves
+    relative dates ('yesterday', 'last quarter') against this instead of the
+    ingestion time, and documents in a batch are processed oldest-first so newer
+    facts correctly supersede older ones. Set this whenever you backfill historical
+    content.
+    """
+
     filepath: str
     """Optional file path for the document (e.g., '/documents/reports/file.pdf').
 
diff --git a/tests/api_resources/test_client.py b/tests/api_resources/test_client.py
index 4af3e8c..171a215 100644
--- a/tests/api_resources/test_client.py
+++ b/tests/api_resources/test_client.py
@@ -33,6 +33,7 @@ def test_method_add_with_all_params(self, client: Supermemory) -> None:
             container_tag="containerTag",
             container_tags=["string"],
             custom_id="customId",
+            document_date="documentDate",
             dreaming="instant",
             entity_context="entityContext",
             filepath="filepath",
@@ -148,6 +149,7 @@ async def test_method_add_with_all_params(self, async_client: AsyncSupermemory)
             container_tag="containerTag",
             container_tags=["string"],
             custom_id="customId",
+            document_date="documentDate",
             dreaming="instant",
             entity_context="entityContext",
             filepath="filepath",
diff --git a/tests/api_resources/test_documents.py b/tests/api_resources/test_documents.py
index bd1290d..2c9e36e 100644
--- a/tests/api_resources/test_documents.py
+++ b/tests/api_resources/test_documents.py
@@ -43,6 +43,7 @@ def test_method_update_with_all_params(self, client: Supermemory) -> None:
             container_tags=["_:_k--W2K_1V"],
             content="Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s.",
             custom_id="doc-api-rate-limits",
+            document_date="2025-03-14",
             filepath="/documents/reports/file.pdf",
             filter_by_metadata={
                 "department": "engineering",
@@ -210,6 +211,7 @@ def test_method_add_with_all_params(self, client: Supermemory) -> None:
             container_tag="containerTag",
             container_tags=["string"],
             custom_id="customId",
+            document_date="documentDate",
             dreaming="instant",
             entity_context="entityContext",
             filepath="filepath",
@@ -267,6 +269,7 @@ def test_method_batch_add_with_all_params(self, client: Supermemory) -> None:
                     "container_tag": "user_alex",
                     "container_tags": ["_:_k--W2K_1V"],
                     "custom_id": "doc-api-rate-limits",
+                    "document_date": "2025-03-14",
                     "dreaming": "instant",
                     "entity_context": "User's name is {XYZ}",
                     "filepath": "/documents/reports/file.pdf",
@@ -284,6 +287,7 @@ def test_method_batch_add_with_all_params(self, client: Supermemory) -> None:
             container_tag="user_alex",
             container_tags=["_:_k--W2K_1V"],
             content=None,
+            document_date="2025-03-14",
             dreaming="instant",
             entity_context="User's name is {XYZ}",
             filepath="/documents/reports/file.pdf",
@@ -518,6 +522,7 @@ async def test_method_update_with_all_params(self, async_client: AsyncSupermemor
             container_tags=["_:_k--W2K_1V"],
             content="Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s.",
             custom_id="doc-api-rate-limits",
+            document_date="2025-03-14",
             filepath="/documents/reports/file.pdf",
             filter_by_metadata={
                 "department": "engineering",
@@ -685,6 +690,7 @@ async def test_method_add_with_all_params(self, async_client: AsyncSupermemory)
             container_tag="containerTag",
             container_tags=["string"],
             custom_id="customId",
+            document_date="documentDate",
             dreaming="instant",
             entity_context="entityContext",
             filepath="filepath",
@@ -742,6 +748,7 @@ async def test_method_batch_add_with_all_params(self, async_client: AsyncSuperme
                     "container_tag": "user_alex",
                     "container_tags": ["_:_k--W2K_1V"],
                     "custom_id": "doc-api-rate-limits",
+                    "document_date": "2025-03-14",
                     "dreaming": "instant",
                     "entity_context": "User's name is {XYZ}",
                     "filepath": "/documents/reports/file.pdf",
@@ -759,6 +766,7 @@ async def test_method_batch_add_with_all_params(self, async_client: AsyncSuperme
             container_tag="user_alex",
             container_tags=["_:_k--W2K_1V"],
             content=None,
+            document_date="2025-03-14",
             dreaming="instant",
             entity_context="User's name is {XYZ}",
             filepath="/documents/reports/file.pdf",

From 9d1f3f69492f802c96e5d8c4a3573f0c644b6075 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Fri, 14 Aug 2026 21:27:18 +0000
Subject: [PATCH 2/2] release: 3.59.0

---
 .release-please-manifest.json | 2 +-
 CHANGELOG.md                  | 8 ++++++++
 pyproject.toml                | 2 +-
 src/supermemory/_version.py   | 2 +-
 4 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 15a42fa..bcab5a6 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "3.58.0"
+  ".": "3.59.0"
 }
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index db9b569..bdc872d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 3.59.0 (2026-08-14)
+
+Full Changelog: [v3.58.0...v3.59.0](https://github.com/supermemoryai/python-sdk/compare/v3.58.0...v3.59.0)
+
+### Features
+
+* **api:** api update ([556b996](https://github.com/supermemoryai/python-sdk/commit/556b996208d3408931197190237cc571eb8b1ded))
+
 ## 3.58.0 (2026-08-14)
 
 Full Changelog: [v3.57.0...v3.58.0](https://github.com/supermemoryai/python-sdk/compare/v3.57.0...v3.58.0)
diff --git a/pyproject.toml b/pyproject.toml
index 22ea14d..f5c444e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "supermemory"
-version = "3.58.0"
+version = "3.59.0"
 description = "The official Python library for the supermemory API"
 dynamic = ["readme"]
 license = "Apache-2.0"
diff --git a/src/supermemory/_version.py b/src/supermemory/_version.py
index 135daef..85202d3 100644
--- a/src/supermemory/_version.py
+++ b/src/supermemory/_version.py
@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "supermemory"
-__version__ = "3.58.0"  # x-release-please-version
+__version__ = "3.59.0"  # x-release-please-version