Skip to content

apple_notes

diapason.connectors.apple_notes

Apple Notes connector — reads directly from the macOS Notes SQLite database.

No API calls, no OAuth. The connector opens ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite in read-only mode and yields one :class:Document per note.

Requires Full Disk Access granted to the terminal / app in System Settings → Privacy & Security → Full Disk Access.

Timestamp notes

The Notes database stores modification timestamps as seconds since the Apple epoch of 2001-01-01 00:00:00 UTC. Conversion formula::

dt = datetime(2001, 1, 1, tzinfo=utc) + timedelta(seconds=ZMODIFICATIONDATE)

Content extraction

The ZDATA column in ZICNOTEDATA contains gzip-compressed protobuf (com.apple.notes.ICNote). Plain text is obtained by decompressing the bytes, decoding to UTF-8, and stripping protobuf control bytes.

AppleNotesConnector

Bases: BaseConnector

Connector that reads notes from the macOS Notes SQLite database.

Parameters

db_path: Path to NoteStore.sqlite. Defaults to ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite.

disconnect()

Mark the connector as disconnected.

is_connected()

Whether the Notes store can actually be READ, not merely seen.

See can_read_sqlite: under macOS TCC the file is visible and unreadable at the same time, and exists() cannot tell them apart.

mcp_tools()

Expose two MCP tool specs for real-time Apple Notes queries.

sync(*, since=None, cursor=None)

Read notes from NoteStore.sqlite and yield one :class:Document each.

Parameters

since: If provided, skip notes whose modification time is before this datetime. cursor: Not used for this local connector (included for API compatibility).

Yields

Document One document per note, with gzip-decompressed plain-text content.

sync_status()

Return sync progress from the most recent :meth:sync call.