---
name: email-graph-sweep
description: "Enable or disable a recurring, per-account routine that reads new inbound mail and recent session transcripts, writes the mail's organisations/people/jobs into the graph deduped, proposes preferences/notes/task-intents from the transcripts to the review queue, and reports over a persistent channel on every fire. Triggers on 'set up an automatic email sweep', 'turn my email into the graph automatically', 'enable the recurring mail to graph routine', 'schedule a mailbox sweep', and the disable equivalents ('stop the automatic email sweep', 'disable the mailbox sweep'). Opt-in, mailbox-dependent, channel-bound; it is not the silent always-on graph maintenance routine."
---

# Email to graph sweep

This skill turns one account's recent activity into graph knowledge on a schedule, from two sources: new inbound
mail, and recent session transcripts. It is the automatic sibling of the `sweep-workflow` skill, which does the
same read-and-surface work only when the operator asks.

The two sources are handled differently, on purpose. Mail entities (organisations, people, live jobs) are
written directly, deduped against the graph, the way `sweep-workflow` proposes but here without waiting.
Session-derived insights (preferences, notes, task intents) are only proposed to the operator's review queue,
never written on the fire, because a scheduled turn runs inside the untrusted-inbound reframe where auto-writing
inferred user intent is not safe. So the fire writes mail facts and proposes session insights.

It messages the operator's persistent channel on every fire. It is a proactive report, not a background-only
job. The silent, always-on graph-maintenance half is the dream-cycle; this is the noisy, opt-in,
mailbox-dependent half. There is no silent variant of this routine, by design (see Refusal discipline).

This skill adds no tool. Enable and disable are calls to the `scheduling` plugin's `schedule-event`,
`schedule-list`, and `schedule-cancel`. The extraction itself runs later, as the scheduled agent turn this
skill arms, using the mail-read, graph-write, and conversation-archive tools that turn holds.

## When to use

The operator asks to switch the routine on or off for their account. Enable triggers are "set up an automatic
email sweep", "turn my email into the graph automatically", "schedule a mailbox sweep". Disable triggers are
"stop the automatic email sweep", "disable the mailbox sweep". This is per-account and opt-in. It is never
auto-provisioned and never fleet-wide.

## Enable

Run two gates in order before arming anything. A gate that fails names its reason and stops. Do not soften a
failed gate into a silent or a webchat routine.

### Gate A, mailbox

The account must have a mailbox connector this session can read. Name the surface by capability, never by one
provider: a generic IMAP mailbox is read with `email-read` and `email-search`; a Microsoft 365 mailbox
is read with `outlook-mail-list` and `outlook-mail-search`. If neither pair of tools is loaded in this session,
there is no mailbox to sweep. Emit `op=preflight-refused` with `reason=no-mailbox` and `channel=none` (no
channel has been named yet), tell the operator no mailbox is connected and that connecting one is the
prerequisite, and stop.

### Gate B, channel

The routine delivers its report over a persistent channel, so the operator must name the destination that
receives it: a WhatsApp phone in E.164 form, or a Telegram chat id. That destination must already be a
registered admin or account-manager on the socket-owning house account. This is not a check this skill
re-implements: `schedule-event` already enforces it at creation and refuses a destination that is not
registered (`not-registered`) or is registered to a different account (`cross-account`). Treat either refusal
as this skill's `reason=no-channel`: emit `op=preflight-refused` with `reason=no-channel` and `channel` set to
the destination the operator named, tell the operator which case they hit (their number is not registered as an
admin or manager, or it is registered under a different account), and stop. Do not add
a new tool to enumerate registered destinations; the creation-time preflight is the gate.

First guard against a double-enable. `schedule-event` always creates a fresh event and never merges on the
event name, so calling it twice would arm two identical series. Before arming, call `schedule-list` and check
whether an event named `Email→graph sweep` is already `scheduled` for this account. If one is, the routine is
already on: tell the operator so, do not create a second, and stop.

With both gates passed and no existing series, call `schedule-event` once with:

- `name`: `Email→graph sweep`. This is the event's title field on the tool, and this exact string is how
  disable finds the series, so do not vary it. (The tool's parameter is `name`, not `title`.)
- `startDate`: an ISO 8601 datetime for the first run, normally the next occurrence of the cadence or the
  current time from the `<datetime>` block. `startDate` is required and seeds the recurring event's first
  `nextRun`; the `recurrence` cron governs every run after it.
- `recurrence`: a cron expression. Default to weekday morning, `0 8 * * 1-5`. Use the operator's cadence if
  they gave one.
- `agentDispatch`: `{ channel, destination, prompt }` with the channel and destination from Gate B and the
  canonical prompt below as `prompt`.
- `sessionKey`: the current session key, so the event links to the conversation that enabled it. `schedule-event`
  anchors every write to the calling session's conversation, so pass this to satisfy that anchor.

A recurring event that carries an `agentDispatch` fires the prompt as an admin turn on the destination's
channel each cycle, and the turn's answer is delivered back over that channel. That delivered answer is the
report, so the prompt ends by asking the turn to make its final answer a short report.

On success emit `op=enable` with `reason=ok`.

### Canonical prompt

Arm this text verbatim as the event's `agentDispatch.prompt`:

> Do two passes over this account's recent activity since the last run, a mail pass and a session pass.
>
> Mail pass. Read the new inbound mail on this account's mailboxes using whichever mail tools are loaded
> (`email-read`/`email-search`, or `outlook-mail-list`/`outlook-mail-search`). From that mail, identify
> organisations, people, and live jobs. Before writing anything, check each candidate against the existing graph
> with `memory-search` and `contact-lookup`; an organisation, person, or job the graph already holds is not
> written again. Write only the genuinely new entities, through the tool that owns each: `contact-create` for a
> new person or organisation, `work-create` for a live job, `memory-write` for a standing fact.
>
> Session pass. Read this account's recent conversation transcripts since the last run: find the
> `:ConversationArchive` nodes touched since then with `memory-search`, and page their chunks with
> `conversation-archive-list-chunks`. Reading each chunk, identify statements that express a user preference, a
> durable note, or a task intent. For each, emit a claim of kind `preference`, `note`, or `task` with a
> near-verbatim evidence snippet, and hand the claims for that chunk to `conversation-archive-derive-insights`;
> it returns operator-facing proposals and drops any the operator has already rejected. Do not wire these
> proposals. Unlike the mail entities above, which you write directly, these session-derived proposals go to
> review, not a silent write: list them in your report (the kind, the proposed action, and the evidence snippet)
> so I can wire or reject them later through the conversation-archive-enrich flow.
>
> Do not send any mail or message. Make your final answer a short plain report in two parts: what you wrote from
> the mail pass (counts and names), and what you are proposing for review from the session pass (counts and a
> line each), because that answer is delivered to me over this channel.

Deduping hard is what makes a second fire quiet. On the mail pass, entities written on the first run are found by
the graph dedupe check on the next, so they are not written twice. On the session pass, `derive-insights` dedupes
a preference against its `OBSERVED_IN` evidence trail and a note or task against its content hash, and its
rejection ledger drops anything the operator already triaged, so a proposal the graph already holds or the
operator already rejected does not re-surface. There is no separate read cursor.

## Disable

Call `schedule-list`, find every `scheduled` event whose `name` is exactly `Email→graph sweep` (the list
returns the title in the `name` field), and `schedule-cancel` each one by its id. Cancelling a recurring event
kills the whole series. Cancel all matches, not just the first, because a past double-enable can leave more than
one armed. Emit `op=disable` with `reason=ok`. If no event with that name is armed, tell the operator the routine
was not enabled and stop.

## Refusal discipline

A failed gate is a stop, not a fallback. This routine has exactly one shape: a scheduled agent turn that reports
over a persistent channel. A silent or report-only scheduled sweep, and a sweep that reports into the webchat,
were proposed and closed unbuilt by design; do not re-open that path here. If the account has no
mailbox or no registered channel destination, the routine cannot be built for it, and saying so plainly is the
correct outcome.

## Caveats to state to the operator

1. It reports on every fire. The operator will get a message on their channel each cycle, whether or not the run
   found anything new. This is a proactive report, not a silent background job.
2. Each fire arrives inside the untrusted inbound reframe wrapper, and the routine's own instructions land in the
   turn's untrusted `## Context` zone. That is the failure mode: a security-cautious turn can cancel its
   own scheduled job and narrate a breach. The session pass proposes rather than writes precisely to keep inferred
   user intent out of a silent write under that reframe, but the mail pass still auto-writes inside it, so the hold
   stands: it is tolerable for a single account whose operator deliberately enabled the routine and understands it,
   but this routine must not be recommended broadly until (an out-of-`## Context` provenance marker that
   grounding trusts) lands.

## What this skill does not do

- It is not core and not auto-provisioned. It is enabled per account, only when both gates pass.
- It is not the dream-cycle, which is the silent, always-on graph-maintenance routine.
- It adds no new dispatch surface. It does not report into the webchat or fire silently, closed
  unbuilt).
- It keeps no read cursor. "Since the last run" is bounded by the cadence and enforced by graph dedupe.

## Observability

Emit one line per lifecycle action, so an enable, a disable, or a refusal is visible with its reason:

```
[email-graph-sweep] op=enable|disable|preflight-refused accountId=<8> channel=<ch> reason=<no-mailbox|no-channel|ok>
```

Use the first 8 characters of the account id. On a refusal, `channel` is the destination the operator named, or
`none` if the routine stopped at Gate A before a channel was given. Each fire after enable is recorded by the
schedule dispatch itself (`lastDispatchResult` and `lastDispatchAt` on the event) and audited by the heartbeat
(`[schedule-audit] op=stale-dispatch`), so a destination that stops being a registered admin or manager between
enable and fire surfaces there with its true reason.