Skip to main content
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:
  • Isolate user data: Retrieve memories for specific users while maintaining privacy
  • Debug and audit: Export specific memory subsets for analysis
  • Target content: Find memories with specific categories or metadata
  • Time-based queries: Retrieve memories within specific date ranges
  • Performance optimization: Reduce query complexity by pre-filtering
Filters were introduced in v1.0.0 to provide precise control over memory retrieval.

​
Filter structure

Filters use a nested JSON structure with logical operators at the root: 
# Basic structure
{
    "AND": [  # or "OR", "NOT"
        { "field": "value" },
        { "field": { "operator": "value" } }
    ]
}

​
Available fields and operators

​
Entity fields

FieldOperatorsExample
user_id=, !=, in, *{"user_id": "user_123"}
agent_id=, !=, in, *{"agent_id": "*"}
app_id=, !=, in, *{"app_id": {"in": ["app1", "app2"]}}
run_id=, !=, in, *{"run_id": "*"}

​
Time fields

FieldOperatorsExample
created_at>, >=, <, <=, =, !={"created_at": {"gte": "2024-01-01"}}
updated_at>, >=, <, <=, =, !={"updated_at": {"lt": "2024-12-31"}}
timestamp>, >=, <, <=, =, !={"timestamp": {"gt": "2024-01-01"}}

​
Content fields

FieldOperatorsExample
categories=, !=, in, contains{"categories": {"in": ["finance"]}}
metadata=, !={"metadata": {"key": "value"}}
keywordscontains, icontains{"keywords": {"icontains": "invoice"}}

​
Special fields

FieldOperatorsExample
memory_idsin{"memory_ids": ["id1", "id2"]}
The * wildcard matches any non-null value. Records with null values for that field are excluded.

​
Common filter patterns

Use these ready-made filters to target typical retrieval scenarios without rebuilding logic from scratch. 
# Narrow to one user's memories
filters = {"AND": [{"user_id": "user_123"}]}
memories = client.get_all(filters=filters)

# Wildcard skips null user_id entries
filters = {"AND": [{"user_id": "*"}]}
memories = client.get_all(filters=filters)

# Pair a user filter with a run wildcard
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"run_id": "*"}
    ]
}
memories = client.get_all(filters=filters)

​
Content search

Find memories containing specific text, categories, or metadata values. 
# Case-insensitive match
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"keywords": {"icontains": "pizza"}}
    ]
}

# Case-sensitive match
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"keywords": {"contains": "Invoice_2024"}}
    ]
}

# Match against category list
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"categories": {"in": ["finance", "health"]}}
    ]
}

# Partial category match
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"categories": {"contains": "finance"}}
    ]
}

# Pin to a metadata attribute
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"metadata": {"source": "email"}}
    ]
}

​
Time-based filtering

Retrieve memories within specific date ranges using time operators. 
# Created in January 2024
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"created_at": {"gte": "2024-01-01T00:00:00Z"}},
        {"created_at": {"lt": "2024-02-01T00:00:00Z"}}
    ]
}

# Updated recently
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"updated_at": {"gte": "2024-12-01T00:00:00Z"}}
    ]
}

​
Multiple criteria

Combine various filters for complex queries across different dimensions. 
# Expand scope to a short user list
filters = {
    "AND": [
        {"user_id": {"in": ["user_1", "user_2", "user_3"]}}
    ]
}

# Return matches on either condition
filters = {
    "OR": [
        {"user_id": "user_123"},
        {"run_id": "run_456"}
    ]
}

# Wrap negative logic with NOT
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"NOT": {
            "categories": {"in": ["spam", "test"]}
        }}
    ]
}

# Fetch a fixed set of memory IDs
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"memory_ids": ["mem_1", "mem_2", "mem_3"]}
    ]
}

# Require every entity field to be non-null
filters = {
    "AND": [
        {"user_id": "*"},
        {"agent_id": "*"},
        {"run_id": "*"},
        {"app_id": "*"}
    ]
}

​
Advanced examples

Level up foundational patterns with compound filters that coordinate entity scope, tighten time windows, and weave in exclusion rules for high-precision retrievals. 
# Invoice memories in Q1 2024
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"keywords": {"icontains": "invoice"}},
        {"categories": {"in": ["finance"]}},
        {"created_at": {"gte": "2024-01-01T00:00:00Z"}},
        {"created_at": {"lt": "2024-04-01T00:00:00Z"}}
    ]
}

# From specific agent, all users
filters = {
    "AND": [
        {"agent_id": "finance_bot"},
        {"user_id": "*"}
    ]
}

# Any entity populated
filters = {
    "OR": [
        {"user_id": "*"},
        {"agent_id": "*"},
        {"run_id": "*"},
        {"app_id": "*"}
    ]
}

# User memories from 2024, excluding spam and test
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"created_at": {"gte": "2024-01-01T00:00:00Z"}},
        {"NOT": {
            "OR": [
                {"categories": {"in": ["spam"]}},
                {"categories": {"in": ["test"]}}
            ]
        }}
    ]
}

​
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.
When you specify user_id only, other entity fields default to null. Use wildcards to include them.

​
Troubleshooting

Problem: Filtered by user_id but don’t see agent memories.Solution: Add a wildcard for agent_id so non-null entries return:
{"AND": [{"user_id": "user_123"}, {"agent_id": "*"}]}
Problem: ne comparison pulls in records with null values.Solution: Pair ne with a wildcard guard:
{"AND": [{"agent_id": "*"}, {"agent_id": {"ne": "old_agent"}}]}
Solution: Use gte for the start and lt for the end boundary:
{"AND": [
    {"created_at": {"gte": "2024-01-01"}},
    {"created_at": {"lt": "2024-02-01"}}
]}
Solution: Match top-level metadata keys exactly:
{"metadata": {"source": "email"}}

​
FAQ

Yes. The root must be a logical operator with an array.
Any non-null value. Nulls are excluded.
Unspecified fields default to NULL. Use "*" to include non-null values.
No. Equality is the default: {"user_id": "u1"} works.
Only top-level keys are supported.
Use keywords with contains (case-sensitive) or icontains (case-insensitive).
{
    "AND": [
        {"user_id": "user_123"},
        {"OR": [
            {"categories": "finance"},
            {"categories": "health"}
        ]}
    ]
}