What SAM Does

SAM is a native Mac application built with Swift 6, SwiftUI, and SwiftData for macOS 26 (Tahoe). It serves as a personal coaching assistant for independent financial strategists, combining relationship intelligence with business strategy in a single, unified interface.

SAM deeply integrates with Apple system apps — Contacts, Calendar, Mail, iMessage, Phone, and FaceTime — to observe the user's professional interactions, then provides AI-powered coaching: meeting preparation briefs, follow-up recommendations, relationship health tracking, pipeline analytics, production metrics, and strategic business insights. All AI processing happens entirely on-device using Apple FoundationModels and local MLX models. No data ever leaves the Mac.

Today view — daily briefing with prioritized coaching outcomes

People view — contact detail with notes and relationship summary

How SAM Uses Apple Contacts

Apple Contacts is SAM's canonical source of identity data. SAM never duplicates or replaces the user's address book. Instead, it links to Apple Contacts and enriches each person with CRM metadata: pipeline stages, communication preferences, interaction history, life events, and coaching outcomes.

Scoped Access

During onboarding, the user selects a specific Contacts group that SAM manages. SAM reads all Apple Contacts to support matching and deduplication (e.g., when importing LinkedIn connections or parsing email headers), but only imports and updates contacts within the user-designated group. Personal contacts remain untouched.

Contact Enrichment

When SAM discovers new information about a contact — from a LinkedIn import, a Facebook connection, an email signature, or a meeting note — it stages the update as a PendingEnrichment record. The user reviews and approves each enrichment before SAM writes it back to Apple Contacts. Enrichable fields include:

• Organization and job title
• Email addresses and phone numbers
• LinkedIn and Facebook profile URLs
• WhatsApp identifiers
• Contact relations (spouse, assistant, etc.)
• Anniversary dates
• Contact notes — SAM appends a structured block to the Apple Contacts note field containing a relationship summary, key context, and last interaction date (requires com.apple.developer.contacts.notes entitlement)

Why Contact Notes Matter

The Apple Contacts note field is the natural place to store portable relationship context that should travel with the contact across all Apple devices and apps. When a user opens a contact in Apple Contacts, Phone, FaceTime, or Mail, the note provides instant context — who this person is, what SAM knows about them, and when they last interacted.

SAM writes a clearly delimited block within the note (preserving any existing user-written content) that includes:

• A one-line AI-generated relationship summary (e.g., "Client since 2024. Active IUL policy. Last met Feb 15 about retirement planning.")
• Role badges (Client, Lead, Applicant, Agent, Vendor, etc.)
• Pipeline stage if applicable
• Last interaction date and channel

Without the Contact Notes entitlement, this context is locked inside SAM and invisible when the user encounters a contact in other Apple apps. The entitlement bridges SAM's intelligence into the broader Apple ecosystem where the user actually communicates.

Architecture

SAM follows a clean layered architecture with strict separation of concerns and Swift 6 strict concurrency throughout.

AI Architecture: Two-Layer Intelligence

SAM uses a two-layer AI architecture, both running entirely on-device:

• Layer 1 — Relationship Intelligence (foreground): Note analysis, meeting pre-briefs, follow-up drafts, relationship health scoring, communication channel recommendations. Responds within 2–5 seconds.
• Layer 2 — Business Intelligence (background): Pipeline analytics, production trends, time allocation analysis, cross-relationship pattern detection, content suggestions, scenario projections. Runs at TaskPriority.background, never competing with foreground interactions.

The StrategicCoordinator orchestrates business reasoning using an RLM-inspired decomposition pattern: it breaks complex analysis into focused sub-problems, dispatches specialist analysts (PipelineAnalyst, TimeAnalyst, PatternDetector, ContentAdvisor) in parallel via TaskGroup, then synthesizes results deterministically in Swift. Each specialist receives fewer than 2,000 tokens of pre-aggregated data. All numerical computation happens in Swift — the LLM interprets and narrates, never computes.

Apple System Integration

Privacy & Security

Privacy is foundational to SAM's architecture, not an afterthought.

Data Handling Principles

• Observe, summarize, discard — Raw email bodies and message text are analyzed on-device, then discarded. Only AI-generated summaries are stored.
• Scoped access — Contacts limited to user-designated SAM group. Calendar and Mail limited to user-selected work accounts.
• No external network calls — SAM makes zero network requests. All data stays on the local machine. Backups are encrypted.
• Sandboxed — Full App Sandbox with only the entitlements listed below.

Requested Entitlements

Contact Notes Entitlement: Technical Detail

SAM requests the com.apple.developer.contacts.notes entitlement to read and write the note field on CNContact records. This section describes exactly how SAM uses this field.

What SAM Writes

SAM appends a clearly delimited block to the existing note content — it never overwrites user-written notes. The block is wrapped in markers (--- SAM ---) so it can be identified, updated, and removed cleanly:

When SAM Writes

• Only when the user explicitly approves a contact enrichment update through the Pending Enrichment review flow
• Or when the user enables automatic note sync in Settings (opt-in, disabled by default)
• Never during background processing without user consent

What SAM Reads

SAM reads the note field during contact enrichment to preserve any existing user-written content outside the SAM block. It also reads notes to detect relationship context that the user may have previously entered manually (e.g., "Met at conference 2023" or "Referred by John Smith").

Graceful Degradation

SAM is fully functional without this entitlement. The ContactsService uses a try-catch pattern with isKeyAvailable(CNContactNoteKey) to detect entitlement availability at runtime. When unavailable, all other enrichment fields (organization, job title, email, phone, social profiles, relations, dates) still update normally. Only the note sync is skipped.

Technology Stack