Migrate metadata filters to v5

Migration details

v5 uses one optional singular filter field for search, profiles, and list operations.

Shape

type Filter =
  | { field: string; operator: "eq" | "neq"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "eq" | "neq"; value: number | boolean }
  | { field: string; operator: "gt" | "gte" | "lt" | "lte"; value: number }
  | { field: string; operator: "contains" | "notContains"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "arrayContains" | "arrayNotContains"; value: string }
  | { operator: "and" | "or"; operands: Filter[] };

Fields may contain letters, numbers, _, ., and -. Expressions allow up to five nested levels and 200 operands per logical group.

Operator mapping

Legacy condition	v5 predicate
`{ key, value }`	`{ field: key, operator: "eq", value }`
`negate: true` equality	`operator: "neq"`
`filterType: "string_contains"`	`operator: "contains"`
contains + `negate: true`	`operator: "notContains"`
`filterType: "array_contains"`	`operator: "arrayContains"`
array contains + `negate: true`	`operator: "arrayNotContains"`
numeric `=` / numeric `=` + `negate: true`	`eq` / `neq` with a JSON number
numeric `>`, `>=`, `<`, `<=`	`gt`, `gte`, `lt`, `lte`
`AND` / `OR` arrays	lowercase `and` / `or` with `operands`
`ignoreCase: true`	`caseSensitive: false`

Before and after

{
  "AND": [
    { "key": "category", "value": "research" },
    { "key": "score", "value": 0.8, "filterType": "numeric", "numericOperator": ">=" }
  ]
}

{
  "operator": "and",
  "operands": [
    { "field": "category", "operator": "eq", "value": "research" },
    { "field": "score", "operator": "gte", "value": 0.8 }
  ]
}

With the SDK

await client.search.execute({
  q: "research notes",
  containerTags: ["user_1"],
  filters: JSON.stringify({
    AND: [
      { key: "category", value: "research" },
      { key: "score", value: 0.8, filterType: "numeric", numericOperator: ">=" },
    ],
  }),
})

await supermemory.search("user_1", {
  query: "research notes",
  filter: {
    operator: "and",
    operands: [
      { field: "category", operator: "eq", value: "research" },
      { field: "score", operator: "gte", value: 0.8 },
    ],
  },
  searchMode: "chunks",
})

filter is a typed object under body, not a JSON string. The same shape works in supermemory.list and supermemory.profile. Keys are literal: customer.plan is one field name, not a nested path.

Deterministic conversion

Rename outer filters to filter.
Recursively replace AND/OR objects with { operator, operands }.
Rename key to field.
Convert legacy flags into one explicit operator.
Keep numeric values as JSON numbers rather than numeric strings.
Remove legacy filterType, negate, numericOperator, and ignoreCase keys.

Verification

Compare result IDs for equality, inequality, contains, numeric, array, nested AND, and nested OR fixtures.
Add negative tests: legacy shapes, empty operands, incompatible value types, and unknown keys must return 400.
Confirm omitted filter preserves unfiltered behavior.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Migration details

Shape

Operator mapping

Before and after

With the SDK

Deterministic conversion

Verification

​Migration details

​Shape

​Operator mapping

​Before and after

​With the SDK

​Deterministic conversion

​Verification

Migration details

Shape

Operator mapping

Before and after

With the SDK

Deterministic conversion

Verification