Google Workspace Integration

Sync Gmail and Google Drive into governed memory — read-only.

The Google Workspace connector pulls Gmail messages and Google Docs into Cortex as governed, searchable memories. It is read-only: Cortex requests only the gmail.readonly and drive.readonly scopes and never writes back to your account.

How it works

Unlike GitHub and Slack (which push events via webhooks), Google has no webhook for the content Cortex ingests. Instead, a scheduled pull fetches what changed since the connector's last sync:

Connect (OAuth)

Authorize Google Workspace from Connectors (or onboarding). Cortex stores a read-only access + refresh token for your workspace.

Periodic sync

A cron job (POST /api/cron/connectors) runs on a schedule. For each connected workspace it fetches recent Gmail messages and recently-modified Google Docs since the stored cursor.

Ingest → memory

Every item is routed through the same governed pipeline as all other memories: scope + clearance assignment, embedding, vector + knowledge-graph storage, conflict detection, and audit. It becomes recallable immediately.

Setup

1. Create a Google Cloud OAuth client

  1. In Google Cloud Console, create a project.
  2. APIs & Services → Library → enable Gmail API and Google Drive API.
  3. OAuth consent screen → External; add your test users while in Testing.
  4. Credentials → Create OAuth client ID → Web application.
  5. Add the redirect URI: 
    https://<your-app>/api/connectors/google/callback

2. Set environment variables

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

3. Connect

From Connectors (or onboarding step 1), click Connect on Google Workspace and complete the Google consent screen. The scopes shown will be read-only Gmail + Drive.

The .readonly scopes are the only access Cortex ever requests. There is no code path that writes to Gmail or Drive.

What gets ingested

SourceBecomesDefault scopeCategory
Gmail messageOne memory per email (subject + body)public-docsEmail
Google DocOne memory per doc (exported text)public-docsDocument

Each memory carries a citation back to the original message or document, so any answer that uses it links to its source.

Scheduling the sync

Cortex ships the endpoint + secret but doesn't run a scheduler itself. The recommended option is Upstash QStash (creds already reserved as QSTASH_TOKEN) — a one-time setup registers the schedules:

npx tsx scripts/setup-qstash-schedules.ts

Or point any scheduler (Render Cron Job, GitHub Actions) at the endpoint every ~15 minutes:

curl -X POST https://<your-app>/api/cron/connectors \
  -H "x-cron-secret: $CRON_SECRET"

The workspace owner can also trigger an immediate sync:

POST /api/connectors/google/sync   # CEO-only

Disabling

Disconnect from Connectors in the dashboard. The stored tokens are cleared and no further syncs run.