Repository navigation
This page helps you bring your email into Memo, so mail sits beside your notes and messages in
search, in a person's context and in the sources your agent reads. The way in is the separate
mail program: mail copies your mailbox into the shared WireCat store, and
Memo searches and shows what is there. Memo never changes your mailbox or sends mail.
Install mail and add your mailbox. Its documentation
lists the steps for each provider, such as the IMAP setting and the app password (a separate password for one program,
which you can revoke at any time).
npm install -g @wirecat/mail-cli
mail personal session start --address me@example.com
mail personal sync
mail personal statuspersonal is a profile name you choose for one mailbox. session start signs in, sync reads the last 30 days into the
shared store, and status shows how far a large mailbox is. Run mail personal sync again to bring in new mail. Memo needs
no setting for this mail: it reads the same store.
mail keeps the text and the headers of each message, not the attachments. See its
documentation for what it keeps and how to keep a
mailbox up to date. Everything about the mailbox itself is mail's too:
-
mail <profile> account inspectgroups a mailbox's mail by sender and list with a spam score, before a big first sync;--domain-ageasks when each sender's domain was registered. -
mail <profile> messages import <file.mbox>adds years of old Gmail from a Google Takeout file to the same mailbox, each email once. -
mail <profile> rules add|list|removedecide which mail is stored whole, as an envelope or not at all.
memo sync and its timer embed the mail mail stored for search by meaning when the search model is
on your computer; --no-embed skips it.
memo search mail 'invoice'
memo messages show <ref><ref> is the ref of a search hit. memo search all finds this mail together with your notes and messages. More
search words are in Find your mail and Search.
memo can run an agent after each sync that stored new mail. It reads only mail past its own mark, and only stages
proposals: tasks, closes and updates of open tasks, facts, memories, links and new contacts. Nothing is created until
you confirm it in memo review. The one thing it does itself is file a sender it is sure only sends newsletters,
promotions or notices as envelopes (mail <profile> rules add): the next sync keeps that sender's mail without its
text. The agent never sends, drafts, moves or deletes mail, never changes or removes a rule, and never decides for
you.
Turn it on once:
memo schedule agent mail-triage claude 'Run memo skill show mail-triage and follow it.' --every 5m --on-new-mail mail-triage --max-cost 1 --max-cost-per-day 5Every 5 minutes the schedule checks the store. With no mail past the mail-triage mark it does nothing: no model
call, no notification. It waits until 10 emails wait for it, or the oldest has waited 30 minutes, so a day of
scattered mail costs a few runs, not dozens. Newsletters, suspicious senders and other mail it would skip do not count.
Once the day's runs have cost 5 US dollars, no run starts until the next day; memo schedule list shows the day's
spend and why it skipped. Change these per schedule with --mail-wait 1h, --mail-batch 20 and
--max-cost-per-day 2, or for every schedule in the config file: schedule_mail_wait, schedule_mail_batch and
schedule_max_cost_per_day (memo config show lists them; a flag wins over the file). When enough mail waits and
the day's budget allows, it starts claude on Sonnet with only memo and mail allowed, under MEMO_READ_ONLY and MAIL_READ_ONLY, and without your MCP servers, skills, settings and
CLAUDE.md: a run starts on about 4,700 tokens instead of 38,000. --model opus picks another model for one schedule,
and schedule_model_claude in the config file for every new one; schedule_lean_start: false loads your setup. Both
apply when the schedule is added, so add it again after changing them. That run may move only the mail-triage mark.
The prompt it follows is memo skill show mail-triage. Its first run starts from now; older mail is not read. A
schedule saved by an older memo allows only memo: run the line above again to replace it.
What it does, per mailbox:
-
memo mail review --holder mail-triage --source email:<account> --jsongives the mail past its mark. Newsletters, envelope rules, drafts, suspicious senders and mail not yet stored whole are left out, and counted. Other mail sent to many — an order, an invoice or a site form with an unsubscribe link — comes last as its subject and first lines (excerpt_only), at most 30 a read; the agent reads one whole when it looks like something for you. A bulk email is a newsletter when words in its subject and first lines, its sender's address, an emoji or an unsubscribe link say so, and no order word in the subject, order number or reply says otherwise; themail_bulk_*settings inmemo config showhold the words, the score and the limits, andmail_bulk_excerpts: falseleaves all bulk mail out. Each email has thefingerprinta finding cites it by, and says whether its sender is new. - It keeps the emails that ask something of you, carry a date, or answer a thread with an open task.
- It reads context for those only, through links the store already has: the thread,
memo contextof the sender. - It stages one batch:
memo mail findings add '<json>' --key <key> --source email:<account>, the JSON as one argument (a file or-for stdin work too) and the key the review gave in itsmail-findings.addstep. A new sender gets a link to a known person, or a new contact proposal only when the email's text gives a better name than the sender line. Aftermessages resetthe key ends in-r<n>, so a run over mail read again stages beside a batch still waiting for you. - Then, and only then,
memo messages acknowledge --holder mail-triage --cursor <cursor> --source email:<account>moves its mark. A run that fails before this reads the same mail again; the same batch is not staged twice. - For a sender not linked to a person, with no open task, whose every email in the run was a newsletter, promotion
or notice, it adds
mail <profile> rules add --sender <address> --do envelope(or--list-id), at most 5 per run, with the address taken from the review's fields, never from the email's text. UnderMAIL_READ_ONLYmail takes only that:--senderor--list-idwith--do envelope, never a rule that replaces one, recorded withsource: agent(mail <profile> rules list source:agent). The report lists the rules it added and the ones it was unsure about, for you to run.
| Command | What it does |
|---|---|
memo mail review --source email:<account> |
Threads with new mail, --unanswered what you owe, --waiting what waits for an answer; --holder <name> reads past that holder's mark |
memo messages acknowledge --holder <name> --cursor <cursor> |
Moves a holder's mark to the cursor its review gave |
memo messages reset --holder <name> --last <n> or --since-time <time>
|
You only: moves a holder's mark back, so it reads that mail again; says how many emails; --dry-run only counts |
memo mail findings add <file> |
Stages one mailbox's findings for you |
memo mail findings list status:proposed |
Batches waiting for you |
memo mail findings show <id> |
One batch with its evidence |
MEMO_READ_ONLY refuses every store change except mail findings add and messages acknowledge. messages reset
is yours alone: it refuses an agent and a scheduled run, and MCP lists it as unavailable (messages.reset is deny). You decide in
memo review: memo review show <id>, then memo review confirm <id>/<finding> or memo review reject <id>. No
agent can confirm or reject mail findings. memo review status shows each mailbox's mark and what waits.
Email bodies go to the model provider of the agent you schedule. Stop it with memo schedule remove mail-triage.
Memo no longer reads a mailbox itself. Its old mail commands change nothing and name their replacement.
<profile> is the mail profile that holds the address; mail session list lists them.
| Old Memo command | Run instead |
|---|---|
memo mail add <account> <address> |
mail <profile> session start --address <address>, then mail <profile> sync
|
memo mail check <account> |
mail <profile> account check |
memo mail inspect <account> |
mail <profile> account inspect, same options, no account |
memo mail rules list|add|remove|apply|export|import <account> … |
mail <profile> rules list|add|remove|apply|export|import …, same options, no account |
memo mail delete <account> |
mail <profile> messages delete --rules (a preview; --yes moves the mail) |
memo mail restore <account> --run <id> |
mail <profile> messages restore --run <id>; Memo's run ids work there |
memo mail runs list <account> |
mail doctor, which names the runs that stopped part way or whose Gmail Trash empties soon; every run is a file <id>.jsonl in Memo's state folder under mail-trash/<profile>/
|
A config that still has Memo's old mail settings loads, and nothing reads them: memo doctor names the mailboxes
they list, for mail to sync, and memo config unset mail removes them. The mail Memo imported stays in the store
and is still found; mail <profile> sync of the same address goes on from it.
memo search mail 'invoice'
memo search mail 'from:kai subject:budget'
memo search mail 'mailbox:starred' --source email:you@example.com
memo search mail 'trip NOT mailbox:bulk'
memo search all 'budget'Mail sent to many — newsletters, notices, mailing lists, anything with a List-Id, List-Unsubscribe or
Precedence: bulk header — is in the mailbox bulk (memo:bulk), so NOT mailbox:bulk leaves it out when it
crowds a search. It is not left out by default: bills, bookings and other notices from companies carry the same
headers. --source email:<address> names one mailbox; --source email:a@example.com,email:b@example.com searches
both.
mail <profile> sync also scores every sender from the mail already stored, at most once a day, the same way
mail <profile> account inspect scores a group. A hit from a scored sender carries sender_score in --json, with the score
and its signals. Mail from a sender whose signs of fraud add up to 3 or more comes after the rest of the page in
memo search mail and memo search all, and its sender_score says demoted: true; nothing is left out. Your own
are never moved: a domain you wrote to anyone at, your mailbox's domain, and a sender a protect rule keeps.
--plain-order keeps such mail where the words put it, to find it:
memo search mail 'invoice' --plain-orderGmail labels such as Inbox, Important, Starred and your own labels become mail folders, so
mailbox:important finds them. See Search.
memo messages show <msg:email/…> prints one email whole. Mail that older Memo versions imported keeps the text
Memo read from each attachment, such as a bill's PDF: the first 4,000 characters of each, or all of it with --full.
Mail synced by mail has no attachment text.
With --before-n and --after-n it also prints that many earlier and later emails of the same thread, oldest
first, with the email you asked for marked anchor: true. The thread is the one the mailbox gives (Gmail's own
thread, or for other mailboxes the first email its References header names). An email alone in its thread, such
as most newsletters, comes back alone.
When you delete an email in your mailbox, its text leaves the store on the next mail <profile> sync, and Memo no
longer finds it.
An address a person's contact already has joins that person by itself. Another address joins them when you link
it: memo people link email:kai@example.com telegram:Kai. Then their mail is part of
their context.
Memo finds phones, e-mail addresses, links, names and street addresses in every stored email, note and document. List them and say what they are:
memo mentions list kind:phone --source email:personal
memo mentions show 40 --source email:personal
memo mentions confirm 40 person:7 --source email:personal
memo mentions reject 41 --source email:personal--source names what to read, the same way in every WireCat tool: email:personal one mailbox, email:personal,email:work
several, mail every mailbox (the answer lists which), notes memo's notes, documents imported documents, and
group:<name> a saved group. show lists the senders who may own a phone, but links nothing until you confirm it.