MessengersMAX

MAX messenger search query language

Every field, operator, preset and limit of MAX message search, with date rules, regular expressions and the JSON answer for scripts and agents.

This is the reference for writing message-search queries. You will be able to combine words, people, chats, dates and file conditions, check the query syntax and interpret the returned matches.

When using max through an AI agent, describe what you want in ordinary words and let the agent form the search query. Use this reference when typing searches yourself or looking up exact operators, every field, presets, date rules and limits.

This is help for the queries max personal search messages, max personal search all, max personal stats messages show, saved searches and --filter search by topic. Examples for every day - in message search.

Terms used below:

  • Query — what you search for, such as счёт from:me date:7d.
  • Field — a name followed by a colon, targeting a message property: from: for sender or date: for date. Unqualified words search message text.
  • Operator — a word or symbol combining conditions: AND, OR, NOT.
  • Word forms — variations of one word, such as “apartment” and “apartments”.

This language implements a strict subset of Apache Lucene syntax: words, phrases, AND/OR/NOT, groups, fields, ranges, limited patterns and regular expressions. Unsupported syntax causes an error rather than being silently skipped. The full reference contains generated field/operator/preset/limit tables and verified examples; the technical specification describes grammar and compilation.

max does not search mail: that is memo search mail.

What the language can do

NeedWrite
messages with all these words, in any formсчёт оплачен
these words in a row, in this order"счёт оплачен"
one word or another, without a third(кафе OR библиотека) NOT шумно
only this form of the wordexact:квартира, or --exact for all words without a field
words that start with somethingквартир*
sender, chat, chat typefrom:me, chat:"Книжный клуб", kind:private
perioddate:7d, date:[2026-01-01 TO 2026-02-01}
files by name or sizefilename:*.pdf, size>10MB
text similar to password, card or phonepreset:secret, preset:card
your own tagstag:work
templatetext:/pass(port)?/

Unqualified words and phrases match word forms. --exact selects exact forms for unqualified words; explicit text: still matches forms. Archive language settings determine which forms match (word forms).

Operators

OperatorExampleMeaning
wordsсчёт оплаченboth words
phrase"счёт оплачен"the words in this order
AND, &&alpha AND betaboth
OR, ||alpha OR betaeither
NOT, !, -alpha NOT betathe first without the second
++alpha OR betaalpha required, beta optional
group(alpha OR beta) gammabrackets set the order
field groupfrom:(alice OR bob)the field applies to each value
rangedate:[2026-01-01 TO 2026-02-01}[ ] include, { } exclude, * open
comparisonsize>10MB, date>=7d, date:>=7dan open range; the form with a colon means the same
wildcardквартир*, т?кст* any characters, ? one
regextext:/pass(port)?/a bounded Lucene regular expression

alpha OR beta gamma means (alpha OR beta) AND gamma; alpha OR beta AND gamma means alpha OR (beta AND gamma). Use parentheses for clarity. Lowercase and, or, not are ordinary words. A lone NOT query finds nothing; add a positive condition such as kind:group NOT preset:secret. Fuzzy search ~, word proximity, boosts and intervals produce errors rather than being skipped. Typos are not corrected; use a pattern such as квартир* for different endings.

Fields

FieldFindsExample
textmessage words (the default field)text:счёт
exactExact word or phrase formexact:квартира, exact:"счёт оплачен"
bodythe whole original text, case-sensitivebody:/.*счёт.*/
fromsender by name, @username or id; me means youfrom:"Алиса Тестова"
chatchat by title, @username or idchat:"Книжный клуб"
datewhen sentdate:today, date:7d, date:[2026-01-01 TO 2026-02-01}
kindchat kind: private, group, channel, saved, bot, service, unknownkind:private
hasattachment, link, file, photo, image, video, audio, voice, sticker, contact, location, pollhas:file
topicone discussion thread; needs one chatchat:"Книжный клуб" AND topic:42
inwhich accounts: provider or botsin:bots
presettext resembling a secret or contactpreset:secret
contentretained attachment textcontent:договор
filenamewhole attachment filenamefilename:*.pdf
mimeattachment type; MAX does not report itmime:image
sizeattachment size in bytes or 1,024-based KB/MB/GBsize>10MB
tagyour local tag on the message, its chat or sendertag:work
phonea phone number found in the text, however it is writtenphone:"+34 600 000 000"
emailan email address found in the textemail:"ana@example.com"
urla link found in the text, without tracking parametersurl:"https://example.com/a"
domainthe site of a link or address found in the textdomain:example.com
mentionsthe person, organization or document that a found mention is linked tomentions:"person:12"

