mem0 Filter Syntax

Contract

When you call the mem0 Python SDK (MemoryClient / Memory) to search or get_all memories, emit mem0's OWN filter grammar — never MongoDB / Mongoose syntax. Apply whenever you build a filters= object or pick the search arguments.

Rules

1. Search arguments. client.search(query, filters=..., top_k=..., threshold=..., rerank=...).

• query — the natural-language semantic query string.
• filters — the filter object (see rule 3+).
• top_k — max results (NOT limit, k, n, max_results, count, or size).
• threshold — minimum semantic score, a float (default 0.1); pass 0.0 to disable score

filtering. NOT min_score, min_relevance, score, or cutoff.

• rerank — a boolean; turns on the managed reranker. NOT use_rerank, reorder, rerankers.
• Listing without a semantic query uses client.get_all(filters=...) (NOT list, all,

get_memories).

1. Entity scopes are snake_case and at least one is required. The scoping keys are exactly

user_id, agent_id, app_id, run_id — snake_case, never camelCase (userId, agentId) and never id / application_id / session_id. Every filter must carry at least one entity id. A bare {"user_id": "alice"} is equality shorthand.

1. Logical operators are BARE UPPERCASE keys — no $. Combine conditions with AND, OR,

NOT (never $and / $or / $not, never lowercase and / or).

• AND — value is a JSON array of condition objects (all must match).
• OR — value is a JSON array of condition objects (any match).
• NOT — value is a single condition object (must not match).
• Nest freely: an AND array may contain an OR object and vice-versa.

1. Comparison operators are BARE keys — no $. Nest an operator object on a field:

• in — membership in a list: {"categories": {"in": ["finance", "health"]}} (NOT $in).
• gte / lte / gt / lt — numeric/date range (NOT $gte etc.).
• contains — case-SENSITIVE substring.
• icontains — case-INSENSITIVE substring (this is the ONLY case-insensitive form — NOT

$regex, regex, like, ilike).

• ne — not-equal (NOT $ne, neq, !=).

1. Wildcard "any non-null value" is the literal string "*". e.g. {"run_id": "*"} matches

records where run_id is present. NEVER $exists, {"ne": null}, or a boolean-exists form.

1. Metadata is a sub-object supporting only eq / contains / ne. Write

{"metadata": {"type": "decision"}} — never a dotted "metadata.type" key. Metadata does NOT support range operators (gte/lte) — only bare equality, contains, and ne.

1. Dates are ISO-8601 strings on created_at / updated_at with gte/lte/gt/lt, e.g.

{"created_at": {"gte": "2024-01-01T00:00:00Z"}}.

Worked examples

Simple scoped search — base reaches for a flat call + limit:

# BEFORE (base default)                    # AFTER (mem0)
m.search("payment retries",                m.search("payment retries",
         user_id="u_42", limit=5)                   filters={"user_id": "u_42"}, top_k=5)

Compound AND with metadata — base reaches for MongoDB $and + dotted key:

# BEFORE  filters={"$and": [{"user_id": "u_42"}, {"metadata.kind": "note"}]}
# AFTER   filters={"AND": [{"user_id": "u_42"}, {"metadata": {"kind": "note"}}]}

Case-insensitive substring — base reaches for $regex:

# BEFORE  {"summary": {"$regex": "timeout", "$options": "i"}}
# AFTER   {"summary": {"icontains": "timeout"}}

Membership + wildcard + date — base reaches for $in / $exists / $gte:

# BEFORE  {"$and": [{"labels": {"$in": ["a","b"]}}, {"run_id": {"$exists": true}},
#                   {"created_at": {"$gte": "2025-01-01T00:00:00Z"}}]}
# AFTER   {"AND": [{"labels": {"in": ["a","b"]}}, {"run_id": "*"},
#                  {"created_at": {"gte": "2025-01-01T00:00:00Z"}}]}

Negation — base reaches for $not / $ne:

# BEFORE  {"$and": [{"user_id": "u_42"}, {"tier": {"$ne": "trial"}}]}
# AFTER   {"AND": [{"user_id": "u_42"}, {"NOT": {"tier": "trial"}}]}

Edge cases & exceptions

• No entity id → invalid. A metadata-only or category-only filter is rejected; add a

user_id / agent_id / app_id / run_id scope.

• Metadata numbers need range → not supported. Metadata only does eq/contains/ne; promote the

value to a top-level field or filter it after retrieval.

• get_all paginates with page / page_size; search caps with top_k. Don't put top_k

on get_all or page on search.

• Python is snake_case; the TypeScript SDK is camelCase. This convention is the Python form.
• threshold=0.0 returns everything above score 0 (filtering effectively off), not "top 0".

Do / Don't

• DO use bare AND / OR / NOT. DON'T use $and / $or / $not.
• DO use bare in / gte / icontains / ne. DON'T prefix operators with $.
• DO use icontains for case-insensitive match. DON'T use $regex / like.
• DO use "*" for any-non-null. DON'T use $exists / {"ne": null}.
• DO use top_k and threshold. DON'T use limit / k / min_score.
• DO nest metadata as {"metadata": {...}}. DON'T use dotted "metadata.key".
• DO keep entity ids snake_case. DON'T camelCase them in Python.

Common mistakes

• MongoDB carryover: $and, $or, $gte, $lte, $in, $ne, $regex, $exists, $options.
• limit= / k= / n= instead of top_k=; min_score= instead of threshold=.
• userId / agentId / appId (camelCase) in the Python SDK.
• Dotted metadata paths ("metadata.type") instead of the {"metadata": {...}} sub-object.
• Using contains when case-insensitivity is required (that needs icontains).
• {"run_id": {"$exists": true}} instead of {"run_id": "*"}.

Quick checklist

• ] Logical keys are bare AND / OR / NOT (arrays for AND/OR, object for NOT).
• ] No $-prefixed operator anywhere.
• ] Operators: in / gte / lte / gt / lt / contains / icontains / ne.
• ] At least one snake_case entity id (user_id / agent_id / app_id / run_id).
• ] Any-non-null is "*"; metadata is a sub-object (eq/contains/ne only); dates are ISO-8601.
• ] Result cap is top_k; min score is threshold; reranker is rerank.