Skip to content

Glossary

mxr borrows vocabulary from email standards, Gmail, Hey, and IMAP. This page reconciles them so you don’t have to guess.

Runtime: the local daemon and the mailbox state it owns: synced mail, the SQLite store, search index and provider connections. A provider account is one connected mailbox in that runtime. See the architecture guide.

Daemon: the background process for a runtime. The TUI, CLI, web app, HTTP bridge, MCP server, scripts and agents can call the same daemon; each client exposes different operations and may have different authority. mxr autostarts the daemon; mxr daemon runs it explicitly. See the architecture guide.

Client: an interface or caller that uses a runtime, such as the TUI, CLI, web app, MCP server, script or agent. Sharing a daemon shares mailbox state, not client capabilities or permissions.

Adapter: the per-provider code that translates mxr’s internal model to and from a provider’s API or wire protocol. Today: provider-gmail, provider-outlook, provider-imap, provider-smtp, provider-fake. New adapters live in their own crate and pass a conformance test suite.

Internal model: mxr’s provider-agnostic types: Envelope, Thread, Account, Address, Label. Adapters map into this model so application code never speaks Gmail-specific or IMAP-specific dialects.

Every IPC request the daemon serves falls into one of four buckets. The buckets are conceptual, not separate sockets, but they shape what’s stable, what’s user-facing, and what’s an internal hatch.

  • core-mail: read mail, send mail, mutate mail. The settled, stable surface.
  • mxr-platform: accounts, rules, saved searches, subscriptions, semantic runtime. mxr-product features that aren’t strictly mail.
  • admin-maintenance: status, events, logs, doctor, bug reports, local reset, repair. Diagnostic and operational.
  • client-specific: pane-shape, view-model, screen-state. Not part of the daemon contract; clients (TUI and web) shape these themselves.

See Architecture for why this split matters.

Config-backed account: an entry in config.toml under [accounts.<key>]. IMAP/SMTP accounts and Gmail-with-BYOC live here. Editable from the TUI’s Accounts page or by hand.

Provider account: one connected mailbox in a runtime. mxr accounts shows accounts currently available to the daemon; mxr config show shows config-backed entries. An account is not the runtime itself.

Owned address: an address registered locally against an mxr account, used for direction inference and per-message From selection. Registering it in mxr does not create or authorise the address at the mail provider. Manage with mxr accounts addresses.

Lexical search: Tantivy BM25 only. Exact, fast, deterministic. The default mode.

Semantic search: dense retrieval using local embeddings. Useful when you don’t know the keywords. Semantic work is enabled in the built-in config, but lexical search remains the default mode and mxr falls back to lexical when dense retrieval is unavailable. Runs entirely on-device.

Hybrid search: lexical + semantic, fused with reciprocal-rank fusion. Best recall; the keyword-aware default for “I want it to find what I mean.”

Saved search: a named, queryable inbox lens. Lives in the sidebar. Run from the CLI with mxr saved run <name>.

Mutation: an operation that changes mail or provider state, such as archive, trash, label, snooze or send. Preview support depends on the command; check its CLI reference and the automation contract before applying it.

Mutation ID: an operation-specific token returned by some mutations. Use mxr undo only when that operation reports an undo ID and supports undo; the available effects and time window depend on the operation.

Reply-later (a.k.a. bookmark): flag a thread to come back to. Hey’s term is “Reply Later”; it is the first choice, Later, in the b (Not now) picker. The reply queue is browsed with mxr replies or Ctrl-p → Reply Queue.

Snooze: hide a thread until a time. Returns to inbox at the specified moment. Set with mxr snooze --until '<time>' (see time phrases) or a time in the b (Not now) picker.

Screener: Hey-borrowed term for triaging unknown senders into Allow / Deny / Feed / Paper Trail. Anyone you have written to is never in the queue. Allow gives the sender Messages visibility, not automatic reply debt. A directed request can enter New from people until you write to them. Feed sends their mail to Reading; Paper Trail retains the older sender-bundle destination. These are sender decisions, not extra email modes. CLI: mxr screener.

