> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Memory

> Ask one question across your Google Calendar, Gmail and Drive, and walk into each client meeting knowing which orders are late and what to say

Your calendar knows who you meet, your inbox knows what went wrong, and your Drive knows what you promised. One memory holds all three, so a single question connects a meeting to the courier's email and the order sheet behind it.

## What You'll Build

Your primary Google Calendar, your newest Gmail inbox emails and one Google Drive folder go into one cognee memory. An agent then answers one question across them. By default it prepares your client meetings of the next seven days: which orders are late or at risk, why, and what to tell each client. Google is read-only: nothing is created, changed or sent.

Building the memory takes three `cognee.remember` calls, one per app, and answering takes one `cognee.recall` call.

The complete cookbook is
[`examples/cookbooks/google_workspace_memory/`](https://github.com/topoteretes/cognee/tree/dev/examples/cookbooks/google_workspace_memory).

## Try It on Sample Data

The sample is Ana Novak's week. She runs Birchwood Ceramics, which makes tableware for restaurants. She meets Harbor Café in two days and Olive & Fig in four. A courier delayed Harbor Café's dinner plates past their menu launch, and a back-ordered sage glaze puts Olive & Fig's pasta bowls at risk. You need only an [LLM key](/setup-configuration/llm-providers), no Google account.

```bash theme={null}
git clone https://github.com/topoteretes/cognee.git && cd cognee
uv sync
echo 'LLM_API_KEY="your-key"' >> .env
```

`LLM_API_KEY` alone is enough for OpenAI, cognee's default for both the LLM and the embeddings. Other providers, such as Anthropic, Gemini, Azure OpenAI, AWS Bedrock or a local model through Ollama, need a few more lines in the same `.env`: [LLM Providers](/setup-configuration/llm-providers#provider-setup-guides) and [Embedding Providers](/setup-configuration/embedding-providers#provider-setup-guides) list them for each provider. Set both, because embeddings you leave at the default still need an OpenAI key.

**Terminal**

```bash theme={null}
uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py --sample
```

**Coding agent**

The cognee repo ships a skill for this cookbook, [`.agents/skills/google-workspace-memory/SKILL.md`](https://github.com/topoteretes/cognee/blob/dev/.agents/skills/google-workspace-memory/SKILL.md). Claude Code and Codex find it on their own when you open them in the cognee folder. Ask in plain words, or type `/google-workspace-memory` in Claude Code:

```text theme={null}
Use my Google Workspace memory to prepare my client meetings of the coming week.
```

With no Google OAuth client set up, it runs on the sample and tells you the answer is about sample data. Once your account is set up, the same request reads your real calendar, inbox and Drive folder; the skill runs `--check` first, tells you what is missing, and never creates credentials for you.

The run prints one line per step: `[clear]` forgets the sample's dataset from an earlier run, or says there is nothing to forget yet, then `[ingest_calendar]`, `[ingest_gmail]` and `[ingest_drive]` report 4 sample calendar events, 4 sample emails and 1 sample Drive file. `[ask]` prints the question, then the answer after `[ask] Answer:`.

A correct answer lists both meetings. For Harbor Café, it names order BC-1042, the dinner plates, delayed by the courier past the menu launch. For Olive & Fig, it names BC-1043, the pasta bowls held up by the back-ordered glaze. The meetings come from the calendar, the promised dates and statuses from the orders sheet in Drive, and the reasons from the courier's and the supplier's emails. Your wording will differ from run to run.

## Run It on Your Data

Calendar, Gmail and Drive all read through one Google OAuth client. Each app is optional: pass `--no-calendar`, `--no-gmail` or `--no-drive` to skip one, and the answer draws on the others.

**Google Calendar**

The cookbook reads every event of your primary calendar, past and future, through cognee's [Google Calendar connector](/integrations/dlt-integration#google-calendar-connector). Create the OAuth client here once; Gmail and Drive use the same one.

1. In the [Google Cloud Console](https://console.cloud.google.com/), create or pick a project and enable the **Google Calendar API**, the **Gmail API** and the **Google Drive API**.
2. In **Google Auth Platform → Audience**, add your own Google account as a test user.
3. In **Data Access**, add the three read-only scopes: `calendar.readonly`, `gmail.readonly` and `drive.readonly`.
4. In **Clients**, create a client of type **Desktop app** and download its JSON file.
5. Save it as `credentials.json` in the cookbook folder, next to `google_workspace_memory.py`.

The first run opens a browser so you can allow read access, then writes `calendar_token.json` next to `credentials.json`.

**Gmail**

The cookbook reads your newest inbox emails through cognee's [Gmail connector](/guides/gmail-ingestion), with the client from the Google Calendar tab. No extra Google setup is needed beyond the Gmail API and the `gmail.readonly` scope added there.

The first run opens a browser for consent and writes `gmail_token.json`.

**Google Drive**

The cookbook reads one Drive folder and its subfolders through cognee's [Google Drive connector](/guides/google-drive), with the client from the Google Calendar tab.

1. Open the folder in Google Drive and copy the ID at the end of its URL.
2. Add it to `.env` at the repo root: `GOOGLE_DRIVE_FOLDER_ID="..."`.

Docs export as text and Sheets as CSV (first sheet only). PDFs and text files are read too, up to 25 MB each; other file types are skipped. `GOOGLE_DRIVE_INCLUDE_SUBFOLDERS` and `GOOGLE_DRIVE_MAX_FILE_SIZE_MB` in `.env` change these defaults. The first run opens a browser for consent and writes `drive_token.json`.

* Install the Google client libraries with `uv sync --extra gmail --extra google-drive --extra google-calendar`.
* `credentials.json` and the `*_token.json` files are git-ignored. Never commit them.

```bash theme={null}
uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py --check
uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py
uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py --ask "What did Leo ask me about last week?"
```

`--check` reports what is missing without doing any work. The first run opens the browser three times, once per app. It reads your whole primary calendar and cognifies each event with your LLM, so a calendar with a few hundred events can take ten minutes or more. Later runs fetch only what changed in Calendar and Drive and skip the emails cognee already holds; add `--clear` to forget the dataset first and start over. Each script also runs alone, for example `uv run python examples/cookbooks/google_workspace_memory/scripts/ask.py --ask "..."`.

## How It Works

### Step 1: Start From an Empty Memory

Source: [`scripts/clear.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/google_workspace_memory/scripts/clear.py)

This step forgets what an earlier run remembered. It runs only with `--clear`, which a sample run turns on by default; `--no-clear` keeps the dataset.

```python theme={null}
await clear(args.sample)
```

The sample is dated relative to today, so each day's sample differs from yesterday's. Without this step, a second run would add today's meetings next to yesterday's. cognee's part is one call: [`cognee.forget(dataset=...)`](/core-concepts/main-operations/forget), which deletes the dataset and everything extracted from it. `args.sample` switches every step to the sample's own dataset, `google_workspace_memory_sample`, so the sample never mixes with your data in `google_workspace_memory`.

### Step 2: Remember Your Calendar

Source: [`scripts/ingest_calendar.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/google_workspace_memory/scripts/ingest_calendar.py)

This step saves every event of your primary calendar, past and future, so the agent knows who you meet and when. It runs unless you pass `--no-calendar`.

```python theme={null}
await ingest_calendar(args.sample)
```

cognee's part is one call: [`cognee.remember`](/core-concepts/main-operations/remember) with `google_calendar_source(["primary"])` as the input and `node_set=["calendar"]`. `remember` turns each event, with its organizer and attendees, into a knowledge graph, so the same client links across meetings. A [*node set*](/core-concepts/further-concepts/node-sets) is a tag on what you remember, so you can later recall from that part alone. `write_disposition="merge"` with `primary_key="id"` merges events by id, so a rerun updates them instead of storing them twice.

### Step 3: Remember Your Inbox

Source: [`scripts/ingest_gmail.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/google_workspace_memory/scripts/ingest_gmail.py)

This step saves the newest 50 emails in your inbox, not your whole mailbox. Pass `--emails N` to change how many. It runs unless you pass `--no-gmail`.

```python theme={null}
await ingest_gmail(args.emails, args.sample)
```

cognee's part is one call: `cognee.remember` with `gmail_source(label_ids=["INBOX"], max_results=count)` and `node_set=["email"]`. A capped read is a snapshot of your inbox, so it uses `write_disposition="replace"`: emails that left the newest N are forgotten, and memory holds your inbox as it is now.

### Step 4: Remember Your Drive Folder

Source: [`scripts/ingest_drive.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/google_workspace_memory/scripts/ingest_drive.py)

This step saves the Docs, Sheets, PDFs and text files in the folder `GOOGLE_DRIVE_FOLDER_ID` and its subfolders, such as your orders sheet. It runs unless you pass `--no-drive`.

```python theme={null}
await ingest_drive(args.sample)
```

cognee's part is one call: `cognee.remember` with `google_drive_source(folder_id, auth_mode="oauth")` and `node_set=["drive"]`, merged by file id like the calendar. Every ingest step passes `self_improvement=False`, so no [`improve`](/core-concepts/main-operations/improve) pass runs after each app; the question in the next step reads the graph directly.

### Step 5: Ask Across All Three

Source: [`scripts/ask.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/google_workspace_memory/scripts/ask.py)

This step answers one question across your calendar, inbox and Drive. Without `--ask`, it prepares your client meetings of the next seven days.

```python theme={null}
await ask(args.ask, args.sample)
```

The agent is one [`cognee.recall`](/core-concepts/main-operations/recall) call with `query_type=SearchType.HYBRID_COMPLETION` over the cookbook's [*dataset*](/core-concepts/further-concepts/datasets), the named memory everything went into. `HYBRID_COMPLETION` gives the LLM the matching source passages and the graph around them in one call, so a meeting, an email and a sheet row about the same client meet in one answer. The script puts today's date in front of the question, so "next seven days" and "late" are measured from today.

## Make It Yours

* **Ask your own question.** Pass `--ask "Which clients have I not met in a month?"`, or change `DEFAULT_QUESTION` in `scripts/ask.py` to the question you ask every Monday.
* **Read a different label or more mail.** Change `label_ids=["INBOX"]` in `scripts/ingest_gmail.py` to a support or sales label, or raise `--emails`. See [Gmail Ingestion](/guides/gmail-ingestion) for the connector's options.
* **Ask one app at a time.** Recall with `node_name=["email"]` to answer only from your inbox, or `["drive"]` only from your files. [NodeSet Grouping](/guides/nodeset-grouping) shows how scoping works.
* **Draft the follow-up email.** Keep steps 1–4 and add a step after `ask` that recalls the meeting answer and drafts one email per client. Same memory, a different application.

## Clean Up

```bash theme={null}
uv run cognee-cli forget --dataset google_workspace_memory
uv run cognee-cli forget --dataset google_workspace_memory_sample
```

To start over completely, also delete `sample/` and the `*_token.json` files in the cookbook folder.

## Through a Cognee Server

The steps above read Google from your machine with your own OAuth client. When cognee runs as a server for several people, the server can hold the Google OAuth clients instead. Each user connects their account once in the browser, and the server syncs each app into that account's own dataset. `--api` drives that flow:

```bash theme={null}
uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py --api --check
uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py --api
```

With `--api`, `run()` replaces steps 1–5 with one line:

```python theme={null}
await ask_api(args.ask, await sync_api(apps(args)))
```

[`scripts/sync_api.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/google_workspace_memory/scripts/sync_api.py) selects your primary calendar, the `INBOX` label and the folder `GOOGLE_DRIVE_FOLDER_ID` through `PUT /api/v1/integrations/<provider>/resources`, replacing any calendars, labels or folders you selected before, and the next sync forgets what they held. It starts each sync with `POST .../sync` and polls `GET .../connection` until `lastSyncedAt` changes. `ask_api` in [`scripts/ask.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/google_workspace_memory/scripts/ask.py) then sends the same question to `POST /api/v1/recall` across the synced datasets. `--sample` and `--clear` stop the run with a `[setup] MISSING` line, and `--emails` is ignored: the server's datasets are its own, and Gmail syncs the whole label.

* `COGNEE_API_TOKEN` (your bearer token) and `COGNEE_API_URL` (default `http://localhost:8000`) go in `.env` at the repo root, along with `GOOGLE_DRIVE_FOLDER_ID` unless you pass `--no-drive`.
* The server needs, per app (`GOOGLE_CALENDAR_*`, `GOOGLE_GMAIL_*`, `GOOGLE_DRIVE_*`), a `CLIENT_ID` and `CLIENT_SECRET` from a Google OAuth client of type *Web application*, a `REDIRECT_URI` (`<server>/api/v1/integrations/<provider>/callback`), a `STATE_SECRET` and a `FRONTEND_BASE_URL`. It also needs `INTEGRATION_CREDENTIALS_KEYS` (and `INTEGRATION_CREDENTIALS_ACTIVE_KEY_ID` when the active key's id isn't `1`) to encrypt the stored Google tokens. The [Google Calendar](/integrations/google-calendar-integration), [Gmail](/integrations/gmail-integration) and [Google Drive](/integrations/google-drive-integration) integration pages cover each one.
* Connect each app in the browser, never in the script: the server accepts only a consent that finishes in the browser that started it. Connect Drive and Gmail on the cognee UI's Integrations page. Calendar has no card there yet: in the same browser, open the server's `/docs`, call `POST /api/v1/integrations/google_calendar/authorize`, and open the `authorizeUrl` it returns. `--api --check` reports each app that is not connected yet.

> **[Personalized Email](/cookbooks/personalized-email)**
>
> Build another one: email replies that remember your meetings and how you write.

> **[Google Drive Ingestion](/guides/google-drive)**
>
> How the Drive connector syncs a folder and forgets deleted files.

> **[Gmail Ingestion](/guides/gmail-ingestion)**
>
> How the Gmail connector reads your mailbox.

> **[NodeSet Grouping](/guides/nodeset-grouping)**
>
> Tag memories by source and recall from one part at a time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.