> ## 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.

# iCalendar Integration

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