This guide helps developers connect memory trace data with Google Calendar by converting structured JSON to .ics files and syncing them using the Google Calendar API.

​
Overview

This module enables end-to-end calendar integration:
  • Converts memory traces (JSON) to .ics files
  • Authenticates Google Calendar access
  • Syncs events from .ics to the user’s Google Calendar

​
Setup Instructions

​
1. Create Google Cloud Project

Google Cloud Console: https://console.cloud.google.com/
  • Select or create a project
  • Navigate to APIs & Services → Library
  • Enable Google Calendar API

​
2. Enable Calendar API

Follow the official quickstart guide:
https://developers.google.com/calendar/api/quickstart/python

​
3. Create OAuth 2.0 Credentials

  • Go to APIs & Services → Credentials
  • Click + CREATE CREDENTIALS → OAuth client ID
  • If prompted to configure the consent screen:
    • Choose “External”, click “Create”
    • Fill in App name, support email, contact info
    • Click “Save and Continue” through remaining steps
  • On OAuth creation page:
    • Application type: Desktop App
    • Name: Calendar Sync Local
    • Click “Create”

​
4. Download and Store Credentials

  • After creation, download the JSON file
  • Save as: calendar/credentials.json
  • Add to .gitignore: calendar/credentials.json calendar/token.json

​
Run the Sync Script

From the project root: 
python modules/calendar_io/sync_google_json.py
On first run:
  • Auth flow opens in browser
  • On success, token.json is generated
  • Future runs reuse the token unless revoked

​
Python Module Overview

​
authenticate_google()

Handles the full OAuth authentication lifecycle:
  • Loads existing token from calendar/token.json if available
  • Falls back to browser-based auth via InstalledAppFlow
  • On success, stores updated credentials for reuse

​
convert_json_folder_to_ics(input_dir, output_dir)

  • Parses each .json memory file in input_dir
  • Validates traces via validate_memory_trace(trace)
  • Generates .ics format VEVENT strings
  • Outputs .ics calendar files to output_dir
Example Data I/O: 
input_dir = Path("data/conversation/raw")  
output_dir = Path("data/conversation/processed")  
convert_json_folder_to_ics(input_dir, output_dir)

​
parse_ics_and_sync(ics_path, service)

  • Parses .ics file using ics.Calendar
  • Builds Google Calendar payloads
  • Sends each event to Google Calendar using: service.events().insert(calendarId="primary", body=payload).execute()
  • Prints status and error messages

​
Security & Best Practices

  • Never commit credentials.json or token.json to version control
  • Rotate or revoke OAuth tokens as needed
  • Log sync actions for debugging and traceability