Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtimelabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to sync memory trace data with the native macOS Calendar using AppleScript. This approach supports local iCloud-synced calendars without requiring API credentials or cloud setup.

​
Overview

This module enables local calendar integration on macOS:
  • Converts memory traces from JSON into AppleScript-formatted events
  • Writes directly to the local Calendar app (e.g., iCloud-synced “Home” calendar)
  • Requires no external API or OAuth setup

​
Requirements

  • macOS with Calendar app installed
  • Python 3.8+
  • AppleScript (osascript) available on macOS terminal
  • A local calendar named Home (or any custom calendar name you specify)

​
Run the Sync Script

From the project root: python modules/calendar_io/sync_mac_calendar.py This will:
  • Load a memory trace file (JSON format)
  • Parse each memory item
  • Convert to AppleScript and invoke via osascript
  • Log success or errors per event

​
Python Module Overview

​
memory_trace_to_applescript(trace, calendar_name=“Home”)

  • Parses a memory trace with a UTC timestamp
  • Formats start/end time in AppleScript-compatible string
  • Constructs a detailed event:
    • summary: Derived from trace type and content
    • description: Includes full trace content and metadata (task ID, importance, etc.)
  • Returns a valid AppleScript string to be executed

​
create_event(trace, calendar_name)

  • Runs osascript to create an event via AppleScript
  • Handles escaping and formatting internally

​
sync_memory_file_to_mac_calendar(memory_json_path, calendar_name)

  • Loads a full .json session (with list of memory traces)
  • Validates each trace using your schema
  • Creates events one-by-one
  • Logs number of successfully synced events and any failures
Example: memory_path = Path(“data/conversation/raw/lab_manager_4-12.json”)
sync_memory_file_to_mac_calendar(memory_path)

​
Security & Best Practices

  • Events are only written to local calendars—no external access is required
  • Validate your calendar_name exists in macOS Calendar before syncing
  • Use validate_memory_trace() to guard against invalid input or format drift

​
Limitations

  • Only runs on macOS (due to reliance on AppleScript)
  • No two-way sync (events created in Calendar are not reflected back to memory traces)
  • Execution may be rate-limited by system AppleScript policies if abused