Enhanced Metadata Filtering

Fine-grained metadata queries for precise OSS memory retrieval.

Enhanced metadata filtering in Mem0 lets you run complex queries across memory metadata. Combine comparisons, logical operators, and wildcard matches to zero in on the exact memories your agent needs.

This page covers the self-hosted Memory / AsyncMemory grammar. Sibling top-level keys are implicitly ANDed on both self-hosted and the hosted Platform API, so a flat filter like {"user_id": "alice", "category": "work"} works without wrapping it in AND on either. Two real differences remain: the nin operator documented below is not part of the Platform contract, and Platform validates every top-level key against a fixed allow-list, rejecting anything else with a 400. See Memory Filters (Platform) for the hosted grammar.

---

Feature anatomy

Operator quick reference

Operator	Meaning	When to use it
eq / ne	Equals / not equals	Exact matches on strings, numbers, or booleans.
gt / gte	Greater than / greater than or equal	Rank results by score, confidence, or any numeric field.
lt / lte	Less than / less than or equal	Cap numeric values (e.g., ratings, timestamps).
in / nin	In list / not in list	Pre-approve or block sets of values without chaining multiple filters.
contains / icontains	Case-sensitive / case-insensitive substring match	Scan text fields for keywords.
*	Wildcard	Match regardless of value. Exact semantics (field-must-exist vs. no-op) vary by vector store, see Wildcard matching.
AND / OR / NOT	Combine filters	Build logic trees so multiple conditions work together.

Metadata selectors

Start with key-value filters when you need direct matches on metadata fields.

from mem0 import Memory

m = Memory()

# Search with simple metadata filters
results = m.search(
    "What are my preferences?",
    filters={"user_id": "alice", "category": "preferences"}
)

Expect only memories tagged with category="preferences" to return for the given user_id.

Comparison operators

Layer greater-than/less-than comparisons to rank results by score, confidence, or any numeric field. Equality helpers (eq, ne) keep string and boolean checks explicit.

# Greater than / Less than
results = m.search(
    "recent activities",
    filters={
        "user_id": "alice",
        "score": {"gt": 0.8},
        "priority": {"gte": 5},
        "confidence": {"lt": 0.9},
        "rating": {"lte": 3}
    }
)

# Equality operators
results = m.search(
    "specific content",
    filters={
        "user_id": "alice",
        "status": {"eq": "active"},
        "archived": {"ne": True}
    }
)

List-based operators

Use in and nin when you want to pre-approve or exclude specific values without writing multiple equality checks.

# In / Not in operators
results = m.search(
    "multi-category search",
    filters={
        "user_id": "alice",
        "category": {"in": ["food", "travel", "entertainment"]},
        "status": {"nin": ["deleted", "archived"]}
    }
)

Verify the response includes only memories in the whitelisted categories and omits any with archived or deleted status.

String operators

contains and icontains capture substring matches, making it easy to scan descriptions or tags for keywords without retrieving irrelevant memories.

# Text matching operators
results = m.search(
    "content search",
    filters={
        "user_id": "alice",
        "title": {"contains": "meeting"},
        "description": {"icontains": "important"},
        "tags": {"contains": "urgent"}
    }
)

Wildcard matching

Match any value for a field, handy when the mere presence of a field matters.

# Match any value for a field
results = m.search(
    "all with category",
    filters={
        "user_id": "alice",
        "category": "*"
    }
)

Wildcard semantics differ by vector store. pgvector requires the key to exist in the payload (a real “field exists” check). Qdrant and Chroma have no native “field exists” filter, so * is a no-op there: the field condition is dropped and every record passes, including ones where the field is missing entirely. Do not rely on * to exclude records with a missing field unless you have confirmed your store’s behavior in mem0/vector_stores/<provider>.py.

Logical combinations

Combine filters with AND, OR, and NOT to express complex decision trees. Nest logical operators to encode multi-branch workflows.

The examples on this page use search(). get_all() accepts the same entity and comparison-operator filters, but the AND / OR / NOT wrapper is only translated at the search() layer before it reaches the vector store. Whether it also works on get_all() depends on your vector store: Qdrant recognizes raw AND / OR / NOT keys natively, but pgvector does not, so a logical wrapper passed to get_all() on pgvector silently matches nothing. Stick to search() for logical trees, or use plain sibling keys (implicitly ANDed) with get_all().

# Logical AND
results = m.search(
    "complex query",
    filters={
        "user_id": "alice",
        "AND": [
            {"category": "work"},
            {"priority": {"gte": 7}},
            {"status": {"ne": "completed"}}
        ]
    }
)

# Logical OR
results = m.search(
    "flexible query",
    filters={
        "user_id": "alice",
        "OR": [
            {"category": "urgent"},
            {"priority": {"gte": 9}},
            {"deadline": {"contains": "today"}}
        ]
    }
)

# Logical NOT
results = m.search(
    "exclusion query",
    filters={
        "user_id": "alice",
        "NOT": [
            {"category": "archived"},
            {"status": "deleted"}
        ]
    }
)

# Complex nested logic
results = m.search(
    "advanced query",
    filters={
        "user_id": "alice",
        "AND": [
            {
                "OR": [
                    {"category": "work"},
                    {"category": "personal"}
                ]
            },
            {"priority": {"gte": 5}},
            {
                "NOT": [
                    {"status": "archived"}
                ]
            }
        ]
    }
)

Inspect the response metadata: each returned memory should satisfy the combined logic tree exactly. If results look too broad, log the raw filters sent to your vector store.

---

Configure it

Tune your vector store so filter-heavy queries stay fast. Index fields you frequently filter on and keep complex checks for later in the evaluation order.

