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 user, public, and knowledgebase 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.

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

4. Available Fields and Operators

The root of each filter group must be and or or, followed by a list of field conditions. Specifying user_id in filter is not supported.

Instance Fields

For more details about these fields, see the advanced usage section in Add Message.

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

Filter Memories by Agent

"filter": {
    "or": [
        {"agent_id": "agent_123"},
        {"agent_id": "agent_456"}
    ]
}

Filter Memories by Business Scenario

"filter": {
    "and": [
        {"business_type": "travel"},
        {"biz_id": "travel_001"},
        {"scene": "payment"},
        {"custom_status": "v1"}
    ]
}

Filter by Tag and Date Range

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

Filter Different Memory Sources Separately

The following example retrieves Knowledge Base memories tagged with "reading" and created in 2025, user memories where scene=chat, and public memories tagged with "announcement".

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