Google Calendar

​

What It Does

• One Google account, one Cognee user. Whoever completes the consent owns the credential, and the account’s events are indexed into that user’s memory. Personal and Workspace accounts take the same path and are told apart by the hosted-domain claim (account_type: workspace or personal).
• Read-only. The requested scopes are openid email https://www.googleapis.com/auth/calendar.readonly — Cognee never creates, changes or deletes events.
• Its own grant. Like Google Drive and Gmail, Google Calendar is a separate provider with its own settings and its own consent, so disconnecting one never revokes the others.
• Opt-in by calendar. A new connection selects nothing, and there is no “all calendars” selection. No events are read until you choose calendars explicitly and start a sync.
• Incremental and deletion-aware. Each calendar keeps its own sync token; later syncs fetch only what changed, and deleted events — as well as every event of a calendar you deselect — are forgotten.

​

Prerequisites

• A Cognee backend on v1.6.5 or later.
• The google-calendar extra installed on that backend:
  pip install "cognee[google-calendar]"
  
  It pulls in google-api-python-client, google-auth and google-auth-oauthlib, which the sync builds its Calendar client with.
• A Google Cloud project with the Google Calendar API enabled.

​

Setup

​

1. Create the Google Cloud OAuth client

​

2. Configure Cognee

​

3. Connect

curl -X POST https://<your-host>/api/v1/integrations/google_calendar/authorize \
  -H "Authorization: Bearer <your-cognee-token>"
# {"authorizeUrl":"https://accounts.google.com/o/oauth2/v2/auth?...&access_type=offline&prompt=consent"}

​

Choosing Calendars

curl https://<your-host>/api/v1/integrations/google_calendar/resources \
  -H "Authorization: Bearer <your-cognee-token>"

curl -X PUT https://<your-host>/api/v1/integrations/google_calendar/resources \
  -H "Authorization: Bearer <your-cognee-token>" \
  -H "Content-Type: application/json" \
  -d '{"resourceIds": ["jane@example.com", "team@group.calendar.google.com"]}'

​

Syncing and Status

curl -X POST https://<your-host>/api/v1/integrations/google_calendar/sync \
  -H "Authorization: Bearer <your-cognee-token>"
# {"accepted": true}

• Only the first sync reads each calendar in full. The connector keeps one sync token per selected calendar; later syncs ask Google only for what changed. A calendar whose token has expired is listed again in full and reconciled against what was stored. Adding a calendar to the selection backfills just that calendar.
• Deletions are forgotten. A deleted event is removed from memory on the next sync. A calendar that was synced before and has since left the account’s calendar list (deleted or no longer shared) has its events forgotten too.
• One failing calendar doesn’t block the others. When one calendar fails, the others still finish and save their sync tokens; the failed one keeps its previous state and is retried on the next sync. An authentication error or a rate limit ends the whole run, since the remaining calendars would fail the same way.
• One sync per account at a time. While a sync is running, another /sync call returns {"accepted": false} and does nothing. The guard lives in the API process, so a deployment with several workers needs its own queue or lock.
• Nothing refreshes on its own. There are no Calendar webhooks and no built-in scheduler. Call /sync again, or from your own scheduler, to pick up new events.

import cognee

results = await cognee.recall(
    "When did I last meet the vendor, and who attended?",
    datasets=["google_calendar_jane_example_com_3f2a1b9c4d"],
)

# List calendars and the connection status
uv run python examples/guides/google_integration_sync.py google_calendar

# Select a calendar and start a sync
uv run python examples/guides/google_integration_sync.py google_calendar --resource-id CALENDAR_ID

​

Token Lifecycle and Disconnect

# Revoke the connection, keep the indexed events
curl -X DELETE "https://<your-host>/api/v1/integrations/google_calendar/connection" \
  -H "Authorization: Bearer <your-cognee-token>"

# Revoke it and forget the account's google_calendar_… dataset as well
curl -X DELETE "https://<your-host>/api/v1/integrations/google_calendar/connection?delete_data=true" \
  -H "Authorization: Bearer <your-cognee-token>"

​

Limitations

• No “all calendars” selection. List the calendars you want explicitly; a calendar added to the account later is not picked up until you add it to the selection.
• No automatic refresh. /sync is the only thing that updates memory.
• One Cognee user per Google account. Connecting an account that another user already holds is refused with error_already_connected.
• Attachments and conference details beyond the meeting link are not ingested.
• calendar.readonly is a sensitive scope, so public distribution needs Google’s OAuth verification.

​

Related