Owed reply: an unanswered directed request from someone you have written to, or an explicit reply-later reminder that has returned: the desk’s You owe lane. Informational mail and acknowledgements do not create a reply obligation. mxr ranks requests by waiting_days / expected_days, where expected_days is your usual reply time. Reachable via mxr owed, the desk, or the TUI sidebar (Owed). The raw set (every thread whose latest message is inbound with no later reply, automated and archived mail included) is mxr owed --all or mxr search 'is:owed-reply'. See the search guide.

Commitment: a promise mxr extracted from your sent mail (e.g. “I’ll send the deck Friday”). Persisted to contact_commitments after every successful mxr send. Browse with mxr commitments --status open. See Forgotten work. You can also keep one yourself with mxr commitments add, or from the offer the web app shows after a send. Open ones due within a week show under Due on the desk.

Desk: a separate four-lane workflow for replies, promises, waiting conversations and new requests from people. It is available through mxr desk; Now is the web app and TUI front page. See Start from Now.

Lane: one section of the desk. You owe (a directed request or returned reply-later timer), Due (a promise you made is coming due), Waiting on (you wrote last and they have not answered), New from people (a directed request from someone you have not written to). The rules are in the desk reference.

Done: puts a desk row away. You owe and New from people are archived and marked read; Waiting on is marked read and set aside; a Due promise is marked kept. The row stays away until someone writes in the conversation again. CLI: mxr desk done, previewed with --dry-run, reversed with mxr undo.

Promise: the desk’s and web app’s word for a commitment you made in mail you sent. When you send one with a date, mxr offers to remind you. See Reply to everyone you owe.

Focus & reply: a web workflow that shows everyone you owe a reply one conversation at a time, with the reply beside it. See Reply to everyone you owe.

Paper trail: a retained compatibility name for the older sender-bundle view and its CLI command. The current workflow uses the five modes: Updates groups notifications, while Archive holds sourced records. See Reading and Paper trail.

Sender kind: where a sender’s mail goes, set once with mxr sender kind or Move sender: people, reading, paper-trail, screened-out, or auto (the rules decide). Stored as the sender’s screener decision. mxr why MESSAGE_ID says which rule placed a message.

Sweep: archive everything unpinned in a place, or in one sender’s bundle there, after a preview. CLI: mxr sweep, reversed with mxr undo.

Pin: keeps a message in place when you sweep. Local to this machine; not a provider star. CLI: mxr pin, mxr unpin.

Low tide: what the web app shows when the desk is clear: “Low tide. Nobody’s waiting on you.”

Time phrase: a time typed in words, such as fri 3 or in 2d, accepted wherever mxr asks for a time. Preview one with mxr time. See time phrases.

mxr’s current email workflow has five shipped modes over one shared mailbox. See Email is five apps at once for their jobs and completion actions. Terms marked (planned) describe future work, not current behavior.

Mode: one of the five jobs email does, each with its own view, unit and verbs: Messages, To do, Updates, Reading and Archive. One email can be in several modes at once; mxr modes why says which and why. Messages, To do, Updates, Reading and Archive are built.

Messages: the mode for people you are in conversation with (mxr messages, g m). One row per person, merged across their addresses, with your conversations inside as topics; a group thread is its own row. See Messages.

Your turn: their latest message to you is unanswered. The same rule feeds Now’s People. A turn nobody took goes quiet after three times your usual interval with them, at least a week.

Copied thread: a thread you were only copied on, or one sent to more than 10 people, that you never wrote in. It goes to Updates, not Messages.

New text: what a message says that its thread didn’t already, with quoted history and signature removed. Marked “trimmed” when anything was removed; o shows the message as sent.

Got it: a short acknowledgement reply in your own greeting and sign-off, sent after a visible countdown you can undo (., mxr messages ack).

