Architecture

A small monorepo: one shared Swift package with the data model, and two thin native apps (macOS and iOS) built on top of it. Pure Swift — SwiftUI + AppKit on the Mac, SwiftUI on iOS.

Repository layout

Packages/MemoryKit/   shared models and rules: items, Boards, retention, persistence, sync interfaces
apps/macos/           macOS app (clipboard monitor, panel, Boards, reminders, pasting)
apps/ios/             iOS app (local memory, gestures, details, Boards, reminders)
Resources/Info.plist  Info.plist for the macOS build
project.yml           XcodeGen configuration → generates MemoryApp.xcodeproj
build.sh              fast macOS build via SwiftPM (no Xcode needed)

MemoryKit — the shared core

Packages/MemoryKit is a Swift package containing the data model shared by both apps. It deliberately depends on Foundation and CryptoKit only — no AppKit, no UIKit — so it compiles unchanged on macOS and iOS.

ClipType — enum of content types: text, link, color, image, file, each with a display name and an SF Symbols icon name.
ClipItem — one remembered item: identity, type, timestamps, payload references, source app, pin, Board memberships, reminder date and content hash. Full field reference in Data Format.
MemoryBoard and MemoryArchive — named collections plus one atomic snapshot of items and Boards. Pinned, Loved and Saved use stable system IDs.
RetentionPolicy, ClipProtection and HistoryRules — 30/60/90/120-day or forever cleanup with pin, Board and uncleared-reminder protection.
HistoryEnvelope and HistoryPersistence — versioned atomic saves, matching backup snapshots, migration and corrupt-file recovery.
ClipItem.detectTextType(_:) — classification of copied text into color / link / text.
Hashing — SHA-256 helpers used for content-based deduplication.

macOS app (`apps/macos`)

Component	Responsibility
`ClipboardMonitor`	Watches `NSPasteboard` by polling its change counter; classifies new content, honors the `org.nspasteboard` confidentiality convention and the app exclusion list.
`HistoryStore`	Owns items and Boards: atomic archive persistence, blob storage, deduplication, time-based retention, Board membership, Loved/Saved state, reminder scheduling and legacy migration.
`PanelController`	The slide-up recall panel. A non-activating panel (Spotlight pattern), so the frontmost app keeps focus while you browse.
`HistoryView`	SwiftUI content of the panel: global search, type filters, card grid, quick Loved/Saved actions, Board and reminder menus, keyboard navigation, drag & drop and context menus.
`LibraryView`	All-Boards navigation, Board editor, per-Board item views and item detail/reminder sheets.
`ReminderScheduler`	Requests notification permission, schedules/cancels local item notifications and routes an opened notification to its stable item ID.
`HotkeyManager`	Registers the global `⌘⇧V` shortcut.
`PasteHelper`	Pastes into the active app by synthesizing `⌘V` (CGEvent); requires the Accessibility permission. Plain-text paste variant for `⌥↩`.
`SettingsView`	Preferences: retention (30/60/90/120 days or forever), excluded apps and launch at login.
`ColorHex`	Parsing/rendering of HEX colors for color previews.
`main.swift`	App bootstrap: menu-bar item (🧠), wiring of monitor, store, panel and hotkey.

iOS app (`apps/ios`)

The iOS app (bundle id cc.memoryapp.ios) is a native client for the same memory as the Mac app, kept in sync via iCloud in signed builds. It supports global search, left-to-Deleted/right-pin swipes, tap-to-detail, long-press actions, Loved/Saved, named Boards, reminders and safe opening for recognized web links.

Component	Responsibility
`MemoryAppApp` / `IOSAppDelegate`	SwiftUI entry point plus notification category setup and response routing to an item ID.
`IOSStore`	Local item and Board store: search, membership, reminders, retention, archive persistence and the sync interface (active in signed builds).
`ContentView`	Memory list, search, quick Loved/Saved buttons, swipe actions, long-press menus and add-from-clipboard.
`IOSItemDetailView`	Detail sheet, safe web-link opening, Board membership and reminder editor.
`IOSBoardsView`	All-Boards overview, custom Board management and Board-scoped item lists.
`IOSReminderScheduler`	Local notification authorization, scheduling, cancellation and reconciliation.

Data flow (macOS)

copy in any app
      │
      ▼
NSPasteboard ──(polling)──▶ ClipboardMonitor
                                  │  classify (text/link/color/image/file)
                                  │  skip confidential + excluded apps
                                  ▼
                            HistoryStore ──▶ versioned archive + blobs/
                                  │  dedup + Boards + reminders + retention
                                  ▼
⌘⇧V ──▶ HotkeyManager ──▶ PanelController ──▶ HistoryView
                                  │
                     click / ↩ / drag & drop
                                  ▼
                    clipboard  ──▶ PasteHelper (⌘V into the active app)

Build system

build.sh — the fast path: builds the macOS app with SwiftPM only. Artifacts go to ~/Library/Caches/MemoryAppBuild to keep the (cloud-synced) repo clean.
project.yml + XcodeGen — generates MemoryApp.xcodeproj with the MemoryApp-macOS and MemoryApp-iOS targets. The project file is disposable; project.yml is the source of truth.

iCloud sync architecture

Signed, entitled builds use CloudKitSyncEngine by default and keep an offline local copy. Items, Deleted state and Board definitions travel through the user's private CloudKit database; SyncPocket App runs no data server and cannot read anyone's archive. Every item carries modifiedAt: the newest change wins, Deleted wins an exact-time tie, and a conflicting save is retried with the latest server change tag. Isolated UI tests use NoopSyncEngine. Shipping remains gated on a signed production container and a two-device conflict test.