macOS-only local context collector for Apple apps
Mac Context for ISTM is a local-first context collector for Apple Mail, Notification Center, Reminders, and Calendar. It is deliberately separate from Codex Context for ISTM: this repository has no bridge integration, network client, model dependency, account sync, telemetry, or remote service.
The Swift package target, mac-istm command, default local data path, and LaunchAgent label retain their existing technical names so a public product rename does not break scripts, builds, installed agents, or existing local state.
The verified reference environment on 2026-07-24 was GPT-5.6 Sol with reasoning effort xhigh. That reference is documentation only: the collectors are model-independent and run without an AI model.
| Source | Collection surface | Stored fields | Default behavior |
|---|---|---|---|
| Apple Mail | Read-only JXA/Apple Events query | unread-message subject and received time | enabled when selected |
| Calendar | EventKit | title, start, end | enabled when selected and authorized |
| Reminders | EventKit | title, creation time, due time | enabled when selected and authorized |
| Notification Center | supplied SQLite database, query-only | generic event label and delivery timestamp only | disabled until --notification-db is supplied |
The collector never stores Mail sender addresses, bodies, attachments, recipients, mailbox names, message IDs, Calendar notes/locations/attendees/URLs, Reminder notes/URLs, or Notification Center payload blobs. It does not persist native source identifiers.
This is polling, not an OS-native audit trail. A transient item can be missed between runs; repeating, moved, or deleted items can appear differently in later snapshots.
swift build
swift run mac-istm permissions
swift run mac-istm collect --sources mail,calendar,reminders
swift run mac-istm snapshots --limit 20
swift run mac-istm events --source calendar --limit 50The default local store is created under the current user’s Application Support directory. Supply --store PATH to use an explicit location. collect creates one snapshot per run and isolates source failures: an unavailable source is recorded as failed or skipped without discarding the other sources.
To attempt the intentionally experimental Notification Center adapter, first read its limitations, then provide the exact database path yourself:
swift run mac-istm collect --sources notification-center --notification-db /path/you/selected.sqliteThe program never searches for or assumes a Notification Center database path.
mac-istm collect [--store PATH] [--sources LIST] [--notification-db PATH] [--ttl-days DAYS] [--quiet]
mac-istm snapshots [--store PATH] [--limit COUNT]
mac-istm events [--store PATH] [--source SOURCE] [--limit COUNT]
mac-istm status [--store PATH]
mac-istm permissions
Retrieval commands only read the local store. They never invoke a collector or request a macOS permission.
Read Permissions before the first collection and Storage and retention before placing the store on a managed or backed-up volume. The code performs read-only collection, but EventKit and Apple Events permissions can be broader than the actions this program takes.
A conservative LaunchAgent template and idempotent helper scripts live in LaunchAgent documentation. Set permissions interactively before installing it: a background job must not be your first authorization attempt.
swift test
./scripts/public-release-audit.shTests use fixtures and temporary stores only; they never open a real Mail, Calendar, Reminders, or Notification Center database. See Architecture, Roadmap, Changelog, and Security policy.