Merge (people): making several addresses one person, always by hand. mxr suggests a merge when two addresses you’ve written to share a name.

To do: the mode for things you must act on, each titled as an instruction (“Pay council tax”) with a due date and an act-by date (mxr todo, g x).

Updates: the mode for notifications (mxr updates, g u), read as a briefing by source at fixed cuts and let go in one key. See Read Updates as a briefing.

Digest: Updates’ batch: everything that arrived by the latest cut and wasn’t let go, one line per source in Needs a look, Changed and Routine.

Cut: a fixed time of day the digest is gathered, 08:00 and 16:30 by default (updates.cuts, one to four times). Mail after the cut waits in “arriving for” until the next one.

Source line: one line in the digest for everything one source sent, its latest fact per kind of message, with the numbers it quoted and the change code computed against the previous message of that kind.

Tracker: a thing with a state shown where it is now: a parcel, a build or an incident. A tracker that ends well leaves Updates on its own; one that ends badly moves to Needs a look.

Suggested to-do: an update that leads Needs a look with a highlighted line saying why: a new sign-in, a failed payment, a delivery problem, or any message from a source tuned to breakthrough. t adds it, and the line then shows “already in To do”. An alert also explains why automatic creation was held. Current live providers do not supply the receiving verdict mxr requires for automatic alert creation.

Reading: the mode for newsletters and posts you chose (mxr reading, g r), shown as an edition: readable items in three bands, ranked by what you read, with no unread count.

Edition: Reading’s front page: since you were last here, earlier this week and fading. A digest’s links are items of their own and a teaser’s item is its article.

Fade: how long a Reading item stays: twice its source’s usual gap between issues, from 2 to 14 days. Fading is done in Reading only; the email stays in your inbox and in search.

Later: Reading’s shelf of items you chose to keep. It never fades, and its count is the only one Reading shows. b in the apps, mxr reading later on the command line.

Highlight: a passage saved from the reader with ", or made in Marginalia and read back. Found by search and exported with mxr reading export --markdown.

Archive (mode): records such as receipts, orders and bookings, with an answer box that returns the field you asked for (mxr records, g e). Not the same as the archive action, which removes mail from your provider’s inbox: toasts say “Filed in Archive” for a record and “Archived in Gmail” for the provider action. See Archive.

Now: the front page across the modes, at most ten items in four fixed sections (mxr now, g h). See Start from Now.

Rail: the sidebar’s list of Now, the five modes and Inbox, with their g keys (mxr modes rail).

Quiet: Messages’ last band: people you marked done here, or whose turn went quiet. Person mail still in your inbox stays in Messages until you mark it done there, so it never vanishes from every mode.

Inbox: everything in arrival order. It remains an all-mail view outside the five modes.

Handoff: passing an item from one mode to the next, such as making a to-do from a message (t), filing an email in Archive (X then e), or a ticked-off bill or a delivered parcel’s order filing itself in Archive. The toast names where the item went.

Done here: finishing an item in one mode without clearing it from the others (e, mxr modes done). When the last inbox-holding mode lets go, the provider email may be archived if modes.archive_on_last_done is enabled; preview the command to see its effect. The desk’s own Done is a separate lane action.

Reason: the explanation for an email’s placement. Use mxr why MESSAGE_ID to inspect the reason and available evidence for the installed version. See Messages.

Correction: telling mxr an email is in the wrong mode. Preview a per-email correction with mxr reclassify MESSAGE_ID MODE --dry-run; use --sender when the choice should apply to that sender’s mail. See Start from Now.

Fast tier (planned): proposed model-assisted work for every incoming message. Current mode placement is deterministic; fast is not a shipped configuration key or model path.

Smart tier (planned): proposed model-assisted extraction for selected mail. It is not a shipped configuration key or model path. See the LLM features guide.

