Safari (Reading List + history fallback)

The Safari connector is a macOS edge harvester. Safari has no public read API, so the Carabase Desktop client reads directly from ~/Library/Safari/ (which requires Full Disk Access) and pushes a daily summary of your browsing history, Reading List, and Bookmarks into Carabase.

It’s the fallback capture path: it works without a browser extension installed, and it covers what an extension can’t easily see (for example, history from before you installed anything). A higher-signal Safari browser extension is planned — see The browser extension (planned) below — and the two are designed to run side by side.

What’s live today

The Safari fallback is shipping in stages. The first release covers Reading List capture, bookmarks change-detection, and sync bookkeeping; turning browsing history into searchable daily summaries is still being wired up.

• Reading List is captured. Reading List adds, removes, and read/unread status changes from your Mac are recorded in Carabase, keyed by URL so re-syncs don’t create duplicates. (Hydrating each saved page’s full body into a searchable artifact lands in a later release.)
• Browsing history is received, not yet stored per visit. Each sync acknowledges the history batch and advances the “last synced” marker to the newest visit it sees. Per-visit storage and per-domain daily rollups are still in progress.
• Bookmarks are change-detected. The Desktop client sends a snapshot of your bookmarks with a checksum; Carabase stores the checksum so later syncs can skip re-processing when nothing changed.
• Multi-device safe. Sync state is tracked per workspace, and the “last synced” marker only ever moves forward — an older sync from a second Mac can never rewind a newer one.

Setup

The Safari edge harvester ships in the Carabase Desktop client. To connect it:

1. Grant Carabase Desktop Full Disk Access in macOS System Settings → Privacy & Security (Safari stores its data in a protected location).
2. Pair the device using the standard edge-harvester pairing flow with connector name safari.

Once paired, Desktop pushes a daily summary (around 03:00 local time) to the POST /api/v1/safari/sync endpoint. The current connection status — last sync time, detected Reading List source, and item counts — is available at GET /api/v1/safari/connection.

Filter options

You can shape what the Safari connector ingests with per-rule filters. Some of these affect substrate capture today; others govern how history is routed into your daily notes, which activates with the history-rollup release. The options are:

• Exclude / include domains — skip noisy or sensitive hosts, or restrict routing to a chosen set of domains (substring match, case-insensitive).
• Daily top-N — how many of the day’s most-visited URLs appear in the daily browsing summary (default 10).
• Minimum daily visits — suppress a day’s summary entirely when total visits fall below this threshold (default 3), to cut noise on quiet days.
• Minimum per-URL visit count — drop URLs visited fewer than this many times (default 1; raise it to filter out accidental single taps).
• Reading List — capture Reading List adds (on by default).
• Bookmarks — keep a folio summary in sync with your Safari bookmarks (off by default, since bookmarks re-shuffle on every sync).
• Scrape top visits — opt in to fetching full page bodies for the day’s most-visited URLs.
• Promote by entity domain — automatically treat a visit as high-priority when its host matches a domain already tracked by an entity in your knowledge graph (on by default).

The browser extension (planned)

The long-term, higher-signal Safari capture surface is a browser extension rather than a disk reader. Where the fallback captures every URL you visit with no sense of which pages mattered, the extension is built around intent: a toolbar button to explicitly save a page to a folio with tags, plus dwell-time signals that promote pages you actually read. It would also capture the exact page you saw — extracted in the browser — without a second fetch, and would not require Full Disk Access.

The extension uses Carabase’s streaming push model (per-event pushes to POST /api/v1/streams/<connector>), and the host-side streaming infrastructure that model depends on already exists. The Safari extension itself — the connector wiring and the macOS extension app — is not yet built. Until it ships, the history fallback described above is the Safari capture path.

When the extension arrives, the two will co-exist: the extension handles high-intent active capture, while the fallback continues to cover passive history and Bookmarks (which the Safari extensions API can’t read). You’ll be able to run either or both.