Search

You need to find something that was written: a message, an agreement, an address from months ago. This page shows how to search everything wa has saved on this computer — WhatsApp messages, and the notes that memo imported.

After reading it you can find messages by words, people, chats and dates, save a search and run it again, count matches, and tell a real "not found" from a gap in the saved history. Searching never connects to WhatsApp and marks nothing read.

Terms used on this page:

• Local store (also called the archive): the database on this computer where wa keeps every message the phone pushed and serve received (the local store). Every search reads only this.
• Query: what you search for. It can be plain words, or words with fields such as from: and date:. Your AI agent writes queries for you; the full language is in the query language reference.
• Coverage: what a search could see — how many chats and messages were saved.

When you remember the question rather than its wordingCopy Anchor Link

Ask your agent to find messages answering a question and show the supporting messages. For example: "Find when the Helix daily export runs in the project chat, and check whether the schedule changed." The agent can use archive discovery to find partial word matches and direct replies, then inspect those messages before answering. It does not download a model.

For command-line control:

wa personal search messages 'What time does Helix export run? chat:[email protected]' --discover --json

Chat, sender and date filters still apply. Over MCP, pass discover: true to wa_read (command: "search messages"). Each item's discovery says how much of the query it matched: missing_terms names unmatched terms, and parent links a reply to its matching parent. A high score is not answer confidence: a question, proposal or old decision can rank first. Read the evidence and check what the store holds before concluding that a fact is absent.

Without --discover, the usual strict search remains. Boolean syntax, quoted phrases, wildcards, --exact and --newest keep strict behavior.

What you can doCopy Anchor Link

Every search is under one group of commands, wa personal search. When you don't know where something was written, start with search all.

wa personal search all 'lease agreement'          # messages and notes, best match first

wa personal search all 'lease' --only notes       # notes only

wa personal search messages 'lease chat:"Book club"'  # WhatsApp messages only, never mail

wa personal search notes 'budget source:internal'  # only notes written in memo

search all says what each hit is — a message (msg:…) or a note (note:…). wa never searches mail: memo search mail does. When a field does not apply — chat:/from: for notes — search all skips that resource and explains why. Mail and notes reach the store through memo: memo sync --only mail and memo sync --only notes. Without them, search all searches messages only.

The rest of this page is about searching messages, wa personal search messages.

Try a focused searchCopy Anchor Link

Start with a phrase and one chat.

Your request:

Find the message saying "invoice paid" in Book club. Show the match and any gaps in the history.

Command:

wa personal search messages '"invoice paid" chat:"Book club"' --json

Example agent answer:

One matching message in saved history.

Person	Message
Alice Synthetic	Invoice paid yesterday.

The store holds this chat only since the device was linked. I can open this message and its surrounding conversation.

An empty result is not proof that the message never existed. The examples on this page are fictional.

What the store can answerCopy Anchor Link

Search sees only what the store holds: the history the phone pushed when the device was linked, what serve received while it ran, and the older messages messages sync asked of the phone (older history). A gap between the history push and the day serve started cannot be filled. Keep the store current with wa personal server install (keeping it current).

Every search says what it searched. With --json, coverage carries the number of messages and chats searched. Put the query in single quotes, so the shell leaves its quotes and brackets alone. The names below are examples; use your own chats and people.

Words and phrasesCopy Anchor Link

wa personal search messages invoice

wa personal search messages '"invoice paid"'     # words together

wa personal search messages 'cafe OR library'

wa personal search messages '(cafe OR library) NOT loud'

wa personal search messages 'invoic*'            # every word that starts with "invoic"

Words next to each other must all be in the message. Search includes word forms, according to the store's language settings: piso can find pisos. Quotes keep words together and also allow word forms. Use exact:piso or add --exact for words without an explicit field. An explicit text: still matches forms. Case and accents are ignored. Written message text is not corrected for typos.

Bare words and transcript: also search saved voice-note transcripts, including word forms and single-word spellings that speech recognition may have garbled. text: searches written text only; exact: or --exact for bare words keeps those words exact without widening transcript spellings.

People and chatsCopy Anchor Link

wa personal search messages 'from:"Alice Synthetic" invoice'

wa personal search messages 'from:("Alice Synthetic" OR "Bob Synthetic") library'

wa personal search messages 'from:me date:7d'    # what you wrote this week

wa personal search messages 'chat:"Book club" library'

wa personal search messages 'chat:[email protected] library'  # a chat by its id

wa personal search messages 'passport kind:private'  # one-to-one chats only

On WhatsApp, kind:private is a one-to-one chat, kind:group a group, kind:saved the chat with yourself and kind:channel a WhatsApp channel. A person's id is usually …@lid, a group's …@g.us. To search every account in the store, add --source all.

DatesCopy Anchor Link

wa personal search messages 'date:today'

wa personal search messages 'library date:yesterday'

wa personal search messages 'invoice date:7d'    # from 7 days ago until now; also 30m, 2h

wa personal search messages 'invoice date:[2026-01-01 TO 2026-02-01}' --timezone Europe/Madrid