Index recipe: what each mode indexes for semantic search. Archive’s ships: one field chunk per record email plus its PDF text. The other modes’ recipes, such as one fact per Updates message, are planned.

Let go: Updates’ and Reading’s word for done. In Reading it is e, or E for everything in the edition, which acts on exactly the set its preview listed. Letting go of an Updates digest does the same (mxr updates let-go).

Act-by date: the last day you can act and still meet a due date, such as three working days before a bill paid by bank transfer. To do surfaces an item ahead of its act-by date, not its due date.

Record: Archive’s unit, built from one or more emails: an order’s confirmation, dispatch and delivery are one record. Kinds: receipt, order, booking, invoice, statement, ticket, contract, warranty and account.

Trip and series: records grouped by Archive. A trip is bookings whose dates overlap or come within a day of each other; a series is statements from one issuer in at least three different months.

Subscription: receipts or invoices from one issuer for one product that come at a steady cadence (weekly, monthly, quarterly or yearly). Archive works it out from the records, with the next charge, the yearly cost, price changes and whether it is active, overdue or ended.

Checked: a record whose every amount and date came from schema.org markup or from you. A value read by a rule shows an open dot until you confirm it (,, mxr records fix --confirm).

mxr gates every send through a seven-check pipeline before any provider call.

Verdict: the rollup decision from the safety pipeline: Safe (no issues), Warn (one or more Warnings, no Blockers), or Blocked (at least one Blocker). The CLI mxr send --check exits 0 on Safe/Warn and exit code 2 on Blocked.

Issue: a single finding from one check. Has a code (WrongRecipient, MissingAttachment, ReplyAll, PiiSecret, ToneMismatch, AnswerCoverage, UnfilledGap, plus structural codes like NoRecipients), a severity (Info, Warning, Blocker), a message, optional detail/citations, and an override_token for Blockers.

Override token: a single-use, draft-scoped token that bypasses Blocker issues for one send. Minted when a safety check finds a Blocker, either during mxr send --check or a refused send. Use it with the revision, original expected_workspace JSON and operation ID from the saved-draft preview: mxr send DRAFT_ID --expected-revision REVISION_FROM_PREVIEW --expected-workspace '<OWNER_JSON_FROM_PREVIEW>' --operation-id OPERATION_ID_FROM_PREVIEW --override-safety TOKEN_FROM_CHECK. Subsequent attempts with the same token fail. Editing the draft and adding a new Blocker kind invalidates the token.

Safety audit: every safety run is persisted to draft_safety_runs (verdict + redacted issues). Every override consumption is persisted to draft_safety_overrides. PII is never persisted raw, only redacted previews.

External agent model: the reasoning model selected by a coding-agent host. It is separate from mxr’s native model configuration; mail returned to a hosted agent can leave the machine through that host’s model service. See For agents and LLM features.

mxr-native model feature: a model-backed operation configured through [llm], disabled by default and optionally overridden per feature. The built-in assistant uses the native assistant feature configuration.

Native synthesis returns suggestions or answers; the built-in assistant can also call mutation tools under its approval rules. Synthesis from message evidence is citation-backed, while deterministic profile fallbacks may return no citations. See archive intelligence, briefings and loop-in, and timing and cadence.

Archive ask: mxr ask "<question>" runs a hybrid (or lexical, or semantic) retrieval over your local mail and synthesizes a Markdown answer with cited message ids. The daemon rejects any LLM citation that points outside the retrieved set; “not enough evidence” is a valid answer.

Citation: a structured reference to source evidence. Briefing citations use { message_id?, thread_id?, field, quote }; whois and archive-answer surfaces carry their own cited evidence shapes. LLM-backed synthesis validates citations against the candidate set before trusting them.

Decision log: mxr decisions is a queryable ledger of explicit decisions extracted from threads (“we agreed on Postgres”). Rows are stable across rebuilds: id = hash(account, thread, normalized_decision, evidence_ids). Rebuild with mxr decisions rebuild --since N, idempotent on unchanged threads.

