Use Selected Apple Notes as Agent Memory

Selected Apple Notes folders can serve as an AI agent's persistent memory — readable on every Apple device the user owns, correctable by hand, and updated by the agent through structured writeback. Figment does not offer a public Notes-specific API endpoint; this article is an integration design guide for developers building a Notes-backed agent using Apple-native access methods on a Figment-hosted Mac.

Why Apple Notes fits an agent memory store

Apple Notes automatically syncs across iPhone, iPad, Mac, and Apple Vision Pro via iCloud (iCloud Notes overview). Notes support tags, Smart Folders, rich text, attachments, and inline PDFs — enough structure for most agent workflows without a separate database.

The key advantage over a vector store or SQL table is human editability. When the agent writes something wrong, the user fixes it in the note. That correction becomes the agent's source of truth on the next read cycle. The memory stays legible, correctable, and always with the user — which matters as much as recall accuracy.

iCloud sync means the memory survives session boundaries. The user can annotate a note on their iPhone during the day; the agent reads the updated text that evening from the Mac-side helper.

Reading notes with Apple-native tools

Apple's third-party authorization covers iCloud Mail, Calendar, and Contacts — Notes is not among them (Apple support 121539). Notes content requires running native Mac operations.

Markdown export (macOS 26+). Apple Notes supports per-note Markdown export: open the note, choose File → Export as → Markdown, and save to a chosen folder (Apple Notes export guide). A local helper script on the Figment-hosted Mac can automate this for a user-defined folder: export each note to a staging directory, read the files, write updated files back for re-import. Attachments and locked notes are not fully exported; the patterns below account for those gaps.

AppleScript access. A tell application "Notes" block can read note titles and body text from a named folder without a separate export step. This runs on the Figment-hosted Mac inside the signed-in user session. The developer owns this helper script; Figment provides the execution environment, not the script itself.

Both methods require the user to have Notes open and iCloud sync enabled. Neither can read a locked note without an explicit user unlock.

Folder selection: scope access to exactly what matters

Notes organizes content into several types: standard project folders, Quick Notes (notes started outside the app), Math Notes (math work synced from the Calculator app on iPhone/iPad), Shared (collaborator content), and Recently Deleted (held up to 30 days). The agent should read from deliberate project folders only.

Keep agent-writable folders in the iCloud account (not Gmail or Yahoo third-party folder sources). Notes can only be locked if stored in iCloud; keeping agent folders in iCloud gives consistent lock-status behavior and sync availability.

Locked notes

Apple lets users lock individual notes with a password (Apple iCloud locked notes). Notes locked with a device passcode or macOS login password cannot be viewed on iCloud.com. Notes locked with a custom Notes password can be viewed on iCloud.com after entering that password, but still require an explicit unlock step before a local helper can surface them. In either case, the agent rule is the same: skip any locked note and tell the user. Never attempt programmatic unlock.

Build your folder structure so agent-writable notes are never individually locked. Reserve locking for private notes the agent should never see.

Writeback rules: appending without breaking content

An overwrite strategy destroys user edits. An unstructured append strategy accumulates noise the user can't scan. The right rule depends on what a note is for:

Before every write, confirm the Notes helper can reach the target note. If not, queue the write and retry after a configurable back-off. Generate a stable write-intent key (for example, a UUID) once per intended write, before the first attempt, and embed it in the entry. Skip the write if that key already appears in the note. This prevents duplicate entries on retry without a separate state store. Do not recompute a new key if the content changes after a failed attempt — generate a fresh key for the new content, and poll the note directly to determine whether the previous attempt landed before treating its outcome as unknown.

Source citation inside notes

Every paragraph the agent writes must open with a provenance line. This makes the memory auditable and prevents the agent from mistaking its own previous output for an independent source.

A minimal citation:

[Agent • 2026-11-12T14:32Z • source: Research/Article-draft.md • action: summarize]

Four fields: Agent (author), an ISO 8601 UTC timestamp, the source note path or external reference, and the action type (summarize, extract, decide, update). These are application-owned metadata fields embedded as plain text — not invented Apple API fields. If the agent reads a note it wrote previously, the citation chain makes that loop visible — a signal for the user to intervene if the chain has grown long.

The selection–citation–writeback ruleset

The unique artifact for this use case is a declaration that travels with the agent's system prompt or configuration file. It eliminates ambiguity about which folders to touch, how to format an entry, and when to skip a write entirely.

NOTES MEMORY RULES

Readable folders:
  - Agent Memory
  - Research
  - [Project folders defined at setup]

Writable folders:
  - Agent Memory
  - [Project folders where write access was explicitly granted]

Excluded (never read or write):
  - Shared
  - Quick Notes
  - Math Notes
  - Recently Deleted
  - Any note whose status is locked

Access guard:
  - Only proceed if the Notes helper can reach the target folder
  - If unavailable: queue write, retry after back-off; do not write

Writeback strategy:
  - Running logs     → append a dated block; never delete existing lines
  - Decision records → append below "— Agent additions —" separator
  - Summary notes    → replace only content between
                       [AGENT SUMMARY START] … [AGENT SUMMARY END] markers
  - Read-only folder → read only; no write under any condition

Citation format (prepend to every agent-authored paragraph):
  [Agent • {ISO8601_UTC} • source: {source_ref} • action: {action_type}]

Idempotency:
  - Generate a unique write-intent key (e.g., a UUID) once, before the first attempt
  - Embed the key in the entry text
  - If the key already appears in the note: skip write; do not create a duplicate
  - If content changes after a failed attempt: generate a new key for the new content;
    poll the note to determine whether the previous attempt landed before treating
    its outcome as unknown

Locked notes:
  - Skip read; never attempt write
  - Surface to user: "Note is locked — unlock in Apple Notes to include"

This ruleset is plain text. Any agent framework that accepts a system prompt can consume it without code changes. Folder names can be parameterized at setup time; the citation format and writeback strategy are fixed.

The execution environment is a Figment-hosted Mac running within the signed-in user session. Figment's own OAuth layer manages app consent and scoped access tokens for supported services; the Notes helper itself is developer-owned code that runs on that Mac. Start with the read path covered in Read Apple Notes with a Scoped Mac Helper, then add write logic once your folder selection and citation rules are validated. For related Apple data sources — photos, files, and Safari — see Connect Apple Notes, Photos, Files, and Safari. For task creation alongside note memory, see Create Apple Reminders with EventKit on Mac.

Connect Apple Account to register your app and get access to a Figment-hosted Mac. Sandbox access is free; live connections are $29/month per active connection and are available after setup.