Skip to main content

Calendar-to-Brain: Your Schedule Becomes Searchable Memory

Every calendar event becomes a searchable brain page. Your agent knows who you’re meeting tomorrow, what you discussed last time, and what context matters. Meeting prep happens automatically because the brain already has the history.

IMPORTANT: Instructions for the Agent

You are the installer. Follow these steps precisely. Why this matters: Calendar data is the richest source of relationship history. 13 years of calendar data tells you who you’ve met with, how often, where, and with whom. When someone emails you, the brain already knows your meeting history. When you have a meeting tomorrow, the agent pulls attendee dossiers automatically. The output is daily markdown files: One file per day at brain/daily/calendar/{YYYY}/{YYYY-MM-DD}.md with all events, attendees, and locations. These files are the foundation for meeting prep, relationship tracking, and pattern detection. Do not skip steps. Verify after each step.

Architecture

Opinionated Defaults

Multiple calendar accounts:
  • Work calendar (company domain)
  • Personal calendar (gmail.com)
  • Previous company calendars (if still accessible)
Daily file format:
All-day events listed first. Timed events sorted by start time. Cancelled events are skipped. Attendee names extracted (no email addresses in output). Calendar label in parentheses. Location with 📍 emoji. Historical backfill: Sync years of calendar data, not just recent. Common ranges:
  • Work: 2020-present
  • Personal: 2014-present This builds the full relationship graph from day one.

Prerequisites

  1. ModusBrain installed and configured (modusbrain doctor passes)
  2. Node.js 18+ (for the sync script)
  3. Google Calendar access via ONE of:
    • Option A: ClawVisor (recommended, handles OAuth for you, no token management)
    • Option B: Google OAuth2 directly (you manage tokens, no extra service needed)

Setup Flow

Step 1: Choose and Configure Calendar Access

Ask the user: “How do you want to connect to Google Calendar? Option A: ClawVisor (recommended) ClawVisor handles OAuth, token refresh, and encryption. You never touch Google credentials directly. If you already use ClawVisor for email, this uses the same setup. Option B: Google OAuth2 directly Connect to Google Calendar API directly. No extra service needed, but you manage OAuth tokens yourself. Good if you don’t want another dependency.”

Option A: ClawVisor Setup

Tell the user: “I need your ClawVisor URL and agent token.
  1. Go to https://clawvisor.com
  2. Create an agent (or use existing)
  3. Activate the Google Calendar service
  4. Create a standing task with purpose: ‘Full calendar access for historical backfill and ongoing sync. List events, read event details, search across all calendars.’ IMPORTANT: Be EXPANSIVE in the task purpose. Narrow purposes block requests.
  5. Copy the gateway URL and agent token”
Validate:
STOP until ClawVisor validates.

Option B: Google OAuth2 Setup

Tell the user: “I need Google OAuth2 credentials. Here’s exactly how to set them up:
  1. Go to https://console.cloud.google.com/apis/credentials (create a Google Cloud project if you don’t have one)
  2. Click ’+ CREATE CREDENTIALS’ at the top, select ‘OAuth client ID’
  3. If prompted, configure the OAuth consent screen first:
    • User type: External (or Internal if you have Google Workspace)
    • App name: anything (e.g., ‘ModusBrain Calendar’)
    • Scopes: add ‘Google Calendar API …/auth/calendar.readonly’
    • Test users: add your own email
  4. Back on Credentials, create the OAuth client ID:
    • Application type: Desktop app
    • Name: anything (e.g., ‘ModusBrain’)
  5. Click ‘Create’. You’ll see the Client ID and Client Secret.
  6. Copy both and paste them to me.
Also enable the Calendar API: 7. Go to https://console.cloud.google.com/apis/library/calendar-json.googleapis.com 8. Click ‘Enable’” Validate the credentials are set:
Then run the OAuth flow to get an access token:
STOP until OAuth flow completes and tokens are stored.

Step 2: Identify Calendar Accounts