today, yesterday and calendar dates are days in your computer's time zone; --timezone picks another. In a range, [ and ] include that day, { and } exclude it.

Links, phones and addressesCopy Anchor Link

wa personal search messages 'has:link AND "github.com"'  # a link to a site

wa personal search messages 'domain:docs.google.com'

A link counts when it is in the text. To find a phone, an e-mail address, a link's site or a confirmed person mentioned in the text, use phone:, email:, url:, domain: and mentions:; see Mentions.

FilesCopy Anchor Link

wa personal search messages 'has:file chat:"Book club"'
wa personal search messages 'filename:agenda.pdf'
wa personal search messages 'mime:"application/pdf"'
wa personal search messages 'content:"reading list"'

The store keeps each file's name, size and type, so has:file, filename: and mime: work on every message stored since wa handled files. content: finds the text inside a file once that text is read (reading the text of files).

Passwords, codes and cardsCopy Anchor Link

wa personal search messages 'preset:secret kind:saved'  # something that looks like a password or token

wa personal search messages 'preset:card'

A preset finds messages that look like a password, a login code, an API key, a card or IBAN number, a passport, a phone, an email or a link. It checks the shape only: it does not prove that a password works or a card is real. The full list is in the query language.

TagsCopy Anchor Link

wa personal tags add work --chat "Book club"

wa personal tags add work --contact 100000000000001@lid

wa personal tags list tag:work type:chat

wa personal search messages 'tag:work invoice'

wa personal search messages 'invoice NOT tag:work'

wa personal tags remove work --chat "Book club"

A tag is your own label on a chat, a person, one message (--message <id> --chat <chat>) or a task (--task <id-or-key>). It is kept in the local store only and is never sent to WhatsApp. tag:work finds messages tagged work, messages in a chat tagged work and messages from a person tagged work. A tag is 1–32 letters a–z, digits and hyphens.

Groups can be tagged automatically, from their title and description — no messages and no model:

wa personal metadata sync --chat "Book club"  # read the group's description from WhatsApp; the group is not changed

wa personal metadata sync --only-missing  # every stored group with no description read yet

wa personal tags rebuild --dry-run          # what it would tag, without writing

wa personal tags rebuild                    # write the automatic tags

metadata show --chat "Book club" shows what was read, from the store. Channels are not read yet: a channel in the list answers with an error of its own, and the others go on.

Saved searches and historyCopy Anchor Link

wa personal searches create meetings 'library OR cafe' --chat "Book club"

wa personal search messages --saved meetings

wa personal search messages --saved meetings 'date:today'  # extra words are added with AND

wa personal stats messages show --saved meetings --by day

wa personal searches list

wa personal searches history --limit 10

wa personal search messages --saved 42           # a row of the history, by its number

searches create saves a query with its options and runs nothing; an existing name needs --replace. Options you type with --saved replace the saved ones. The saved text is read again on every run, so date:7d always means the last 7 days. searches show prints one, searches delete removes one.

Every search and count that succeeds is written to the history: the query and its options, never the messages it found. The newest 1,000 runs are kept. --no-record keeps one run out of it. searches clear empties the history and keeps the saved searches. This history is separate from the run records of wa personal runs.

Saved searches and the history live in the store that every WireCat CLI shares: tg and max see the same ones, and delete or clear in one changes the others. Tags stay with their account.

Counting: stats messages showCopy Anchor Link

wa personal stats messages show invoice               # how many in each chat

wa personal stats messages show 'date:7d' --by sender

wa personal stats messages show 'from:me' --by day --timezone Europe/Madrid

wa personal stats messages show --by hour             # every stored message

stats messages show counts the messages search messages would find with the same query, each one once. --by chat (the default) and --by sender put the largest first; --by day and --by hour go in order. The numbers count what the store holds, so for a chat held only since linking they are a lower bound.

Messages around a hitCopy Anchor Link

--newest orders by time instead of by relevance, and --context 2 shows two messages before and after each one found (2 in the terminal, 0 otherwise by default).

--thread shows the reply chain and the replies around each hit instead of its neighbours in time. It follows the reply links saved in the store, and in messages context it replaces the neighbours in time too. Defaults are 8 links from the hit, 50 messages, 65,536 bytes and one day either side; change them with --thread-hops, --thread-messages, --thread-bytes and --thread-within. Without saved links it falls back to neighbours in time.

Results as JSONCopy Anchor Link

At a terminal wa prints a readable transcript. --json returns one object with the messages and what was searched; --jsonl streams the messages only, one per line. The fields of the answer are in the query language reference.

When nothing is foundCopy Anchor Link

An empty answer means "not in the store", not "never sent". Check what is stored with wa personal store status. With --json the answer says which chats were searched, even when nothing matched. If wa asks for wa personal store migrate, the word index is still being built; searches without words (date:today, kind:group) already work.

A message from before the device was linked, which the phone did not push, is not in the store. messages sync asks the phone for a chat's older messages (older history); otherwise look for it on the phone.

NextCopy Anchor Link

• Query language: every field, operator, limit and the JSON answer.
• The local store: what it holds, and how to keep it current.
• How search works: the technical page — the word index, the conversation graph and how results are ranked.