Memory Filters - Mem0

Memory Filters

Memory filters provide a flexible way to query and retrieve specific memories from your memory store. You can filter by users, agents, content categories, time ranges, and combine multiple conditions using logical operators.

When to use filters

When working with large-scale memory stores, you need precise control over which memories to retrieve. Filters help you:

Filter structure

Filters use a nested JSON structure with logical operators at the root:

{
    "AND": [  
        { "field": "value" },
        { "field": { "operator": "value" } }
    ]
}

Available fields and operators

Entity fields

Field Operators Example
user_id eq, ne, in, * {"user_id": "user_123"}
agent_id eq, ne, in, * {"agent_id": "*"}
app_id eq, ne, in, * {"app_id": {"in": ["app1", "app2"]}}
run_id eq, ne, in, * {"run_id": "*"}

Time fields

Field Operators Example
created_at gt, gte, lt, lte, eq, ne {"created_at": {"gte": "2024-01-01"}}
updated_at gt, gte, lt, lte, eq, ne {"updated_at": {"lt": "2024-12-31"}}
timestamp gt, gte, lt, lte, eq, ne {"timestamp": {"gt": "2024-01-01"}}

Content fields

Field Operators Example
categories eq, ne, in, contains {"categories": {"in": ["finance"]}}
metadata eq, ne, contains {"metadata": {"key": "value"}}
keywords contains, icontains {"keywords": {"icontains": "invoice"}}

Special fields

Field Operators Example
memory_ids in {"memory_ids": ["id1", "id2"]}

The * wildcard matches any non-null value. Records with null values for that field are excluded.

Use operator keywords exactly as shown (eq, ne, gte, etc.). SQL-style symbols such as >= or != are rejected by the Platform API.

Common filter patterns

Use these ready-made filters to target typical retrieval scenarios without rebuilding logic from scratch.

Single user

{"AND": [{"user_id": "user_123"}]}

All users

{"AND": [{"user_id": "*"}]}

User across all runs

{
    "AND": [  
        {"user_id": "user_123"},
        {"run_id": "*"}
    ]
}

Content search

Find memories containing specific text, categories, or metadata values.

Text search

Case-insensitive match:

{
    "AND": [
        {"user_id": "user_123"},
        {"keywords": {"icontains": "pizza"}}
    ]
}

Case-sensitive match:

{
    "AND": [
        {"user_id": "user_123"},
        {"keywords": {"contains": "Invoice_2024"}}
    ]
}

Categories

Match against category list:

{
    "AND": [
        {"user_id": "user_123"},
        {"categories": {"in": ["finance", "health"]}}
    ]
}

Metadata

Pin to a metadata attribute:

{
    "AND": [
        {"user_id": "user_123"},
        {"metadata": {"source": "email"}}
    ]
}

Time-based filtering

Retrieve memories within specific date ranges using time operators.

Date range:

{
    "AND": [
        {"user_id": "user_123"},
        {"created_at": {"gte": "2024-01-01T00:00:00Z"}},
        {"created_at": {"lt": "2024-02-01T00:00:00Z"}}
    ]
}

Best practices

The root must be AND, OR, or NOT with an array of conditions.

Use "*" to match any non-null value for a field.

Memories are stored per-entity (user, agent, app, run). Combining user_id and agent_id in the same AND clause returns no results because no record contains both values at once. Query one entity scope at a time or use OR logic for parallel lookups.