Field names are case-sensitive. An unknown field, value or combination is an error, never an empty answer and never plain text. A name that the archive does not know is not looked up on MAX.

kind:bot selects a chat with a bot; in:bots selects the archives of max sales bot. topic: requires exactly one chat in chat:: topic numbers repeat across chats. filename, mime and size match a message if at least one of its files matches. MAX does not report file types, so mime: finds nothing here: search by extension.

Mentions

max finds phone numbers, email addresses, links, documents and names of people in the saved messages. These fields find the messages that contain them. max personal mentions list shows the findings themselves.

max personal search messages 'phone:"+34 600 000 000"'
max personal search messages 'email:"ana@example.com" OR domain:example.com'
max personal search messages 'mentions:"person:12"'

Put a value with + or @ in quotes: both signs are operators. A phone number is found however it is written: +34 600 000 000 and 600000000 are one phone number, and a number without + is read by the countries in the phone_countries setting. domain: treats docs.example.com as the site example.com. In mentions:, write a reference to a person, organization or document; the field finds the messages whose mentions you linked to it with max mentions confirm.

max personal mentions list --new shows what is unresolved since the last --new, and max personal mentions domains shows the sites links lead to, most frequent first. confirm and reject with --all-in-chat resolve a name across the whole chat at once.

Presets

Preset finds text based on its type. With it you can find a password, code or card number that someone sent.

PresetA candidate is
passworda password label followed by a value
codea verification-code label and 4–8 digits
api-keyan API-key label and a value
secreta password, secret, token or API-key label and a value
card13–19 digits with optional spaces or hyphens
bankan IBAN-shaped value
passporta labelled passport value or a Russian 4+6 digit shape
phonea plus-prefixed international phone shape
emailan email-address shape
telegram-linka t.me or telegram.me link
urlan HTTP(S) link
contacta contact attachment, or an email or phone
locationa location attachment or a geo: link

A preset reports a candidate by its shape. It does not verify a password, a card or a document, and it can match something harmless. Do not delete or forward messages automatically on its word.

Dates

--timezone takes an IANA zone such as Europe/Madrid; without it, the computer's zone is used and returned in the answer. A date without a time is a whole calendar day. An inclusive upper day includes that whole day, an exclusive one excludes it; a day when clocks change can last 23 or 25 hours.

date:today and date:yesterday are calendar days. date:7d means from 7 days ago until now (also 30m, 2h); date>=7d and date:[30d TO 7d} work in comparisons and ranges, counted from the moment the query runs. An exact time is quoted, with seconds and an offset: date>="2026-01-01T10:00:00+02:00".

Words, wildcards and regular expressions

Before indexing and searching, text is converted to lower case and loses accents; ё becomes е, and й becomes и. Some different words therefore match: мой also finds «мои». Regex and wildcards on text: are normalized the same way.

text:/счёт/ matches the whole word «счёт», but not «счётом». body:/счёт/ matches only a message whose entire text is «счёт», case-sensitive; to find it anywhere, use body:/.*счёт.*/, and for the start of a sentence, body:/.*[Сс]чёт.*/. This is Lucene regular-expression syntax, without lookaround, backreferences, anchors or JavaScript flags.

On a large archive a short prefix such as к* can expand to more than 10,000 words and is refused; lengthen it. Long queries, deep nesting, large patterns and slow scans are refused with query_limit, not cut short: narrow the chat, the dates or the pattern.

The answer

--json returns { items, page, next, missing, meta }, even when nothing matched. --jsonl streams the messages only.

  • missing — what the search did not see and why: a coverage entry if some chats are not fetched or are behind, text while the word index is still being built, pictures if the image model is not downloaded.
  • next — the commands that fix this (messages.sync, store.migrate, models.download-image), and page.next — the next page with the same query.
  • meta.accounts — which accounts were searched.
  • page.has_more is about the page, not about whether MAX holds more.
  • page.total is how many messages match in all: { "value": 144, "relation": "eq" }. eq is an exact number, gte means at least: counting stops at 10 000. The terminal shows the same as showing 1–20 of 144.

An error carries the position of the problem in the query and a hint.

Via MCP

Through the max MCP server, max_read (command: "search messages") accepts the query as text in query. timezone sets the calendar zone. chat: goes in the query itself; source, newest, context and limit match command options; saved runs a saved search. thread, thread_hops, thread_messages, thread_bytes, thread_within and sync_first match --thread… and --sync-first; sync_first requires messages.sync-first: allow. The response is the same object as --json. max_read (command: "stats messages show") counts the same queries. record: false disables request-history recording.

Next steps

  • Message search - search for every day, saved searches and counting.
  • Search by topic - find a discussion by meaning when you don’t remember the words.