Thread briefing: mxr briefing thread <id> is a cached, citation-backed recap of a dormant thread (default threshold: 30 days). Synthesized from the local thread transcript, cached in context_briefings, and invalidated when the thread’s message ids/dates change. Force regenerate with --refresh.

Recipient briefing: mxr briefing recipient <email> is the same cached briefing primitive scoped to a person. Its deterministic baseline includes known interaction counts and last inbound/outbound dates; the LLM can turn that baseline into prose when enabled. The TUI compose flow surfaces it as a quiet hint after a long gap; never auto-inserts into the draft.

Cadence watchlist: relationship_watchlist is an explicit, account-scoped table of “relationships I chose to maintain”. mxr cadence watch <email> --every <N>d adds a row; mxr cadence drift lists watched contacts whose interval has drifted past expected. mxr never auto-watches contacts.

Send-time recommendation: mxr send-time <recipient> computes the recipient’s reply-latency bucket from local reply_pairs. Statistical, no LLM. Fires as a non-blocking hint inside mxr send --check when the proposed slot is at least 2× slower than the best window and confidence is medium or high.

Maybe include: mxr suggest-recipients --draft <id> proposes Cc candidates who co-participate on similar prior threads. Hard rules: minimum support of 3 distinct threads, no self-suggestions, Bcc is never leaked, existing recipients excluded.

Expert: mxr expert <message-id> or --query "<text>" ranks locally cited answerers of similar questions, not askers. Citations point at answer messages: replies that follow a question, contain explanatory content, and are followed by thanks or no further unresolved ask.

Whois entity: mxr whois <name|email|term> looks up a person or free-text term using only locally cited mail evidence. Project names currently use the free-text term / ambiguous path. Query-time only: there is no persisted entities table in v1. Ambiguous queries return candidates, not a synthesized definition.

Delivery: a tracked package distilled from shipping mail. A local heuristic (carrier/merchant senders, shipping subjects, schema.org markup, checksum-valid tracking numbers) shortlists candidates; an optional LLM step confirms and extracts merchant/carrier/items/ETA; a lifecycle layer collapses an order’s many emails into one row whose status only advances and resolves on “delivered”. Browse with mxr deliveries or TUI tab 7. source is schema, llm, or heuristic. See the Deliveries guide.

Reader mode: strips signatures, quoted text, tracking pixels, and remote-image references for distraction-free reading. Toggle with R.

Plain text first: mxr renders text/plain bodies if they exist, falling back to HTML→text only when needed. HTML remote images are controlled by render.html_remote_content; with it on, the TUI and CLI fetch every image the HTML points at, tracking pixels included. Only the web app filters: it drops images that declare a width or height of two pixels or less, plus images from known tracker hosts.

Label: Gmail’s primary classification primitive. A message can have many labels.

Folder: IMAP’s primary classification primitive. A message lives in exactly one folder. mxr’s Label type carries a LabelKind::Folder variant so IMAP folders don’t get flattened into Gmail-style labels, preserving the semantic difference is important. mxr move is the verb that operates on folder semantics; mxr label is for label-style multi-membership.

Provider ID: the provider’s own message identifier. Gmail’s is stable; IMAP’s is mailbox-scoped and may change across moves/copies. mxr stores it on Envelope.provider_id for round-trips back to the provider.

Sync: pulling new mail and applying remote changes locally. Triggered automatically every [general] sync_interval seconds, or on demand with mxr sync.

Indexing: populating Tantivy from new SQLite records. Always runs as part of sync; lexical search is fresh as soon as a sync batch commits. Semantic chunks are persisted but not embedded unless [search.semantic] enabled = true.

Reset / Burn: mxr reset --hard and its alias mxr burn destroy local runtime state (the daemon, the database, the search index). They preserve config.toml and credentials by default. Use --including-config to also drop the config; pair with --dry-run to preview.