Ask the user: “Which Google Calendar accounts should I sync? Common setup: For each account, note:
  • Email address
  • Start year (how far back to sync)
  • Label (Work, Personal, etc.)

Step 3: Set Up the Calendar Sync Script

Create the sync directory:
The sync script needs these capabilities:
  1. Paginated event retrieval — Google Calendar API returns max 50 events per request. The script must paginate through large date ranges. Use monthly chunks for sparse periods, weekly for dense ones.
  2. Daily markdown generation — group events by date, format as markdown with times, attendees, locations, calendar labels
  3. Merge with existing files — if a daily file already has manual notes, preserve them when updating calendar data
  4. Index generation — create INDEX.md with date ranges, event counts, monthly summary
  5. Raw JSON preservation — save raw API responses to .raw/ for provenance

Step 4: Run Historical Backfill

This is the big initial sync. It may take 10-30 minutes depending on how many years of calendar data you have.
Tell the user: “Syncing calendar history from [start year]. This creates one markdown file per day. For 4 years of data, expect ~1,400 daily files.” Verify:
Should show daily files like 2026-04-01.md, 2026-04-02.md, etc.

Step 5: Import Calendar Data to ModusBrain

Verify:
Should return calendar pages with event details.

Step 6: Attendee Enrichment

This is YOUR job (the agent). For each person who appears in calendar events:
  1. Check brain: modusbrain search "attendee name" — do they have a page?
  2. Create page if missing: notable attendees (appears 3+ times) get a brain page
  3. Update existing pages: add meeting history to timeline: - YYYY-MM-DD | Meeting: {event title} [Source: Google Calendar]
  4. Relationship tracking: note meeting frequency in compiled truth: “Met 12 times in last 6 months. Regular 1:1 cadence.”

Step 7: Set Up Weekly Sync

The calendar should sync weekly to stay current:
After sync, import new data:

Step 8: Log Setup Completion

Tell the user: “Calendar-to-brain is set up. You have [N] days of calendar history indexed. I can now prep you for meetings by pulling attendee context from the brain. Weekly sync keeps it current.”

Implementation Guide

These are production-tested patterns from syncing 13 years of calendar data.

Smart Chunking (Monthly vs Weekly)

Why: Monthly chunks for sparse years (2014-2023) = ~96 API calls for 8 years. Weekly for everything would be ~600+ calls. Per-calendar startYear avoids pulling empty months (e.g., don’t query 2014-2020 for a calendar created in 2020).

Attendee Filtering

Without this, your attendee list is polluted with “Conference Room A” and “engineering-all@company.com”. You want actual people.

Merge with Existing Files (Preserve Manual Notes)

Critical: Only touch ## Calendar. Everything else is preserved. If you manually added ## Notes to a daily file, it survives re-sync.

Date/Time Parsing Edge Cases

What the Agent Should Test After Setup

  1. Monthly vs weekly: Run from 2014 with dense_after=2023. Verify pre-2023 makes ~12 API calls per year, post-2023 makes ~4 per month.
  2. Attendee filtering: Create a meeting with a conference room and a mailing list. Sync. Verify neither appears in the daily file.
  3. Merge preservation: Add ## Notes to a daily file manually. Sync calendar. Verify notes are preserved.
  4. All-day events: Create an all-day event and a timed event on the same day. Verify all-day appears first, timed events sorted by start time.
  5. Cancelled events: Cancel a meeting. Sync. Verify it doesn’t appear.
  6. Per-calendar startYear: Sync a calendar created in 2022 with startYear=2022. Verify no API calls for years before 2022.

Cost Estimate

Troubleshooting

No events returned:
  • Check the calendar account email is correct
  • Check ClawVisor has Google Calendar service activated
  • Check the standing task purpose is expansive enough
  • Some calendars may be empty for the requested date range
Attendee names missing:
  • Google Calendar sometimes returns email addresses instead of display names
  • The sync script should extract the display name from the attendee object
  • If no display name, use the email prefix (before @)
Duplicate events:
  • The sync script should be idempotent (same date range = same output)
  • If running multiple times, existing daily files are overwritten (not appended)