# Ensure your vector store supports indexing on filtered fields
config = {
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "host": "localhost",
            "port": 6333,
            "indexed_fields": ["category", "priority", "status", "user_id"]
        }
    }
}

After enabling indexing, benchmark the same query: latency should drop once the store can prune documents on indexed fields before vector scoring.

Put simple key=value filters on indexed fields before your range or text conditions so the store trims results early.

# More efficient: Filter on indexed fields first
good_filters = {
    "user_id": "alice",
    "AND": [
        {"category": "work"},
        {"content": {"contains": "meeting"}}
    ]
}

# Less efficient: Complex operations first
avoid_filters = {
    "user_id": "alice",
    "AND": [
        {"description": {"icontains": "complex text search"}}
    ]
}

When you reorder filters so indexed fields come first (good_filters example), queries typically return faster than the avoid_filters pattern where expensive text searches run before simple checks.

Vector store support varies widely. This table reflects what each provider’s filter-translation code (mem0/vector_stores/<provider>.py) actually implements, confirm before shipping if you use a store not listed:

Store	eq/ne/gt/gte/lt/lte/in/nin	contains/icontains	AND/OR/NOT	* wildcard
Qdrant	Full support (in/nin must be a list, or the Qdrant client raises a validation error)	Yes	Yes, nested	No-op: matches every record regardless of whether the field is present
pgvector	Full support (in/nin must be a list, or the call raises ValueError)	Yes, via SQL LIKE/ILIKE	Yes, nested	Requires the key to exist in the payload
Chroma	Full support	No: silently falls back to equality	Yes, one level of nesting	No-op: the filter is dropped
Pinecone	Full support	Not implemented	Not implemented: filters are only ANDed field-by-field	Not implemented: "*" is matched as the literal string "*", not a wildcard
Weaviate	Not implemented: only user_id, agent_id and run_id are filtered on, as exact equality. Every other key, including all metadata, is silently dropped	Not implemented	Not implemented: only an implicit AND across the three supported keys	Not implemented

If an operator is unsupported, most stores silently ignore it or fall back to equality rather than raising an error. Test filters against your actual store instead of assuming operator parity with Qdrant.

Migrate from earlier filters

# Before (v0.x) - simple key-value filtering only
results = m.search(
    "query",
    filters={"user_id": "alice", "category": "work", "status": "active"}
)

# After (v1.0.0) - enhanced filtering with operators
results = m.search(
    "query",
    filters={
        "user_id": "alice",
        "AND": [
            {"category": "work"},
            {"status": {"ne": "archived"}},
            {"priority": {"gte": 5}}
        ]
    }
)

Existing equality filters continue to work; add new operator branches gradually so agents can adopt richer queries without downtime.

---

See it in action

Project management filtering

# Find high-priority active tasks
results = m.search(
    "What tasks need attention?",
    filters={
        "user_id": "project_manager",
        "AND": [
            {"project": {"in": ["alpha", ""]}},
            {"priority": {"gte": 8}},
            {"status": {"ne": "completed"}},
            {
                "OR": [
                    {"assignee": "alice"},
                    {"assignee": "bob"}
                ]
            }
        ]
    }
)

Tasks returned should belong to the targeted projects, remain incomplete, and be assigned to one of the listed teammates.

Customer support filtering

# Find recent unresolved tickets
results = m.search(
    "pending support issues",
    filters={
        "agent_id": "support_bot",
        "AND": [
            {"ticket_status": {"ne": "resolved"}},
            {"priority": {"in": ["high", "critical"]}},
            {"created_date": {"gte": "2024-01-01"}},
            {
                "NOT": [
                    {"category": "spam"}
                ]
            }
        ]
    }
)

Pair agent ID filters with ticket-specific metadata so shared support bots return only the tickets they can act on in the current session.

Content recommendation filtering

# Personalized content filtering
results = m.search(
    "recommend content",
    filters={
        "user_id": "reader123",
        "AND": [
            {
                "OR": [
                    {"genre": {"in": ["sci-fi", "fantasy"]}},
                    {"author": {"contains": "favorite"}}
                ]
            },
            {"rating": {"gte": 4.0}},
            {"read_status": {"ne": "completed"}},
            {"language": "english"}
        ]
    }
)

Confirm personalized feeds show only unread titles that meet the rating and language criteria.

Handle invalid operators

try:
    results = m.search(
        "test query",
        filters={
            "user_id": "alice",
            "invalid_operator": {"unknown": "value"}
        }
    )
except ValueError as e:
    print(f"Filter error: {e}")
    results = m.search(
        "test query",
        filters={"user_id": "alice", "category": "general"}
    )

Validate filters before executing searches so you can catch typos or unsupported operators during development instead of at runtime.

---

Verify the feature is working

• Log the filters sent to your vector store and confirm the response metadata matches every clause.
• Benchmark queries before and after indexing to ensure latency improvements materialize.
• Add analytics or debug logging to track how often fallbacks execute when operators fail validation.

---

Best practices

1. Use indexed fields first: Order filters so equality checks run before complex string operations.
2. Combine operators intentionally: Keep logical trees readable: large nests are harder to debug.
3. Test performance regularly: Benchmark critical queries with production-like payloads.
4. Plan graceful degradation: Provide fallback filters when an operator isn’t available.
5. Validate syntax early: Catch malformed filters during development to protect agents at runtime.

---

Explore Vector Store Options

Compare operator coverage and indexing strategies across supported stores.

Tag and Organize Memories

Practice building workflows that label and retrieve memories with clear metadata filters.

Memory Filters (Platform)

Using the hosted API instead? See the allow-listed top-level fields, the missing nin operator, and Platform-only fields like created_at and memory_ids.