Skip to content
AlexeinDocs
Get started

Two products, one account

Filters

Narrow search, latest and items to what matches - who said it, what it is about, or your own metadata - with AND, OR and NOT.

filters narrows search, latest and items to the items you added that match: by who said them, what they are about, or the metadata you gave them. A filter applies before ranking, not after it, so a narrow filter does not come back short.

Search only high-priority items about one project
{
  "query": "What did we decide about the budget?",
  "filters": {
    "AND": [
      { "metadata": { "priority": { "gte": 3 } } },
      { "mentions": "project:lisbon-trip" }
    ]
  }
}

The shape is the one Mem0's filters use: conditions written {"field": value} or {"field": {"op": value}}, combined with AND, OR and NOT.

Fields

FieldMatchesOperators
authorThe item's author: its id, name, email or handle, ignoring case.eq (a bare value), ne, in, nin, "*"
mentionsWhat the item is about, as about takes it (project:lisbon-trip, or topic:diet for a bare diet), or its session as session:<id>.contains (a bare value), in
metadata.<key>One top-level key of the item's metadata.eq (a bare value), ne, in, nin, gt, gte, lt, lte, contains, icontains, "*"
  • "*" means the field is set: {"metadata": {"source": "*"}} keeps items that have a source.
  • A metadata value is a string, a number, or true or false. A list is matched element by element, so {"metadata": {"tags": "urgent"}} matches "tags": ["urgent", "billing"]. Nested objects are kept with the item, but cannot be filtered on.
  • Numbers must be exact. Send an integer larger than 2^53 (9,007,199,254,740,992) as a string.
  • gt, gte, lt and lte compare numbers with numbers and strings with strings, never true or false.
  • contains matches part of a string, or one element of a list; icontains the same, ignoring case. Both need a value that is not empty.
  • in and nin take a list of 1 to 100 values.
  • mentions takes what about takes, and session:<id>. Anything else is refused with a 422 that says what to use instead, such as scope for a place or author for a person.

author and metadata are fields of items you add: what connected apps deliver has neither, so a condition on them matches only your items.

Combining conditions

  • Keys side by side must all match: {"author": "Alice Chen", "metadata": {"source": "crm"}}.
  • AND and OR take a list of filters. NOT takes one filter.
  • One operator per condition. {"metadata": {"priority": {"gte": 1, "lte": 5}}} is refused; write two conditions under AND.
  • A filter holds at most 50 conditions, nested at most 5 deep.

What a filter matches

A filter tests items, and search and latest return excerpts and facts:

  • An excerpt matches when any item in it matches.
  • A negation (ne, nin or NOT) keeps an excerpt only when none of its items matches what is negated.
  • A fact matches through the excerpt it was learned from.

On each route:

  • search with filters is a narrowed search: it returns facts and excerpts only.
  • latest returns the newest matching excerpts, or those between after and before.
  • items lists the matching items. Items still queued are not filtered, so a filtered list holds stored items only.

Over MCP, memory_search and memory_latest take the same filters. See the tools reference.

Errors

A filter that does not fit is refused with 422 before anything is read. detail names where the problem is, then what is wrong:

422
{ "detail": "`filters`: filters.metadata.priority: one operator per condition, not 2; AND them. See https://docs.alexein.ai/api/search for what this route takes." }