Memory Filters

1. When to Use Memory Filters

When the memory set grows large, or when a single retrieval request accesses user memories, public memories, and Knowledge Base memories at the same time, you often need to narrow the candidate scope before MemOS performs semantic retrieval. Memory Filters are used for this precise pre-retrieval filtering step.

Common scenarios include:

• Retrieve only memories generated by a specific Agent or App.
• Retrieve only memories created or updated within a specific time range.
• Retrieve only memories that contain specific tags.
• Filter by business fields written when adding messages, such as scene, biz_id, or business_type.
• Apply different filters to user memories, public memories, and Knowledge Base memories.

2. How It Works

1. Filter the scope first: MemOS strictly filters candidate memories based on the conditions in filter.
2. Then perform semantic retrieval: Within the filtered candidates, MemOS runs memory retrieval and returns the fragments most relevant to query.

This means Filter is not keyword search. It is a scope control mechanism before retrieval. The stricter the filter, the fewer candidate memories enter semantic retrieval.

3. Two Filtering Modes

Global Filter

If you do not need to distinguish memory sources, you can put logical conditions directly at the root of filter. The condition applies to the memory scope involved in the current retrieval.

"filter": {
    "and": [
        {"tags": {"contains": "reading"}},
        {"create_time": {"gte": "2025-01-01"}},
        {"create_time": {"lte": "2025-12-31"}},
        {"scene": "chat"}
    ]
}

Source-Specific Filter

If one retrieval request accesses multiple memory types, you can set separate filter conditions for each source inside filter.

Source-specific filters are useful for more precise retrieval strategies, such as filtering user memories by recency, filtering Knowledge Base memories by tags, and leaving public memories unfiltered. Sources not included in filter will not receive extra filter conditions.

Example: Source-Specific Retrieval Across User, Knowledge Base, and Public Memories

The example below retrieves the user's and Agent's memories since June 1, 2025, and also retrieves Knowledge Base and public memories tagged with "policy".

"filter": {
    "user": {
        "and": [
            {"agent_id": "memos_agent"},
            {"create_time": {"gte": "2025-06-01"}}
        ]
    },
    "knowledgebase": {
        "and": [
            {"tags": {"contains": "policy"}}
        ]
    },
    "public": {
        "and": [
            {"tags": {"contains": "policy"}}
        ]
    }
}

4. Available Fields and Operators

The root of each filter group must be and or or, followed by a list of field conditions.

Instance Fields

Metadata Fields

When adding messages, you can write business metadata through info. During retrieval, use those fields directly by name in filter; do not wrap them in another info object.

// Recommended
{"scene": "chat"}

// Do not write it like this
{"info": {"scene": "chat"}}

Tag Fields

Time Fields

5. Usage Examples

The filters below cover common filtering needs, so you don't have to build the filter logic from scratch.

• Agents

// Filter memories related to any of the following Agents
"filter" : {
    "or": [
        {"agent_id": "agent_123"},
        {"agent_id": "agent_456"}
    ]
}

• Metadata

// Filter by custom metadata fields written via info (write the field name directly in filter, without wrapping it in info)
"filter" : {
    "and": [
        {"business_type":"travel"},
        {"biz_id":"travel_001"},
        {"scene":"payment"},
        {"custom_status":"v1"}
    ]
}

• Tags

// Filter memories that contain a specific tag
"filter" : {
    "and": [
        {"tags": {"contains": "weather"}}
    ]
}

• Date range

// Filter memories from December 2025
"filter" : {
    "and": [
        {"create_time": {"gt": "2025-12-01"}},
        {"create_time": {"lt": "2026-01-01"}}
    ]
}

// Filter memories updated recently
"filter" : {
    "and": [
        {"update_time": {"gt": "2025-12-10"}}
    ]
}

• Multiple dimensions

// Filter a user's Q4 billing-related memories with the customer service Agent
"filter" : {
    "and": [
        {"agent_id": "customer_service"},
        {"scene":"billing"},
        {"create_time": {"gt": "2025-10-01"}},
        {"create_time": {"lt": "2026-01-01"}}
    ]
}

• Retrieve memories related to multiple Agents or users

"filter" : {
    "and": [
        {"related_id": ["memos_agent_1", "memos_agent_2"]}
    ]
}