---
title: Custom Categories
description: "Replace default memory tags with custom category labels that match your product terminology at the project level."
---

# Custom Categories

Deja Vu 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.

<Info>
  **Use custom categories when…**
  - You need Deja Vu 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.
</Info>

<Warning>
  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.
</Warning>

## Configure access

- Ensure `VENICE_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, Deja Vu picks the closest matches from your list and saves them in the `categories` field.

<Note>
  Default catalog: `personal_details`, `family`, `professional_details`, `sports`, `travel`, `food`, `music`, `health`, `technology`, `hobbies`, `fashion`, `entertainment`, `milestones`, `user_preferences`, `misc`.
</Note>

## Configure it

### 1. Set custom categories at the project level

<CodeGroup>
```python Code
import os
from dejavu import MemoryClient

os.environ["VENICE_API_KEY"] = "your-api-key"

client = MemoryClient()

# Update custom categories
new_categories = [
    {"lifestyle_management_concerns": "Tracks daily routines, habits, hobbies and interests including cooking, time management and work-life balance"},
    {"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"}
]

response = client.project.update(custom_categories=new_categories)
print(response)
```

```json Output
{
    "message": "Updated custom categories"
}
```
</CodeGroup>

### 2. Confirm the active catalog

<CodeGroup>
```python Code
# Get current custom categories
categories = client.project.get(fields=["custom_categories"])
print(categories)
```

```json Output
{
  "custom_categories": [
    {"lifestyle_management_concerns": "Tracks daily routines, habits, hobbies and interests including cooking, time management and work-life balance"},
    {"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"}
  ]
}
```
</CodeGroup>

## See it in action

### Add a memory (uses the project catalog automatically)

<CodeGroup>
```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 project-level custom categories
client.add(messages, user_id="alice")
```
</CodeGroup>

### Retrieve memories and inspect categories

<CodeGroup>
```python Code
memories = client.get_all(filters={"user_id": "alice"})
```

```json Output
["lifestyle_management_concerns", "seeking_structure"]
```
</CodeGroup>

<Info>
  **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
    }
  }
  ```
</Info>

<Note>
  Need ad-hoc labels for a single call? Store them in `metadata` until per-request overrides become available.
</Note>

## Default categories (fallback)

If you do nothing, memories are tagged with the built-in set below.

```
- personal_details
- family
- professional_details
- sports
- travel
- food
- music
- health
- technology
- hobbies
- fashion
- entertainment
- milestones
- user_preferences
- misc
```

<CodeGroup>
```python Code
import os
from dejavu import MemoryClient

os.environ["VENICE_API_KEY"] = "your-api-key"

client = MemoryClient()

messages = [
    {"role": "user", "content": "Hi, my name is Alice."},
    {"role": "assistant", "content": "Hi Alice, what sports do you like to play?"},
    {"role": "user", "content": "I love playing badminton, football, and basketball. I'm quite athletic!"},
    {"role": "assistant", "content": "That's great! Alice seems to enjoy both individual sports like badminton and team sports like football and basketball."},
    {"role": "user", "content": "Sometimes, I also draw and sketch in my free time."},
    {"role": "assistant", "content": "That's cool! I'm sure you're good at it."}
]

# Add memories with default categories
client.add(messages, user_id='alice')
```

```python Memories with categories
# Following categories will be created for the memories added
Sometimes draws and sketches in free time (hobbies)
Is quite athletic (sports)
Loves playing badminton, football, and basketball (sports)
Name is Alice (personal_details)
```
</CodeGroup>

You can verify the defaults are active by checking:

<CodeGroup>
```python Code
client.project.get(["custom_categories"])
```

```json Output
{
    "custom_categories": None
}
```
</CodeGroup>

## Verify the feature is working

- `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 Deja Vu 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.

<CardGroup cols={2}>
  <Card title="Advanced Memory Operations" icon="wand-magic-sparkles" href="/platform/advanced-memory-operations">
    Explore other ingestion tunables like custom prompts and selective writes.
  </Card>
  <Card title="Travel Assistant Cookbook" icon="plane-up" href="/cookbooks/companions/travel-assistant">
    See custom tagging drive personalization in a full agent workflow.
  </Card>
</CardGroup>
