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

```json
{
    "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

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

All users

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

User across all runs

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

## Content search

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

### Text search

Case-insensitive match:

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

Case-sensitive match:

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

### Categories

Match against category list:

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

### Metadata

Pin to a metadata attribute:

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

## Time-based filtering

Retrieve memories within specific date ranges using time operators.

Date range:

```json
{
    "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.