Google Workspace Connector
Ingest Gmail, Drive, and Calendar activity into CortexDB.
Tails Gmail messages, Drive documents and comments, and Calendar events, and writes them to CortexDB as experiences.
Two ways to run this connector
Self-hosted — pip install 'cortexdb-connectors[google-workspace]' then cortexdb-sync sync google-workspace. Managed — CortexDB runs the connector as a worker. See the
Connectors overview.
1. Prepare credentials
Create a service account in Google Cloud, enable domain-wide delegation, and grant it the Gmail / Drive / Calendar read scopes in the Workspace admin console. Download the service-account key JSON, and choose a user to impersonate (delegated access).
What gets written
Gmail threads, Drive docs + comments, and Calendar events each become a POST /v1/experience on the
resolved scope (default org:<org>/source:google-workspace), with entity references and metadata
(source_url, thread / document / event ids).
Record keys and threads
- The internal
idempotency_keyis the record id, not version-aware:gmail:<message_id>,drive:<shared_drive_id|my-drive>:<file_id>,calendar:<calendar_id>:<event_id>. Edits still land as new events because the wire key hashes the content (see below). - Drive comments link to their document via a
thread=…label, notcontext.preceded_by.
The key on the wire is derived
The key format above is this connector's internal record identity: it decides which source record an
event belongs to. The idempotency_key actually sent to CortexDB is a derived cxsrc:<56 hex> value
that also hashes the content, labels, observed time and actor, so an unchanged redelivery converges on
the same event while any edit lands as a new one, even where the key format itself is not
content-versioned. Every event also carries a source descriptor with the record's fingerprint. See
Source identity and keys.
Run it yourself
pip install 'cortexdb-connectors[google-workspace]'
pip install cortexdb-cli && cortexdb init
export GW_SERVICE_ACCOUNT_KEY=/path/to/service-account.json # required
export GW_DELEGATED_USER=you@acme.com # required (impersonated user)
cortexdb-sync --api-url http://localhost:3141 sync google-workspace
cortexdb-sync --api-url http://localhost:3141 watch google-workspace --interval 300GW_SERVICE_ACCOUNT_KEY may be a path to the JSON key file (or its contents). Cursor state persists in
~/.cortexdb/sync_state.json.
Optional settings
Set these as environment variables (or the matching keys in the cortexdb-sync YAML config). Lists are comma-separated. For on/off settings, 1, true, yes or on turns the setting on and any other value turns it off.
| Setting | What it does | Default |
|---|---|---|
GW_GMAIL | Sync Gmail | On |
GW_DRIVE | Sync Drive | On |
GW_CALENDAR | Sync Calendar | On |
GW_SHARED_DRIVES | Shared drive IDs to include | None |
GW_CALENDARS | Calendar IDs to sync | primary |