From 2b0a457198fa750b7aeb701c665111d3d4707d98 Mon Sep 17 00:00:00 2001 From: Parth Sharma <109902593+parthshr370@users.noreply.github.com> Date: Mon, 3 Nov 2025 23:41:04 +0530 Subject: [PATCH] [docs] Custom categories Documentation fix (#3702) --- docs/platform/features/custom-categories.mdx | 170 +++++++++++-------- 1 file changed, 102 insertions(+), 68 deletions(-) diff --git a/docs/platform/features/custom-categories.mdx b/docs/platform/features/custom-categories.mdx index a1c0b851c..c784a5b94 100644 --- a/docs/platform/features/custom-categories.mdx +++ b/docs/platform/features/custom-categories.mdx @@ -1,19 +1,41 @@ --- title: Custom Categories -description: 'Enhance your product experience by adding custom categories tailored to your needs' +description: "Teach Mem0 the labels that matter to your team." --- -## How to Set Custom Categories +# Custom Categories -You can create custom categories tailored to your specific needs instead of using the default categories such as travel, sports, and music (see [default categories](#default-categories) below). When custom categories are provided, they will override the default categories. +Mem0 automatically tags every memory, but the default labels (travel, sports, music, etc.) may not match the names your app uses. Custom categories let you replace that list so the tags line up with your own wording. -There are two ways to set custom categories: + + **Use custom categories when…** + - You need Mem0 to tag memories with names your product team already uses. + - You want clean reports or automations that rely on those tags. + - You’re moving from the open-source version and want the same labels here. + -### 1. Project Level + + Per-request overrides (`custom_categories=...` on `client.add`) are not supported on the managed API yet. Set categories at the project level, then ingest memories as usual. + -You can set custom categories at the project level, which will be applied to all memories added within that project. Mem0 will automatically assign relevant categories from your custom set to new memories based on their content. Setting custom categories at the project level will override the default categories. +## Configure access -Here's how to set custom categories: +- Ensure `MEM0_API_KEY` is set in your environment or pass it to the SDK constructor. +- If you scope work to a specific organization/project, initialize the client with those identifiers. + +## How it works + +- **Default list** — Each project starts with 15 broad categories like `travel`, `sports`, and `music`. +- **Project override** — When you call `project.update(custom_categories=[...])`, that list replaces the defaults for future memories. +- **Automatic tags** — As new memories come in, Mem0 picks the closest matches from your list and saves them in the `categories` field. + + + Default catalog: `personal_details`, `family`, `professional_details`, `sports`, `travel`, `food`, `music`, `health`, `technology`, `hobbies`, `fashion`, `entertainment`, `milestones`, `user_preferences`, `misc`. + + +## Configure it + +### 1. Set custom categories at the project level ```python Code @@ -42,31 +64,7 @@ print(response) ``` -This is how you will use these custom categories during the `add` API call: - - -```python Code -messages = [ - {"role": "user", "content": "My name is Alice. I need help organizing my daily schedule better. I feel overwhelmed trying to balance work, exercise, and social life."}, - {"role": "assistant", "content": "I understand how overwhelming that can feel. Let's break this down together. What specific areas of your schedule feel most challenging to manage?"}, - {"role": "user", "content": "I want to be more productive at work, maintain a consistent workout routine, and still have energy for friends and hobbies."}, - {"role": "assistant", "content": "Those are great goals for better time management. What's one small change you could make to start improving your daily routine?"}, -] - -# Add memories with custom categories -client.add(messages, user_id="alice") -``` - -```python Memories with categories -# Following categories will be created for the memories added -Wants to have energy for friends and hobbies (lifestyle_management_concerns) -Wants to maintain a consistent workout routine (seeking_structure, lifestyle_management_concerns) -Wants to be more productive at work (lifestyle_management_concerns, seeking_structure) -Name is Alice (personal_information) -``` - - -You can also retrieve the current custom categories: +### 2. Confirm the active catalog ```python Code @@ -83,32 +81,15 @@ print(categories) {"personal_information": "Basic information about the user including name, preferences, and personality traits"} ] } - ``` -These project-level categories will be automatically applied to all new memories added to the project. +## See it in action - - -### 2. During the `add` API Call - -You can also set custom categories during the `add` API call. This will override any project-level custom categories for that specific memory addition. For example, if you want to use different categories for food-related memories, you can provide custom categories like "food" and "user_preferences" in the `add` call. These custom categories will be used instead of the project-level categories when categorizing those specific memories. +### Add a memory (uses the project catalog automatically) ```python Code -import os -from mem0 import MemoryClient - -os.environ["MEM0_API_KEY"] = "your-api-key" - -client = MemoryClient(api_key="") - -custom_categories = [ - {"seeking_structure": "Documents goals around creating routines, schedules, and organized systems in various life areas"}, - {"personal_information": "Basic information about the user including name, preferences, and personality traits"} -] - messages = [ {"role": "user", "content": "My name is Alice. I need help organizing my daily schedule better. I feel overwhelmed trying to balance work, exercise, and social life."}, {"role": "assistant", "content": "I understand how overwhelming that can feel. Let's break this down together. What specific areas of your schedule feel most challenging to manage?"}, @@ -116,23 +97,59 @@ messages = [ {"role": "assistant", "content": "Those are great goals for better time management. What's one small change you could make to start improving your daily routine?"}, ] -client.add(messages, user_id="alice", custom_categories=custom_categories) -``` - -```python Memories with categories -# Following categories will be created for the memories added -Wants to have energy for friends and hobbies (seeking_structure) -Wants to maintain a consistent workout routine (seeking_structure) -Wants to be more productive at work (seeking_structure) -Name is Alice (personal_information) +# Add memories with project-level custom categories +client.add(messages, user_id="alice", async_mode=False) ``` -Providing more detailed and specific category descriptions will lead to more accurate and relevant memory categorization. +### Retrieve memories and inspect categories + +```python Code +memories = client.get_all(filters={"user_id": "alice"}) +``` + +```json Output +["lifestyle_management_concerns", "seeking_structure"] +``` + + + + **Sample memory payload** + ```json + { + "id": "33d2***", + "memory": "Trying to balance work and workouts", + "user_id": "alice", + "metadata": null, + "categories": ["wellness"], // ← matches the custom category we set + "created_at": "2025-11-01T02:13:32.828364-07:00", + "updated_at": "2025-11-01T02:13:32.830896-07:00", + "expiration_date": null, + "structured_attributes": { + "day": 1, + "hour": 9, + "year": 2025, + "month": 11, + "minute": 13, + "quarter": 4, + "is_weekend": true, + "day_of_week": "saturday", + "day_of_year": 305, + "week_of_year": 44 + } + } + ``` + + + + Need ad-hoc labels for a single call? Store them in `metadata` until per-request overrides become available. + + +## Default categories (fallback) + +If you do nothing, memories are tagged with the built-in set below. -## Default Categories -Here is the list of **default categories**. If you don't specify any custom categories using the above methods, these will be used as default categories. ``` - personal_details - family @@ -170,7 +187,7 @@ messages = [ ] # Add memories with default categories -client.add(messages, user_id='alice') +client.add(messages, user_id='alice', async_mode=False) ``` ```python Memories with categories @@ -182,7 +199,7 @@ Name is Alice (personal_details) ``` -You can check whether default categories are being used by calling `project.get()`. If `custom_categories` returns `None`, it means the default categories are being used. +You can verify the defaults are active by checking: ```python Code @@ -191,11 +208,28 @@ client.project.get(["custom_categories"]) ```json Output { - 'custom_categories': None + "custom_categories": None } ``` -If you have any questions, please feel free to reach out to us using one of the following methods: +## Verify the feature is working - \ No newline at end of file +- `client.project.get(["custom_categories"])` returns the category list you set. +- `client.get_all(filters={"user_id": ...})` shows populated `categories` lists on new memories. +- The Mem0 dashboard (Project → Memories) displays the custom labels in the Category column. + +## Best practices + +- Keep category descriptions concise but specific; the classifier uses them to disambiguate. +- Review memories with empty `categories` to see where you might extend or rename your list. +- Stick with project-level overrides until per-request support is released; mixing approaches causes confusion. + + + + Explore other ingestion tunables like custom prompts and selective writes. + + + See custom tagging drive personalization in a full agent workflow. + +