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:

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

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

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` (matches any category in the list), `contains` (case-insensitive)	`{"categories": {"in": ["finance"]}}`
`metadata`	`eq`, `ne`, `contains`	`{"metadata": {"key": "value"}}`
`keywords`	`contains` (case-sensitive), `icontains` (case-insensitive)	`{"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

# Narrow to one user's memories
filters = {"AND": [{"user_id": "user_123"}]}
memories = client.get_all(filters=filters)

All users

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

User across all runs

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

Metadata filters only support bare values/eq, contains, and ne. Operators such as in, gt, or lt trigger a FilterValidationError. For multi-value checks, wrap multiple equality clauses in OR.

# Multi-value metadata workaround
filters = {
    "OR": [
        {"metadata": {"type": "semantic"}},
        {"metadata": {"type": "episodic"}}
    ]
}

Content search

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

Text search (keywords)

# Substring match on memory text via get_all
filters = {
    "AND": [
        {"user_id": "user_123"},
        {"keywords": {"icontains": "invoice"}}
    ]
}
memories = client.get_all(filters=filters)

Use contains for case-sensitive matching and icontains for case-insensitive.

A keywords filter works on get_all, but passing it to search() currently returns a 500 (MEM-5746). For text relevance during a search, pass the text to the query argument instead of filtering on keywords.

Time-based filtering

Retrieve memories within specific date ranges using time operators.

Date range

# 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.

Multiple users

# Expand scope to a short user list
filters = {
    "AND": [
        {"user_id": {"in": ["user_1", "user_2", "user_3"]}}
    ]
}

OR logic

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

Exclude categories

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

Specific memory IDs

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

All entities populated

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

Matches records where user_id equals user_123 and run_id/app_id are both non-null. It does not require other entity fields to be null.

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.

Multi-dimensional filtering

filters = {
    "AND": [
        {"user_id": "user_123"},
        {"categories": {"in": ["finance"]}},
        {"keywords": {"icontains": "invoice"}},
        {"created_at": {"gte": "2024-01-01T00:00:00Z"}},
        {"created_at": {"lt": "2024-04-01T00:00:00Z"}}
    ]
}
memories = client.get_all(filters=filters)

Entity-specific retrieval

# Query agent scope on its own
filters = {
    "AND": [
        {"agent_id": "finance_bot"}
    ]
}

# Or broaden within that scope using wildcards
filters = {
    "AND": [
        {"agent_id": "finance_bot"},
        {"run_id": "*"}
    ]
}

Nested NOT/OR logic

# 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 does not have to be AND, OR, or NOT. A bare filter like {"user_id": "alice"} works on its own; wrap conditions in a logical operator only when you need to combine more than one.

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

Combining user_id and agent_id in the same AND clause only returns records that have both values set. Memories created by a normal client.add never do: each extracted fact is attributed to its speaker, so it carries user_id or agent_id, not both. Use OR to match either scope. Only Direct Import (infer=False) writes both fields on one record.A filter object with both an AND key and a sibling OR key at the same level silently drops the OR branch today. Nest the OR inside the AND array instead of placing them as siblings.

Troubleshooting

Missing results with agent_id

Problem: Filtered by user_id but don’t see agent memories.Solution: A user_id filter only matches records that have that user_id set; it won’t surface memories written with only agent_id. Use OR to query both scopes:

{"OR": [{"user_id": "user_123"}, {"agent_id": "agent_name"}]}

ne operator returns too much

Problem: ne comparison pulls in records with null values.Solution: Pair ne with a wildcard guard:

{"AND": [{"agent_id": "*"}, {"agent_id": {"ne": "old_agent"}}]}

Case-insensitive text match

Solution: Use keywords with icontains on get_all:

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

This works on get_all. It is not supported on search() yet (returns a 500, MEM-5746) - for search, pass the text to the query argument instead.

Date range between two dates

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"}}
]}

Metadata filter not working

Solution: Match top-level metadata keys exactly:

{"metadata": {"source": "email"}}

FAQ

Do I need AND/OR/NOT?

No. A bare filter like {"user_id": "u1"} works on its own. Add AND, OR, or NOT only when you need to combine more than one condition.

What does * match?

Any non-null value. Nulls are excluded.

Why use wildcards?

Unspecified fields default to NULL. Use "*" to include non-null values.

Is = required?

No. Equality is the default: {"user_id": "u1"} works.

Can I filter nested metadata?

Only top-level keys are supported.

How to search text?

For a substring match, use the keywords filter with contains/icontains on get_all. For relevance-ranked search, pass the text to the query argument on search(). Note: keywords is not supported inside search() filters yet (returns a 500, MEM-5746).

Can I nest AND/OR?

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

Known limitations

Filters only constrain the fields you mention; unmentioned entity fields are not required to be null. A record carries user_id or agent_id (never both) unless it came from Direct Import, plus whatever app_id and run_id were passed.
Metadata supports only bare/eq, contains, and ne comparisons.
Wildcards ("*" ) match only records where the field is already non-null.

Getting Started

Core Concepts

Features

Support

Migration

Memory Filters

When to use filters

Filter structure

Available fields and operators

Entity fields

Time fields

Content fields

Special fields

Common filter patterns

Content search

Time-based filtering

Multiple criteria

Advanced examples

Best practices

Troubleshooting

FAQ

Known limitations

​When to use filters

​Filter structure

​Available fields and operators

​Entity fields

​Time fields

​Content fields

​Special fields

​Common filter patterns

​Content search

​Time-based filtering

​Multiple criteria

​Advanced examples

​Best practices

​Troubleshooting

​FAQ

​Known limitations

When to use filters

Filter structure

Available fields and operators

Entity fields

Time fields

Content fields

Special fields

Common filter patterns

Content search

Time-based filtering

Multiple criteria

Advanced examples

Best practices

Troubleshooting

FAQ

Known limitations