From cdee6a4ff0c0cdf1757b21c9792fe00299bb80ed Mon Sep 17 00:00:00 2001 From: Prateek Chhikara <46902268+prateekchhikara@users.noreply.github.com> Date: Wed, 18 Jun 2025 10:07:18 -0700 Subject: [PATCH] Enhance update method to support metadata (#2976) --- docs/platform/quickstart.mdx | 14 +- mem0/client/main.py | 601 +++++++++++++++++++++++++++++------ pyproject.toml | 2 +- 3 files changed, 506 insertions(+), 111 deletions(-) diff --git a/docs/platform/quickstart.mdx b/docs/platform/quickstart.mdx index 925f7fce..20b9f444 100644 --- a/docs/platform/quickstart.mdx +++ b/docs/platform/quickstart.mdx @@ -1780,24 +1780,26 @@ curl -X GET "https://api.mem0.ai/v1/memories//history/" \ ### 4.6 Update Memory -Update a memory with new data. +Update a memory with new data. You can update the memory's text, metadata, or both. ```python Python -message = "I recently tried chicken and I loved it. I'm thinking of trying more non-vegetarian dishes.." -client.update(memory_id, message) +client.update( + memory_id="", + text="I am now a vegetarian.", + metadata={"diet": "vegetarian"} +) ``` ```javascript JavaScript -const message = "I recently tried chicken and I loved it. I'm thinking of trying more non-vegetarian dishes.."; -client.update("memory-id-here", message) +client.update("memory-id-here", { text: "I am now a vegetarian.", metadata: { diet: "vegetarian" } }) .then(result => console.log(result)) .catch(error => console.error(error)); ``` ```bash cURL -curl -X PUT "https://api.mem0.ai/v1/memories/memory-id-here" \ +curl -X PUT "https://api.mem0.ai/v1/memories/" \ -H "Authorization: Token your-api-key" \ -H "Content-Type: application/json" \ -d '{ diff --git a/mem0/client/main.py b/mem0/client/main.py index e7bc245c..5aafa0de 100644 --- a/mem0/client/main.py +++ b/mem0/client/main.py @@ -45,8 +45,8 @@ def api_error_handler(func): class MemoryClient: """Client for interacting with the Mem0 API. - This class provides methods to create, retrieve, search, and delete memories - using the Mem0 API. + This class provides methods to create, retrieve, search, and delete + memories using the Mem0 API. Attributes: api_key (str): The API key for authenticating with the Mem0 API. @@ -68,13 +68,16 @@ class MemoryClient: """Initialize the MemoryClient. Args: - api_key: The API key for authenticating with the Mem0 API. If not provided, - it will attempt to use the MEM0_API_KEY environment variable. - host: The base URL for the Mem0 API. Defaults to "https://api.mem0.ai". + api_key: The API key for authenticating with the Mem0 API. If not + provided, it will attempt to use the MEM0_API_KEY + environment variable. + host: The base URL for the Mem0 API. Defaults to + "https://api.mem0.ai". org_id: The ID of the organization. project_id: The ID of the project. - client: A custom httpx.Client instance. If provided, it will be used instead of creating a new one. - Note that base_url and headers will be set/overridden as needed. + client: A custom httpx.Client instance. If provided, it will be + used instead of creating a new one. Note that base_url and + headers will be set/overridden as needed. Raises: ValueError: If no API key is provided or found in the environment. @@ -86,7 +89,9 @@ class MemoryClient: self.user_id = get_user_id() if not self.api_key: - raise ValueError("Mem0 API Key not provided. Please provide an API Key.") + raise ValueError( + "Mem0 API Key not provided. Please provide an API Key." + ) # Create MD5 hash of API key for user_id self.user_id = hashlib.md5(self.api_key.encode()).hexdigest() @@ -95,11 +100,19 @@ class MemoryClient: self.client = client # Ensure the client has the correct base_url and headers self.client.base_url = httpx.URL(self.host) - self.client.headers.update({"Authorization": f"Token {self.api_key}", "Mem0-User-ID": self.user_id}) + self.client.headers.update( + { + "Authorization": f"Token {self.api_key}", + "Mem0-User-ID": self.user_id, + } + ) else: self.client = httpx.Client( base_url=self.host, - headers={"Authorization": f"Token {self.api_key}", "Mem0-User-ID": self.user_id}, + headers={ + "Authorization": f"Token {self.api_key}", + "Mem0-User-ID": self.user_id, + }, timeout=300, ) self.user_email = self._validate_api_key() @@ -134,7 +147,8 @@ class MemoryClient: Args: messages: A list of message dictionaries. - **kwargs: Additional parameters such as user_id, agent_id, app_id, metadata, filters. + **kwargs: Additional parameters such as user_id, agent_id, app_id, + metadata, filters. Returns: A dictionary containing the API response. @@ -146,8 +160,11 @@ class MemoryClient: if kwargs.get("output_format") != "v1.1": kwargs["output_format"] = "v1.1" warnings.warn( - "output_format='v1.0' is deprecated therefore setting it to 'v1.1' by default." - "Check out the docs for more information: https://docs.mem0.ai/platform/quickstart#4-1-create-memories", + ( + "output_format='v1.0' is deprecated therefore setting it to " + "'v1.1' by default. Check out the docs for more information: " + "https://docs.mem0.ai/platform/quickstart#4-1-create-memories" + ), DeprecationWarning, stacklevel=2, ) @@ -157,7 +174,9 @@ class MemoryClient: response.raise_for_status() if "metadata" in kwargs: del kwargs["metadata"] - capture_client_event("client.add", self, {"keys": list(kwargs.keys()), "sync_type": "sync"}) + capture_client_event( + "client.add", self, {"keys": list(kwargs.keys()), "sync_type": "sync"} + ) return response.json() @api_error_handler @@ -176,7 +195,9 @@ class MemoryClient: params = self._prepare_params() response = self.client.get(f"/v1/memories/{memory_id}/", params=params) response.raise_for_status() - capture_client_event("client.get", self, {"memory_id": memory_id, "sync_type": "sync"}) + capture_client_event( + "client.get", self, {"memory_id": memory_id, "sync_type": "sync"} + ) return response.json() @api_error_handler @@ -185,7 +206,8 @@ class MemoryClient: Args: version: The API version to use for the search endpoint. - **kwargs: Optional parameters for filtering (user_id, agent_id, app_id, top_k). + **kwargs: Optional parameters for filtering (user_id, agent_id, + app_id, top_k). Returns: A list of dictionaries containing memories. @@ -198,28 +220,42 @@ class MemoryClient: response = self.client.get(f"/{version}/memories/", params=params) elif version == "v2": if "page" in params and "page_size" in params: - query_params = {"page": params.pop("page"), "page_size": params.pop("page_size")} - response = self.client.post(f"/{version}/memories/", json=params, params=query_params) + query_params = { + "page": params.pop("page"), + "page_size": params.pop("page_size"), + } + response = self.client.post( + f"/{version}/memories/", json=params, params=query_params + ) else: - response = self.client.post(f"/{version}/memories/", json=params) + response = self.client.post( + f"/{version}/memories/", json=params + ) response.raise_for_status() if "metadata" in kwargs: del kwargs["metadata"] capture_client_event( "client.get_all", self, - {"api_version": version, "keys": list(kwargs.keys()), "sync_type": "sync"}, + { + "api_version": version, + "keys": list(kwargs.keys()), + "sync_type": "sync", + }, ) return response.json() @api_error_handler - def search(self, query: str, version: str = "v1", **kwargs) -> List[Dict[str, Any]]: + def search( + self, query: str, version: str = "v1", **kwargs + ) -> List[Dict[str, Any]]: """Search memories based on a query. Args: query: The search query string. version: The API version to use for the search endpoint. - **kwargs: Additional parameters such as user_id, agent_id, app_id, top_k, filters. + **kwargs: Additional parameters such as user_id, agent_id, app_id, + top_k, filters. Returns: A list of dictionaries containing search results. @@ -230,28 +266,55 @@ class MemoryClient: payload = {"query": query} params = self._prepare_params(kwargs) payload.update(params) - response = self.client.post(f"/{version}/memories/search/", json=payload) + response = self.client.post( + f"/{version}/memories/search/", json=payload + ) response.raise_for_status() if "metadata" in kwargs: del kwargs["metadata"] capture_client_event( - "client.search", self, {"api_version": version, "keys": list(kwargs.keys()), "sync_type": "sync"} + "client.search", + self, + { + "api_version": version, + "keys": list(kwargs.keys()), + "sync_type": "sync", + }, ) return response.json() @api_error_handler - def update(self, memory_id: str, data: str) -> Dict[str, Any]: + def update( + self, + memory_id: str, + text: Optional[str] = None, + metadata: Optional[Dict[str, Any]] = None, + ) -> Dict[str, Any]: """ Update a memory by ID. Args: memory_id (str): Memory ID. - data (str): Data to update in the memory. + text (str, optional): Data to update in the memory. + metadata (dict, optional): Metadata to update in the memory. Returns: Dict[str, Any]: The response from the server. """ - capture_client_event("client.update", self, {"memory_id": memory_id, "sync_type": "sync"}) + if text is None and metadata is None: + raise ValueError("Either text or metadata must be provided for update.") + + payload = {} + if text is not None: + payload["text"] = text + if metadata is not None: + payload["metadata"] = metadata + + capture_client_event( + "client.update", self, {"memory_id": memory_id, "sync_type": "sync"} + ) params = self._prepare_params() - response = self.client.put(f"/v1/memories/{memory_id}/", json={"text": data}, params=params) + response = self.client.put( + f"/v1/memories/{memory_id}/", json=payload, params=params + ) response.raise_for_status() return response.json() @@ -269,9 +332,13 @@ class MemoryClient: APIError: If the API request fails. """ params = self._prepare_params() - response = self.client.delete(f"/v1/memories/{memory_id}/", params=params) + response = self.client.delete( + f"/v1/memories/{memory_id}/", params=params + ) response.raise_for_status() - capture_client_event("client.delete", self, {"memory_id": memory_id, "sync_type": "sync"}) + capture_client_event( + "client.delete", self, {"memory_id": memory_id, "sync_type": "sync"} + ) return response.json() @api_error_handler @@ -279,7 +346,8 @@ class MemoryClient: """Delete all memories, with optional filtering. Args: - **kwargs: Optional parameters for filtering (user_id, agent_id, app_id). + **kwargs: Optional parameters for filtering (user_id, agent_id, + app_id). Returns: A dictionary containing the API response. @@ -290,7 +358,11 @@ class MemoryClient: params = self._prepare_params(kwargs) response = self.client.delete("/v1/memories/", params=params) response.raise_for_status() - capture_client_event("client.delete_all", self, {"keys": list(kwargs.keys()), "sync_type": "sync"}) + capture_client_event( + "client.delete_all", + self, + {"keys": list(kwargs.keys()), "sync_type": "sync"}, + ) return response.json() @api_error_handler @@ -307,9 +379,13 @@ class MemoryClient: APIError: If the API request fails. """ params = self._prepare_params() - response = self.client.get(f"/v1/memories/{memory_id}/history/", params=params) + response = self.client.get( + f"/v1/memories/{memory_id}/history/", params=params + ) response.raise_for_status() - capture_client_event("client.history", self, {"memory_id": memory_id, "sync_type": "sync"}) + capture_client_event( + "client.history", self, {"memory_id": memory_id, "sync_type": "sync"} + ) return response.json() @api_error_handler @@ -356,7 +432,10 @@ class MemoryClient: else: entities = self.users() # Filter entities based on provided IDs using list comprehension - to_delete = [{"type": entity["type"], "name": entity["name"]} for entity in entities["results"]] + to_delete = [ + {"type": entity["type"], "name": entity["name"]} + for entity in entities["results"] + ] params = self._prepare_params() @@ -365,13 +444,21 @@ class MemoryClient: # Delete entities and check response immediately for entity in to_delete: - response = self.client.delete(f"/v2/entities/{entity['type']}/{entity['name']}/", params=params) + response = self.client.delete( + f"/v2/entities/{entity['type']}/{entity['name']}/", params=params + ) response.raise_for_status() capture_client_event( "client.delete_users", self, - {"user_id": user_id, "agent_id": agent_id, "app_id": app_id, "run_id": run_id, "sync_type": "sync"}, + { + "user_id": user_id, + "agent_id": agent_id, + "app_id": app_id, + "run_id": run_id, + "sync_type": "sync", + }, ) return { "message": "Entity deleted successfully." @@ -383,7 +470,8 @@ class MemoryClient: def reset(self) -> Dict[str, str]: """Reset the client by deleting all users and memories. - This method deletes all users, agents, sessions, and memories associated with the client. + This method deletes all users, agents, sessions, and memories + associated with the client. Returns: Dict[str, str]: Message client reset successful. @@ -396,14 +484,17 @@ class MemoryClient: self.delete_users() capture_client_event("client.reset", self, {"sync_type": "sync"}) - return {"message": "Client reset successful. All users and memories deleted."} + return { + "message": "Client reset successful. All users and memories deleted." + } @api_error_handler def batch_update(self, memories: List[Dict[str, Any]]) -> Dict[str, Any]: """Batch update memories. Args: - memories: List of memory dictionaries to update. Each dictionary must contain: + memories: List of memory dictionaries to update. Each dictionary + must contain: - memory_id (str): ID of the memory to update - text (str): New text content for the memory @@ -416,7 +507,9 @@ class MemoryClient: response = self.client.put("/v1/batch/", json={"memories": memories}) response.raise_for_status() - capture_client_event("client.batch_update", self, {"sync_type": "sync"}) + capture_client_event( + "client.batch_update", self, {"sync_type": "sync"} + ) return response.json() @api_error_handler @@ -424,7 +517,8 @@ class MemoryClient: """Batch delete memories. Args: - memories: List of memory dictionaries to delete. Each dictionary must contain: + memories: List of memory dictionaries to delete. Each dictionary + must contain: - memory_id (str): ID of the memory to delete Returns: @@ -433,10 +527,14 @@ class MemoryClient: Raises: APIError: If the API request fails. """ - response = self.client.request("DELETE", "/v1/batch/", json={"memories": memories}) + response = self.client.request( + "DELETE", "/v1/batch/", json={"memories": memories} + ) response.raise_for_status() - capture_client_event("client.batch_delete", self, {"sync_type": "sync"}) + capture_client_event( + "client.batch_delete", self, {"sync_type": "sync"} + ) return response.json() @api_error_handler @@ -450,10 +548,19 @@ class MemoryClient: Returns: Dict containing export request ID and status message """ - response = self.client.post("/v1/exports/", json={"schema": schema, **self._prepare_params(kwargs)}) + response = self.client.post( + "/v1/exports/", + json={"schema": schema, **self._prepare_params(kwargs)}, + ) response.raise_for_status() capture_client_event( - "client.create_memory_export", self, {"schema": schema, "keys": list(kwargs.keys()), "sync_type": "sync"} + "client.create_memory_export", + self, + { + "schema": schema, + "keys": list(kwargs.keys()), + "sync_type": "sync", + }, ) return response.json() @@ -467,13 +574,21 @@ class MemoryClient: Returns: Dict containing the exported data """ - response = self.client.post("/v1/exports/get/", json=self._prepare_params(kwargs)) + response = self.client.post( + "/v1/exports/get/", json=self._prepare_params(kwargs) + ) response.raise_for_status() - capture_client_event("client.get_memory_export", self, {"keys": list(kwargs.keys()), "sync_type": "sync"}) + capture_client_event( + "client.get_memory_export", + self, + {"keys": list(kwargs.keys()), "sync_type": "sync"}, + ) return response.json() @api_error_handler - def get_summary(self, filters: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: + def get_summary( + self, filters: Optional[Dict[str, Any]] = None + ) -> Dict[str, Any]: """Get the summary of a memory export. Args: @@ -483,13 +598,17 @@ class MemoryClient: Dict containing the export status and summary data """ - response = self.client.post("/v1/summary/", json=self._prepare_params({"filters": filters})) + response = self.client.post( + "/v1/summary/", json=self._prepare_params({"filters": filters}) + ) response.raise_for_status() capture_client_event("client.get_summary", self, {"sync_type": "sync"}) return response.json() @api_error_handler - def get_project(self, fields: Optional[List[str]] = None) -> Dict[str, Any]: + def get_project( + self, fields: Optional[List[str]] = None + ) -> Dict[str, Any]: """Get instructions or categories for the current project. Args: @@ -503,7 +622,10 @@ class MemoryClient: ValueError: If org_id or project_id are not set. """ if not (self.org_id and self.project_id): - raise ValueError("org_id and project_id must be set to access instructions or categories") + raise ValueError( + "org_id and project_id must be set to access instructions or " + "categories" + ) params = self._prepare_params({"fields": fields}) response = self.client.get( @@ -511,7 +633,11 @@ class MemoryClient: params=params, ) response.raise_for_status() - capture_client_event("client.get_project_details", self, {"fields": fields, "sync_type": "sync"}) + capture_client_event( + "client.get_project_details", + self, + {"fields": fields, "sync_type": "sync"}, + ) return response.json() @api_error_handler @@ -540,7 +666,10 @@ class MemoryClient: ValueError: If org_id or project_id are not set. """ if not (self.org_id and self.project_id): - raise ValueError("org_id and project_id must be set to update instructions or categories") + raise ValueError( + "org_id and project_id must be set to update instructions or " + "categories" + ) if ( custom_instructions is None @@ -550,7 +679,9 @@ class MemoryClient: and version is None ): raise ValueError( - "Currently we only support updating custom_instructions or custom_categories or retrieval_criteria, so you must provide at least one of them" + "Currently we only support updating custom_instructions or " + "custom_categories or retrieval_criteria, so you must " + "provide at least one of them" ) payload = self._prepare_params( @@ -677,27 +808,45 @@ class MemoryClient: response = self.client.delete(f"api/v1/webhooks/{webhook_id}/") response.raise_for_status() - capture_client_event("client.delete_webhook", self, {"webhook_id": webhook_id, "sync_type": "sync"}) + capture_client_event( + "client.delete_webhook", + self, + {"webhook_id": webhook_id, "sync_type": "sync"}, + ) return response.json() @api_error_handler def feedback( - self, memory_id: str, feedback: Optional[str] = None, feedback_reason: Optional[str] = None + self, + memory_id: str, + feedback: Optional[str] = None, + feedback_reason: Optional[str] = None, ) -> Dict[str, str]: VALID_FEEDBACK_VALUES = {"POSITIVE", "NEGATIVE", "VERY_NEGATIVE"} feedback = feedback.upper() if feedback else None if feedback is not None and feedback not in VALID_FEEDBACK_VALUES: - raise ValueError(f'feedback must be one of {", ".join(VALID_FEEDBACK_VALUES)} or None') + raise ValueError( + f'feedback must be one of {", ".join(VALID_FEEDBACK_VALUES)} ' + "or None" + ) - data = {"memory_id": memory_id, "feedback": feedback, "feedback_reason": feedback_reason} + data = { + "memory_id": memory_id, + "feedback": feedback, + "feedback_reason": feedback_reason, + } response = self.client.post("/v1/feedback/", json=data) response.raise_for_status() - capture_client_event("client.feedback", self, data, {"sync_type": "sync"}) + capture_client_event( + "client.feedback", self, data, {"sync_type": "sync"} + ) return response.json() - def _prepare_payload(self, messages: List[Dict[str, str]], kwargs: Dict[str, Any]) -> Dict[str, Any]: + def _prepare_payload( + self, messages: List[Dict[str, str]], kwargs: Dict[str, Any] + ) -> Dict[str, Any]: """Prepare the payload for API requests. Args: @@ -713,7 +862,9 @@ class MemoryClient: payload.update({k: v for k, v in kwargs.items() if v is not None}) return payload - def _prepare_params(self, kwargs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: + def _prepare_params( + self, kwargs: Optional[Dict[str, Any]] = None + ) -> Dict[str, Any]: """Prepare query parameters for API requests. Args: @@ -757,14 +908,16 @@ class AsyncMemoryClient: """Initialize the AsyncMemoryClient. Args: - api_key: The API key for authenticating with the Mem0 API. If not provided, - it will attempt to use the MEM0_API_KEY environment variable. - host: The base URL for the Mem0 API. Defaults to "https://api.mem0.ai". + api_key: The API key for authenticating with the Mem0 API. If not + provided, it will attempt to use the MEM0_API_KEY + environment variable. + host: The base URL for the Mem0 API. Defaults to + "https://api.mem0.ai". org_id: The ID of the organization. project_id: The ID of the project. - client: A custom httpx.AsyncClient instance. If provided, it will be used instead - of creating a new one. Note that base_url and headers will be set/overridden - as needed. + client: A custom httpx.AsyncClient instance. If provided, it will + be used instead of creating a new one. Note that base_url + and headers will be set/overridden as needed. Raises: ValueError: If no API key is provided or found in the environment. @@ -776,7 +929,9 @@ class AsyncMemoryClient: self.user_id = get_user_id() if not self.api_key: - raise ValueError("Mem0 API Key not provided. Please provide an API Key.") + raise ValueError( + "Mem0 API Key not provided. Please provide an API Key." + ) # Create MD5 hash of API key for user_id self.user_id = hashlib.md5(self.api_key.encode()).hexdigest() @@ -785,11 +940,19 @@ class AsyncMemoryClient: self.async_client = client # Ensure the client has the correct base_url and headers self.async_client.base_url = httpx.URL(self.host) - self.async_client.headers.update({"Authorization": f"Token {self.api_key}", "Mem0-User-ID": self.user_id}) + self.async_client.headers.update( + { + "Authorization": f"Token {self.api_key}", + "Mem0-User-ID": self.user_id, + } + ) else: self.async_client = httpx.AsyncClient( base_url=self.host, - headers={"Authorization": f"Token {self.api_key}", "Mem0-User-ID": self.user_id}, + headers={ + "Authorization": f"Token {self.api_key}", + "Mem0-User-ID": self.user_id, + }, timeout=300, ) @@ -802,7 +965,10 @@ class AsyncMemoryClient: params = self._prepare_params() response = requests.get( f"{self.host}/v1/ping/", - headers={"Authorization": f"Token {self.api_key}", "Mem0-User-ID": self.user_id}, + headers={ + "Authorization": f"Token {self.api_key}", + "Mem0-User-ID": self.user_id, + }, params=params, ) data = response.json() @@ -823,7 +989,9 @@ class AsyncMemoryClient: error_message = str(e) raise ValueError(f"Error: {error_message}") - def _prepare_payload(self, messages: List[Dict[str, str]], kwargs: Dict[str, Any]) -> Dict[str, Any]: + def _prepare_payload( + self, messages: List[Dict[str, str]], kwargs: Dict[str, Any] + ) -> Dict[str, Any]: """Prepare the payload for API requests. Args: @@ -839,7 +1007,9 @@ class AsyncMemoryClient: payload.update({k: v for k, v in kwargs.items() if v is not None}) return payload - def _prepare_params(self, kwargs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: + def _prepare_params( + self, kwargs: Optional[Dict[str, Any]] = None + ) -> Dict[str, Any]: """Prepare query parameters for API requests. Args: @@ -871,13 +1041,18 @@ class AsyncMemoryClient: await self.async_client.aclose() @api_error_handler - async def add(self, messages: List[Dict[str, str]], **kwargs) -> Dict[str, Any]: + async def add( + self, messages: List[Dict[str, str]], **kwargs + ) -> Dict[str, Any]: kwargs = self._prepare_params(kwargs) if kwargs.get("output_format") != "v1.1": kwargs["output_format"] = "v1.1" warnings.warn( - "output_format='v1.0' is deprecated therefore setting it to 'v1.1' by default." - "Check out the docs for more information: https://docs.mem0.ai/platform/quickstart#4-1-create-memories", + ( + "output_format='v1.0' is deprecated therefore setting it to " + "'v1.1' by default. Check out the docs for more information: " + "https://docs.mem0.ai/platform/quickstart#4-1-create-memories" + ), DeprecationWarning, stacklevel=2, ) @@ -887,59 +1062,121 @@ class AsyncMemoryClient: response.raise_for_status() if "metadata" in kwargs: del kwargs["metadata"] - capture_client_event("client.add", self, {"keys": list(kwargs.keys()), "sync_type": "async"}) + capture_client_event( + "client.add", self, {"keys": list(kwargs.keys()), "sync_type": "async"} + ) return response.json() @api_error_handler async def get(self, memory_id: str) -> Dict[str, Any]: params = self._prepare_params() - response = await self.async_client.get(f"/v1/memories/{memory_id}/", params=params) + response = await self.async_client.get( + f"/v1/memories/{memory_id}/", params=params + ) response.raise_for_status() - capture_client_event("client.get", self, {"memory_id": memory_id, "sync_type": "async"}) + capture_client_event( + "client.get", self, {"memory_id": memory_id, "sync_type": "async"} + ) return response.json() @api_error_handler - async def get_all(self, version: str = "v1", **kwargs) -> List[Dict[str, Any]]: + async def get_all( + self, version: str = "v1", **kwargs + ) -> List[Dict[str, Any]]: params = self._prepare_params(kwargs) if version == "v1": - response = await self.async_client.get(f"/{version}/memories/", params=params) + response = await self.async_client.get( + f"/{version}/memories/", params=params + ) elif version == "v2": if "page" in params and "page_size" in params: - query_params = {"page": params.pop("page"), "page_size": params.pop("page_size")} - response = await self.async_client.post(f"/{version}/memories/", json=params, params=query_params) + query_params = { + "page": params.pop("page"), + "page_size": params.pop("page_size"), + } + response = await self.async_client.post( + f"/{version}/memories/", json=params, params=query_params + ) else: - response = await self.async_client.post(f"/{version}/memories/", json=params) + response = await self.async_client.post( + f"/{version}/memories/", json=params + ) response.raise_for_status() if "metadata" in kwargs: del kwargs["metadata"] capture_client_event( - "client.get_all", self, {"api_version": version, "keys": list(kwargs.keys()), "sync_type": "async"} + "client.get_all", + self, + { + "api_version": version, + "keys": list(kwargs.keys()), + "sync_type": "async", + }, ) return response.json() @api_error_handler - async def search(self, query: str, version: str = "v1", **kwargs) -> List[Dict[str, Any]]: + async def search( + self, query: str, version: str = "v1", **kwargs + ) -> List[Dict[str, Any]]: payload = {"query": query} payload.update(self._prepare_params(kwargs)) - response = await self.async_client.post(f"/{version}/memories/search/", json=payload) + response = await self.async_client.post( + f"/{version}/memories/search/", json=payload + ) response.raise_for_status() if "metadata" in kwargs: del kwargs["metadata"] capture_client_event( - "client.search", self, {"api_version": version, "keys": list(kwargs.keys()), "sync_type": "async"} + "client.search", + self, + { + "api_version": version, + "keys": list(kwargs.keys()), + "sync_type": "async", + }, ) return response.json() @api_error_handler - async def update(self, memory_id: str, data: str) -> Dict[str, Any]: - params = self._prepare_params() - response = await self.async_client.put(f"/v1/memories/{memory_id}/", json={"text": data}, params=params) - response.raise_for_status() + async def update(self, memory_id: str, text: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: + """ + Update a memory by ID. + Args: + memory_id (str): Memory ID. + text (str, optional): Data to update in the memory. + metadata (dict, optional): Metadata to update in the memory. + Returns: + Dict[str, Any]: The response from the server. + """ + if text is None and metadata is None: + raise ValueError("Either text or metadata must be provided for update.") + + payload = {} + if text is not None: + payload["text"] = text + if metadata is not None: + payload["metadata"] = metadata + capture_client_event("client.update", self, {"memory_id": memory_id, "sync_type": "async"}) + params = self._prepare_params() + response = await self.async_client.put(f"/v1/memories/{memory_id}/", json=payload, params=params) + response.raise_for_status() return response.json() @api_error_handler async def delete(self, memory_id: str) -> Dict[str, Any]: + """Delete a specific memory by ID. + + Args: + memory_id: The ID of the memory to delete. + + Returns: + A dictionary containing the API response. + + Raises: + APIError: If the API request fails. + """ params = self._prepare_params() response = await self.async_client.delete(f"/v1/memories/{memory_id}/", params=params) response.raise_for_status() @@ -948,6 +1185,17 @@ class AsyncMemoryClient: @api_error_handler async def delete_all(self, **kwargs) -> Dict[str, str]: + """Delete all memories, with optional filtering. + + Args: + **kwargs: Optional parameters for filtering (user_id, agent_id, app_id). + + Returns: + A dictionary containing the API response. + + Raises: + APIError: If the API request fails. + """ params = self._prepare_params(kwargs) response = await self.async_client.delete("/v1/memories/", params=params) response.raise_for_status() @@ -956,6 +1204,17 @@ class AsyncMemoryClient: @api_error_handler async def history(self, memory_id: str) -> List[Dict[str, Any]]: + """Retrieve the history of a specific memory. + + Args: + memory_id: The ID of the memory to retrieve history for. + + Returns: + A list of dictionaries containing the memory history. + + Raises: + APIError: If the API request fails. + """ params = self._prepare_params() response = await self.async_client.get(f"/v1/memories/{memory_id}/history/", params=params) response.raise_for_status() @@ -964,6 +1223,7 @@ class AsyncMemoryClient: @api_error_handler async def users(self) -> Dict[str, Any]: + """Get all users, agents, and sessions for which memories exist.""" params = self._prepare_params() response = await self.async_client.get("/v1/entities/", params=params) response.raise_for_status() @@ -993,6 +1253,7 @@ class AsyncMemoryClient: ValueError: If specified entity not found APIError: If deletion fails """ + if user_id: to_delete = [{"type": "user", "name": user_id}] elif agent_id: @@ -1004,7 +1265,10 @@ class AsyncMemoryClient: else: entities = await self.users() # Filter entities based on provided IDs using list comprehension - to_delete = [{"type": entity["type"], "name": entity["name"]} for entity in entities["results"]] + to_delete = [ + {"type": entity["type"], "name": entity["name"]} + for entity in entities["results"] + ] params = self._prepare_params() @@ -1013,13 +1277,21 @@ class AsyncMemoryClient: # Delete entities and check response immediately for entity in to_delete: - response = await self.async_client.delete(f"/v2/entities/{entity['type']}/{entity['name']}/", params=params) + response = await self.async_client.delete( + f"/v2/entities/{entity['type']}/{entity['name']}/", params=params + ) response.raise_for_status() capture_client_event( "client.delete_users", self, - {"user_id": user_id, "agent_id": agent_id, "app_id": app_id, "run_id": run_id, "sync_type": "async"}, + { + "user_id": user_id, + "agent_id": agent_id, + "app_id": app_id, + "run_id": run_id, + "sync_type": "async", + }, ) return { "message": "Entity deleted successfully." @@ -1029,6 +1301,17 @@ class AsyncMemoryClient: @api_error_handler async def reset(self) -> Dict[str, str]: + """Reset the client by deleting all users and memories. + + This method deletes all users, agents, sessions, and memories + associated with the client. + + Returns: + Dict[str, str]: Message client reset successful. + + Raises: + APIError: If the API request fails. + """ await self.delete_users() capture_client_event("client.reset", self, {"sync_type": "async"}) return {"message": "Client reset successful. All users and memories deleted."} @@ -1038,7 +1321,8 @@ class AsyncMemoryClient: """Batch update memories. Args: - memories: List of memory dictionaries to update. Each dictionary must contain: + memories: List of memory dictionaries to update. Each dictionary + must contain: - memory_id (str): ID of the memory to update - text (str): New text content for the memory @@ -1051,7 +1335,9 @@ class AsyncMemoryClient: response = await self.async_client.put("/v1/batch/", json={"memories": memories}) response.raise_for_status() - capture_client_event("client.batch_update", self, {"sync_type": "async"}) + capture_client_event( + "client.batch_update", self, {"sync_type": "async"} + ) return response.json() @api_error_handler @@ -1059,7 +1345,8 @@ class AsyncMemoryClient: """Batch delete memories. Args: - memories: List of memory dictionaries to delete. Each dictionary must contain: + memories: List of memory dictionaries to delete. Each dictionary + must contain: - memory_id (str): ID of the memory to delete Returns: @@ -1068,10 +1355,14 @@ class AsyncMemoryClient: Raises: APIError: If the API request fails. """ - response = await self.async_client.request("DELETE", "/v1/batch/", json={"memories": memories}) + response = await self.async_client.request( + "DELETE", "/v1/batch/", json={"memories": memories} + ) response.raise_for_status() - capture_client_event("client.batch_delete", self, {"sync_type": "async"}) + capture_client_event( + "client.batch_delete", self, {"sync_type": "async"} + ) return response.json() @api_error_handler @@ -1107,8 +1398,36 @@ class AsyncMemoryClient: capture_client_event("client.get_memory_export", self, {"keys": list(kwargs.keys()), "sync_type": "async"}) return response.json() + @api_error_handler + async def get_summary(self, filters: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: + """Get the summary of a memory export. + + Args: + filters: Optional filters to apply to the summary request + + Returns: + Dict containing the export status and summary data + """ + + response = await self.async_client.post("/v1/summary/", json=self._prepare_params({"filters": filters})) + response.raise_for_status() + capture_client_event("client.get_summary", self, {"sync_type": "async"}) + return response.json() + @api_error_handler async def get_project(self, fields: Optional[List[str]] = None) -> Dict[str, Any]: + """Get instructions or categories for the current project. + + Args: + fields: List of fields to retrieve + + Returns: + Dictionary containing the requested fields. + + Raises: + APIError: If the API request fails. + ValueError: If org_id or project_id are not set. + """ if not (self.org_id and self.project_id): raise ValueError("org_id and project_id must be set to access instructions or categories") @@ -1130,6 +1449,22 @@ class AsyncMemoryClient: enable_graph: Optional[bool] = None, version: Optional[str] = None, ) -> Dict[str, Any]: + """Update the project settings. + + Args: + custom_instructions: New instructions for the project + custom_categories: New categories for the project + retrieval_criteria: New retrieval criteria for the project + enable_graph: Enable or disable the graph for the project + version: Version of the project + + Returns: + Dictionary containing the API response. + + Raises: + APIError: If the API request fails. + ValueError: If org_id or project_id are not set. + """ if not (self.org_id and self.project_id): raise ValueError("org_id and project_id must be set to update instructions or categories") @@ -1173,19 +1508,50 @@ class AsyncMemoryClient: return response.json() async def chat(self): + """Start a chat with the Mem0 AI. (Not implemented) + + Raises: + NotImplementedError: This method is not implemented yet. + """ raise NotImplementedError("Chat is not implemented yet") @api_error_handler async def get_webhooks(self, project_id: str) -> Dict[str, Any]: - response = await self.async_client.get( - f"api/v1/webhooks/projects/{project_id}/", - ) + """Get webhooks configuration for the project. + + Args: + project_id: The ID of the project to get webhooks for. + + Returns: + Dictionary containing webhook details. + + Raises: + APIError: If the API request fails. + ValueError: If project_id is not set. + """ + + response = await self.async_client.get(f"api/v1/webhooks/projects/{project_id}/") response.raise_for_status() capture_client_event("client.get_webhook", self, {"sync_type": "async"}) return response.json() @api_error_handler async def create_webhook(self, url: str, name: str, project_id: str, event_types: List[str]) -> Dict[str, Any]: + """Create a webhook for the current project. + + Args: + url: The URL to send the webhook to. + name: The name of the webhook. + event_types: List of event types to trigger the webhook for. + + Returns: + Dictionary containing the created webhook details. + + Raises: + APIError: If the API request fails. + ValueError: If project_id is not set. + """ + payload = {"url": url, "name": name, "event_types": event_types} response = await self.async_client.post(f"api/v1/webhooks/projects/{project_id}/", json=payload) response.raise_for_status() @@ -1200,6 +1566,21 @@ class AsyncMemoryClient: url: Optional[str] = None, event_types: Optional[List[str]] = None, ) -> Dict[str, Any]: + """Update a webhook configuration. + + Args: + webhook_id: ID of the webhook to update + name: Optional new name for the webhook + url: Optional new URL for the webhook + event_types: Optional list of event types to trigger the webhook for. + + Returns: + Dictionary containing the updated webhook details. + + Raises: + APIError: If the API request fails. + """ + payload = {k: v for k, v in {"name": name, "url": url, "event_types": event_types}.items() if v is not None} response = await self.async_client.put(f"api/v1/webhooks/{webhook_id}/", json=payload) response.raise_for_status() @@ -1208,6 +1589,18 @@ class AsyncMemoryClient: @api_error_handler async def delete_webhook(self, webhook_id: int) -> Dict[str, str]: + """Delete a webhook configuration. + + Args: + webhook_id: ID of the webhook to delete + + Returns: + Dictionary containing success message. + + Raises: + APIError: If the API request fails. + """ + response = await self.async_client.delete(f"api/v1/webhooks/{webhook_id}/") response.raise_for_status() capture_client_event("client.delete_webhook", self, {"webhook_id": webhook_id, "sync_type": "async"}) diff --git a/pyproject.toml b/pyproject.toml index 312ba754..67083b07 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "mem0ai" -version = "0.1.108" +version = "0.1.109" description = "Long-term memory for AI Agents" authors = [ { name = "Mem0", email = "founders@mem0.ai" }