How Armbrain keeps your client minds up to date with email context, even when you are not using your AI - no manual ingestion, no stale sessions, no cold starts.
Why Background Polling?
Standard email ingestion (see Email Ingestion) runs when you open your AI. That means emails arriving overnight, on weekends, or during back-to-back meetings pile up. Sessions start with stale context, requiring a wait for batch ingestion.
Background polling fixes this. Once you connect your Gmail, Armbrain checks for new emails automatically every few minutes - even when your AI is closed. Recent emails are stored as client memories before your next session.
This matters most when:
- You start a session Monday morning and need full weekend context immediately
- A client sends a decision or approval at 2am and you prep a meeting brief at 8am
- You onboard a new client and need their recent email history captured without a manual batch import
How It Works
- You connect your Gmail to Armbrain (one-time setup)
- A background process checks for new emails every few minutes
- Each email is matched to the correct client mind using sender/recipient addresses and company domains
- Memories are extracted and stored - decisions, commitments, preferences, campaign outcomes
- When you open your AI, the context is already fresh
The polling runs on Armbrain's cloud infrastructure. Your machine does not need to be on, and your AI does not need to be open.
Connecting Your Gmail
Run this in Claude:
"Connect my Gmail for background polling"Armbrain will return a URL. Open it in your browser, sign in with Google, and authorize read-only access to your Gmail. Once you approve, Armbrain confirms the connection and polling begins within a few minutes.
What permissions are requested: Read-only access to Gmail. Armbrain never sends, deletes, or modifies your emails.
First poll: The first time it runs, Armbrain pulls the last 7 days of email. After that, it only fetches new messages since the last check.
Checking Polling Status
Ask Claude:
"What's the status of my email ingestion?"The status report now includes background polling information alongside the standard ingestion details:
| Field | Description |
|---|---|
| Connected accounts | Which email accounts are connected for polling |
| Last poll | When emails were last checked in the background |
| Polling status | Active, paused (due to errors), or disconnected |
| Emails ingested (recent) | Count of emails pulled in since last session |
| Pending attribution | Emails from unknown senders waiting for review |
How Emails Are Attributed
Background polling uses the same attribution logic as standard ingestion:
- Known contacts - Sender email matched against stakeholder records on your client minds
- Company domains - Sender domain matched against
company_info.domainon client minds - Outbound emails - When you are the sender, recipients are matched against client minds instead
This last point is important: your sent emails (recommendations, strategy advice, commitments) are captured too, not just inbound messages.
Emails from unknown senders
When an email does not match any client mind, it is not silently dropped. It is held in a pending queue and counted in your status report. Emails from new contacts are kept. Add them as stakeholders on the client mind.
What Gets Filtered Out
The same filters apply as standard email ingestion:
- Auto-replies and out-of-office messages
- Newsletters and marketing emails (detected by
List-Unsubscribeheaders) - Calendar invitations
- Automated notifications (from
noreply@addresses) - Duplicate messages already ingested
Managing Your Connection
Disconnect
"Disconnect my Gmail from background polling"Polling stops immediately. Previously ingested memories remain in your client minds.
Reactivate after errors
If polling pauses due to repeated authentication errors (for example, you changed your Google password), you will see it in the status report. To fix it:
"Reactivate my email polling"If the issue was transient (a temporary Google outage), this resumes polling. If the issue is an expired or revoked token, Armbrain will ask you to reconnect by running the setup flow again.
Reconnect
If your Google authorization was revoked (you removed access in Google Account settings, or changed passwords):
"Connect my Gmail for background polling"Running the connection flow again replaces the old authorization.
Polling Frequency
Background sync is best-effort rather than an exact delivery schedule. When the connector pipeline is enabled, it checks for due work every minute and gives each Gmail connection a seven-minute minimum interval. The legacy rollback path wakes about every three minutes and checks one connected account at a time, so its per-account interval grows with the number of accounts in the rotation.
Each mailbox check processes up to 10 new emails. If you have a large backlog, it drains automatically over subsequent cycles.
Background polling currently supports Gmail only. Outlook/Microsoft 365 mailboxes can still be ingested through the in-session Email Ingestion path (via a connected Outlook MCP), just not through the 24/7 background poller yet.
Security and Privacy
- Read-only access. Armbrain can only read your emails. It cannot send, delete, or modify them.
- Encrypted credentials. Your Gmail token uses AES-256-GCM envelope encryption. Encryption keys are stored separately in Cloudflare Workers secrets. Access to the database alone is therefore not enough to read the raw token.
- Client isolation. Every email is validated against client mind ownership before storage. An email attributed to Client A cannot end up in Client B's client mind.
- Source text is retained for provenance and safe retries. Armbrain stores the email text in the private, client-isolated
raw_documentsrecord alongside the extracted memories. This lets it deduplicate messages, retry incomplete extraction, and show where a memory came from.
Relationship to Standard Email Ingestion
Background polling and standard (in-session) email ingestion complement each other:
| Feature | Standard Ingestion | Background Polling |
|---|---|---|
| Requires your AI open | Yes | No |
| Trigger | Session start, meeting prep, manual | Automatic (every few minutes) |
| Email access | Via your email MCP | Direct Gmail API |
| Setup | Just need an email MCP connected | One-time Gmail authorization |
| Coverage | Only when you are using your AI | 24/7 |
If you have both set up, deduplication ensures emails are never processed twice. Background polling handles the continuous baseline, and standard ingestion catches anything from the current session.
Troubleshooting
Polling shows as "paused" or "error"
Check your status report. If the error type is:
- Auth error - Your Google authorization may have expired. Run
"Connect my Gmail for background polling"to re-authorize. - Transient error - A temporary issue (Google outage, network timeout). Polling retries automatically on the next cycle. No action needed.
Emails are not appearing in the correct client mind
Make sure the sender's email address or company domain is associated with the right client mind. Add stakeholder contacts:
"Set stakeholders for Acme: Sarah Chen (sarah@acme.com, VP Marketing)"Pending attribution count is growing
This means emails are arriving from addresses Armbrain does not recognize. Review who is emailing you and add them as stakeholders on the appropriate client minds.
I changed my Google password
Re-authorize by running the connection flow again:
"Connect my Gmail for background polling"