From fe3f10adb86d3f10aef8696fdf4e6d3d9fdd7253 Mon Sep 17 00:00:00 2001 From: Prateek Chhikara <46902268+prateekchhikara@users.noreply.github.com> Date: Thu, 5 Jun 2025 23:53:04 -0700 Subject: [PATCH] Add Wildcard Character Support Documentation for v2 Memory APIs (#2919) --- docs/api-reference/memory/v2-get-memories.mdx | 22 ++ .../memory/v2-search-memories.mdx | 21 ++ docs/platform/quickstart.mdx | 192 +++++++++++++++++- 3 files changed, 233 insertions(+), 2 deletions(-) diff --git a/docs/api-reference/memory/v2-get-memories.mdx b/docs/api-reference/memory/v2-get-memories.mdx index 1da3036b..26d17311 100644 --- a/docs/api-reference/memory/v2-get-memories.mdx +++ b/docs/api-reference/memory/v2-get-memories.mdx @@ -9,6 +9,9 @@ The v2 get memories API is powerful and flexible, allowing for more precise memo - `lte`: Less than or equal to - `gt`: Greater than - `lt`: Less than +- `ne`: Not equal to +- `icontains`: Case-insensitive containment check +- `*`: Wildcard character that matches everything ```python Code @@ -41,3 +44,22 @@ memories = m.get_all( ] ``` + + +```python Wildcard Example +# Using wildcard to get all memories for a specific user across all run_ids +memories = m.get_all( + filters={ + "AND": [ + { + "user_id": "alex" + }, + { + "run_id": "*" + } + ] + }, + version="v2" +) +``` + diff --git a/docs/api-reference/memory/v2-search-memories.mdx b/docs/api-reference/memory/v2-search-memories.mdx index f0526869..044d9f72 100644 --- a/docs/api-reference/memory/v2-search-memories.mdx +++ b/docs/api-reference/memory/v2-search-memories.mdx @@ -11,6 +11,7 @@ The v2 search API is powerful and flexible, allowing for more precise memory ret - `lt`: Less than - `ne`: Not equal to - `icontains`: Case-insensitive containment check +- `*`: Wildcard character that matches everything ```python Code @@ -49,3 +50,23 @@ The v2 search API is powerful and flexible, allowing for more precise memory ret } ``` + + + ```python Wildcard Example + # Using wildcard to match all run_ids for a specific user + all_memories = m.search( + query="What are Alice's hobbies?", + version="v2", + filters={ + "AND": [ + { + "user_id": "alice" + }, + { + "run_id": "*" + } + ] + }, + ) + ``` + diff --git a/docs/platform/quickstart.mdx b/docs/platform/quickstart.mdx index 81bd0d9b..925f7fce 100644 --- a/docs/platform/quickstart.mdx +++ b/docs/platform/quickstart.mdx @@ -458,7 +458,7 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \ #### Search using custom filters -Our advanced search allows you to set custom search filters. You can filter by user_id, agent_id, app_id, run_id, created_at, updated_at, categories, and text. The filters support logical operators (AND, OR) and comparison operators (in, gte, lte, gt, lt, ne, contains, icontains). For more details, see [V2 Search Memories](/api-reference/memory/v2-search-memories). +Our advanced search allows you to set custom search filters. You can filter by user_id, agent_id, app_id, run_id, created_at, updated_at, categories, and text. The filters support logical operators (AND, OR) and comparison operators (in, gte, lte, gt, lt, ne, contains, icontains, *). The wildcard character (*) matches everything for a specific field. For more details, see [V2 Search Memories](/api-reference/memory/v2-search-memories). Here you need to define `version` as `v2` in the search method. @@ -765,6 +765,81 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \ +Example 5: Search using wildcard filters + +```python Python +query = "What do you know about me?" +filters = { + "AND": [ + { + "user_id": "alex" + }, + { + "run_id": "*" # Matches all run_ids + } + ] +} +client.search(query, version="v2", filters=filters) +``` + +```javascript JavaScript +const query = "What do you know about me?"; +const filters = { + "AND": [ + { + "user_id": "alex" + }, + { + "run_id": "*" // Matches all run_ids + } + ] +}; + +client.search(query, { version: "v2", filters }) + .then(results => console.log(results)) + .catch(error => console.error(error)); +``` + +```bash cURL +curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \ + -H "Authorization: Token your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "What do you know about me?", + "filters": { + "AND": [ + { + "user_id": "alex" + }, + { + "run_id": "*" + } + ] + } + }' +``` + +```json Output +{ + "results": [ + { + "id": "7f165f7e-b411-4afe-b7e5-35789b72c4a5", + "memory": "Name: Alex. Vegetarian. Allergic to nuts.", + "user_id": "alex", + "run_id": "session-1", + "metadata": null, + "categories": ["food_preferences"], + "immutable": false, + "expiration_date": null, + "created_at": "2024-07-20T01:30:36.275141-07:00", + "updated_at": "2024-07-20T01:30:36.275172-07:00" + } + ] +} +``` + + + ### 4.3 Get All Users @@ -1138,7 +1213,7 @@ curl -X GET "https://api.mem0.ai/v1/memories/?user_id=alex&keywords=to play&page #### Get all memories using custom filters -Our advanced retrieval allows you to set custom filters when fetching memories. You can filter by user_id, agent_id, app_id, run_id, created_at, updated_at, categories, and keywords. The filters support logical operators (AND, OR) and comparison operators (in, gte, lte, gt, lt, ne, contains, icontains). For more details, see [v2 Get Memories](/api-reference/memory/v2-get-memories). +Our advanced retrieval allows you to set custom filters when fetching memories. You can filter by user_id, agent_id, app_id, run_id, created_at, updated_at, categories, and keywords. The filters support logical operators (AND, OR) and comparison operators (in, gte, lte, gt, lt, ne, contains, icontains, *). The wildcard character (*) matches everything for a specific field. For more details, see [v2 Get Memories](/api-reference/memory/v2-get-memories). Here you need to define `version` as `v2` in the get_all method. @@ -1497,6 +1572,119 @@ curl -X GET "https://api.mem0.ai/v1/memories/?version=v2&page=1&page_size=50" \ +Example 4: Get all memories using wildcard filters + +```python Python +filters = { + "AND": [ + { + "user_id": "alex" + }, + { + "run_id": "*" # Matches all run_ids + } + ] +} + +# Default (No Pagination) +client.get_all(version="v2", filters=filters) + +# Pagination (You can also use the page and page_size parameters) +client.get_all(version="v2", filters=filters, page=1, page_size=50) +``` + +```javascript JavaScript +const filters = { + "AND": [ + { + "user_id": "alex" + }, + { + "run_id": "*" // Matches all run_ids + } + ] +}; + +// Default (No Pagination) +client.getAll({ version: "v2", filters }) + .then(memories => console.log(memories)) + .catch(error => console.error(error)); + +// Pagination (You can also use the page and page_size parameters) +client.getAll({ version: "v2", filters, page: 1, page_size: 50 }) + .then(memories => console.log(memories)) + .catch(error => console.error(error)); +``` + +```bash cURL +# Default (No Pagination) +curl -X GET "https://api.mem0.ai/v1/memories/?version=v2" \ + -H "Authorization: Token your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "filters": { + "AND": [ + {"user_id":"alex"}, + {"run_id": "*"} + ] + } + }' + +# Pagination (You can also use the page and page_size parameters) +curl -X GET "https://api.mem0.ai/v1/memories/?version=v2&page=1&page_size=50" \ + -H "Authorization: Token your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "filters": { + "AND": [ + {"user_id":"alex"}, + {"run_id": "*"} + ] + } + }' +``` + +```json Output (Default) +[ + { + "id": "f38b689d-6b24-45b7-bced-17fbb4d8bac7", + "memory": "Name: Alex. Vegetarian. Allergic to nuts.", + "user_id": "alex", + "run_id": "session-1", + "metadata": null, + "categories": ["food_preferences"], + "immutable": false, + "expiration_date": null, + "created_at": "2024-07-20T01:30:36.275141-07:00", + "updated_at": "2024-07-20T01:30:36.275172-07:00" + } +] +``` + +```json Output (Paginated) +{ + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": "f38b689d-6b24-45b7-bced-17fbb4d8bac7", + "memory": "Name: Alex. Vegetarian. Allergic to nuts.", + "user_id": "alex", + "run_id": "session-1", + "metadata": null, + "categories": ["food_preferences"], + "immutable": false, + "expiration_date": null, + "created_at": "2024-07-20T01:30:36.275141-07:00", + "updated_at": "2024-07-20T01:30:36.275172-07:00" + } + ] +} +``` + + + ### 4.5 Memory History