Email-to-Brain: Gmail Messages That Update Your Brain
Emails arrive. Brain pages get smarter. The agent reads your inbox, detects entities, updates person and company pages, extracts action items, and files everything with source attribution.IMPORTANT: Instructions for the Agent
You are the installer. Follow these steps precisely. The core pattern: code for data, LLMs for judgment. Email collection is split into two layers:- DETERMINISTIC: code pulls emails, generates Gmail links, detects noise/signatures. This never fails. Links are always correct. Timestamps are always accurate.
- LATENT: you (the agent) read the collected emails and make judgment calls. Who is important? What entities are mentioned? What action items exist?
- Step 1 validates the credential gateway. Without it, nothing connects to Gmail.
- Step 2 sets up the collector. Without it, you have no emails to analyze.
- Step 3 does the first collection. Without data, Step 4 can’t enrich.
- Step 4 is YOUR job: read the digest, update brain pages.
Architecture
Opinionated Defaults
Noise filtering (deterministic, in collector):- Skip: noreply@, notifications@, calendar-notification@
- Flag: DocuSign, Dropbox Sign, HelloSign, PandaDoc (signatures needing action)
- Keep: everything else
- Work email (company domain)
- Personal email (gmail.com)
- Signatures pending (DocuSign etc. needing action)
- Messages to triage (real emails from real people)
- Noise (filtered, available if needed)
[Open in Gmail](https://mail.google.com/mail/u/?authuser=ACCOUNT#inbox/MESSAGE_ID) — these are generated by code, never by the LLM, so they are always correct.
Prerequisites
- ModusBrain installed and configured (
modusbrain doctorpasses) - Node.js 18+ (for the collector script)
- Gmail access via one of:
- ClawVisor (recommended: E2E encrypted credential gateway)
- Google OAuth credentials (direct API access)
- Hermes Gateway (built-in Gmail connector)
Setup Flow
Step 1: Validate Credential Gateway
Ask the user: “How do you access Gmail programmatically? Options:- ClawVisor (recommended, handles OAuth and encryption)
- Google OAuth credentials (you manage tokens yourself)
- Hermes Gateway (if you’re using Hermes Agent)“
Option A: ClawVisor (recommended)
Tell the user: “I need your ClawVisor URL and agent token.- Go to https://clawvisor.com
- Create an agent (or use existing)
- Activate the Gmail service
- Create a standing task with purpose: ‘Full executive assistant email management including inbox triage, searching by any criteria, reading emails, tracking threads’ IMPORTANT: Be EXPANSIVE in the task purpose. Narrow purposes like ‘email triage’ will cause legitimate requests to fail verification.
- Copy the gateway URL and agent token”
Option B: Google OAuth2 directly
Tell the user: “I need Google OAuth2 credentials for Gmail access. Here’s how:- Go to https://console.cloud.google.com/apis/credentials (create a Google Cloud project if you don’t have one)
- Click ’+ CREATE CREDENTIALS’ > ‘OAuth client ID’
- If prompted, configure the OAuth consent screen:
- User type: External (or Internal for Google Workspace)
- App name: ‘ModusBrain Email’ (anything works)
- Scopes: add ‘Gmail API …/auth/gmail.readonly’
- Test users: add your own email address
- Create the OAuth client ID:
- Application type: Desktop app
- Name: ‘ModusBrain’
- Copy the Client ID and Client Secret
- Also enable the Gmail API: Go to https://console.cloud.google.com/apis/library/gmail.googleapis.com Click ‘Enable’”
Step 2: Set Up the Email Collector
Create the collector directory and script:- collect — pull emails from Gmail via credential gateway, deduplicate by message ID, store as JSON with Gmail links baked in
- digest — generate a markdown digest from collected emails, grouped by: signatures pending, messages to triage, noise
- state tracking — remember last collection timestamp and known message IDs to avoid re-processing
- Gmail links are generated by CODE, not by the LLM. Format:
[Open in Gmail](https://mail.google.com/mail/u/?authuser=ACCOUNT#inbox/MESSAGE_ID) - Noise filtering is deterministic: noreply, notifications, calendar invites
- Signature detection uses known patterns: DocuSign envelope, Dropbox Sign, HelloSign, PandaDoc
- All state persisted to
data/state.json(last collect timestamp, known message IDs) - Output is structured JSON (machine-readable) AND markdown digest (agent-readable)
Step 3: Run First Collection
ls data/digests/ should show today’s digest file.
Read the digest. Confirm it contains real emails with working Gmail links.
Step 4: Enrich Brain Pages
This is YOUR job (the agent). Read the digest. For each email:- Detect entities: who sent it? Who is mentioned? What companies?
- Check the brain:
modusbrain search "sender name"— do we have a page? - Update brain pages: if sender has a brain page, append a timeline entry:
- YYYY-MM-DD | Email from {sender}: {subject} [Source: Gmail, {date}] - Create new pages: if sender is notable and has no page, create one
- Extract action items: if the email requires a response or action, log it
- Sync: run
modusbrain sync --no-pull --no-embedto index changes
Step 5: Set Up Cron
The collector should run every 30 minutes:Step 6: Log Setup Completion
Implementation Guide
These are production-tested patterns. Follow them exactly.Noise Filtering (Deterministic)
notifications@slack.com matches because
notifications@ is in the pattern list. Order doesn’t matter.
Signature Detection
Gmail Link Generation (CRITICAL)
authuser parameter is CRITICAL. Without it, the link opens in the default
Gmail account, not the right one. Each email record stores its account separately.
Generate these in CODE, never by the LLM. Links must be 100% reliable.
Deduplication
What the Agent Should Test After Setup
- Noise filtering: Send a test email from
noreply@test.com. Run collect. Verify it appears in noise section, not triage section. - Gmail links: Click a link from the digest. Verify it opens the correct account (not the default one).
- Deduplication: Run collect twice in 1 minute. Verify no duplicate messages.
- Sent mail: Reply to an email manually. Run collect. Verify the thread is marked as replied-to in the digest.
Cost Estimate
Troubleshooting
No emails collected:- Check ClawVisor health:
curl $CLAWVISOR_URL/health - Check standing task is active and has Gmail service enabled
- Check task purpose is expansive enough (narrow purposes block requests)
- Verify the
authuserparameter matches the account email - Gmail links require being logged into the correct Google account
- Check
data/messages/for JSON files - All emails might be filtered as noise — check noise filtering rules