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 ordate: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
| Need | Write |
|---|---|
| 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 word | exact:квартира, or --exact for all words without a field |
| words that start with something | квартир* |
| sender, chat, chat type | from:me, chat:"Книжный клуб", kind:private |
| period | date:7d, date:[2026-01-01 TO 2026-02-01} |
| files by name or size | filename:*.pdf, size>10MB |
| text similar to password, card or phone | preset:secret, preset:card |
| your own tags | tag:work |
| template | text:/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
| Operator | Example | Meaning |
|---|---|---|
| words | счёт оплачен | both words |
| phrase | "счёт оплачен" | the words in this order |
AND, && | alpha AND beta | both |
OR, || | alpha OR beta | either |
NOT, !, - | alpha NOT beta | the first without the second |
+ | +alpha OR beta | alpha required, beta optional |
| group | (alpha OR beta) gamma | brackets set the order |
| field group | from:(alice OR bob) | the field applies to each value |
| range | date:[2026-01-01 TO 2026-02-01} | [ ] include, { } exclude, * open |
| comparison | size>10MB, date>=7d, date:>=7d | an open range; the form with a colon means the same |
| wildcard | квартир*, т?кст | * any characters, ? one |
| regex | text:/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
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.
| Preset | A candidate is |
|---|---|
password | a password label followed by a value |
code | a verification-code label and 4–8 digits |
api-key | an API-key label and a value |
secret | a password, secret, token or API-key label and a value |
card | 13–19 digits with optional spaces or hyphens |
bank | an IBAN-shaped value |
passport | a labelled passport value or a Russian 4+6 digit shape |
phone | a plus-prefixed international phone shape |
email | an email-address shape |
telegram-link | a t.me or telegram.me link |
url | an HTTP(S) link |
contact | a contact attachment, or an email or phone |
location | a 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: acoverageentry if some chats are not fetched or are behind,textwhile the word index is still being built,picturesif the image model is not downloaded.next— the commands that fix this (messages.sync,store.migrate,models.download-image), andpage.next— the next page with the same query.meta.accounts— which accounts were searched.page.has_moreis about the page, not about whether MAX holds more.page.totalis how many messages match in all:{ "value": 144, "relation": "eq" }.eqis an exact number,gtemeans at least: counting stops at 10 000. The terminal shows the same asshowing 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.