Apple Notes Snapshot

Apple Notes Snapshot is the backup control room for Apple Notes on macOS. Keep the upstream notes-exporter engine, then add path-aware exports, launchd scheduling, visible health checks, and a calmer recovery path when the local backup loop drifts.

🤝 Sister repo: looking to recover deleted notes after the fact, not back them up beforehand? See notes-recover — the forensic-grade reader for Apple Notes' NoteStore.sqlite (recover deleted notes, browse the raw store, ship audit-ready bundles). notebackup covers the before; notes-recover covers the after. Together they cover the full Apple Notes lifecycle on macOS.

After the control room already makes sense, the repo also ships extra builder and diagnostics surfaces so humans and coding agents can inspect the same backup state without turning the workflow into a hosted service.

Start the 3-step quickstart | First-run troubleshooting | Open the proof page | Compare with upstream | Browse release history | Get support or routing help

• Keep the path obvious Review or override the export destination before the first snapshot writes.
• Turn one-off exports into a local loop Use launchd to schedule repeatable snapshots instead of babysitting manual exports.
• See health before you guess Check freshness, failure reasons, logs, and recovery clues when the loop drifts.
• Read the next safe move first The Web console now surfaces an operator focus deck above the raw transcript so you can see the next move, the reason, and the reading order before diving into action output.

Category: Apple Notes backup control room. AI/agent hook: AI-assisted diagnostics plus optional coding-agent access once the operator workflow is already clear. Result: a calmer, more reviewable backup workflow on your own Mac.

Best fit: people who already rely on Apple Notes and want a calmer, reviewable backup routine on their own Mac.

Not the goal: cloud sync, team collaboration, or two-way write-back into Apple Notes.

At A Glance

If you only want the shortest truthful filter before reading deeper, use this table first:

What you can prove in one local pass

• The destination is obvious: you can review or override the snapshot path before anything writes.
• The loop is real: one manual run plus launchd turns a one-off export into a repeatable local rhythm.
• The control room is inspectable: status, verify, doctor, logs, and proof pages all stay on the same local facts.
• Integration surfaces are optional: AI Diagnose, the Local Web API, and MCP all stay behind the operator story instead of replacing it.

If you want the shortest public evidence trail after that first pass, open the proof page. It collects the repo-owned gates, the GitHub-controlled release and Pages evidence, and the current access boundary in one place.

Start with Run -> Install -> Verify

Treat the first healthy loop like a three-stop checklist, not like a dashboard to decode all at once.

1. Run Use ./notesctl run --no-status once so macOS can surface permissions and the local ledger can record a first successful baseline.
2. Install Use ./notesctl install --minutes 30 --load after that first run so the workflow becomes a repeatable launchd loop instead of a manual chore.
3. Verify Use ./notesctl verify first, then ./notesctl doctor only if warnings or empty state remain.

After that verified loop exists, the Web console, proof page, AI Diagnose, Local Web API, and MCP surfaces become much easier to read because they are all describing a baseline you already proved.

Integration and maintainer routes after the operator path

The public product front door is still the local backup control room. The lanes below are for builders after the first healthy loop exists; they do not replace Run -> Install -> Verify.

• Public product front door: backup control room
  • the main story is still the local path review, the first snapshot run, the launchd loop, and the health check surface on your own Mac
• Second ring builder protocol lane: pure MCP
  • the repo's main machine-facing surface is the local stdio MCP flow behind ./notesctl mcp and the root server.json
• Second ring builder packet lane: pure skills
  • the public skill packet at examples/public-skills/notes-snapshot-control-room/ teaches hosts how to attach to that same local control room
• Companion later lanes: plugin shell and .mcpb packaging
  • plugins/apple-notes-snapshot-control-room/ and packaging/mcpb/ are host-shaped packaging surfaces around the same local workflow
  • they matter, but they are not the first story a new reviewer should read
• Current non-claims
  • no hosted Notes service
  • no cloud sync product
  • no official skill or plugin marketplace listing without fresh host-side read-back
  • no cross-machine attach guarantee

Use the integration links below only after the operator loop already makes sense.

Secondary integration reads after the first healthy loop: AI Diagnose | Local Web API | MCP Provider | Distribution and listing boundaries | For Codex / Claude Code integrations

Quickstart

Start here if you want the shortest honest path from manual export to a repeatable local snapshot loop. The first-successful-run promise is 3 steps and about 3 minutes, not a zero-click install.

1. Review config/notes_snapshot.env and keep or change the default export path.
2. Run one snapshot so macOS can show Apple Notes / AppleScript permission prompts.
3. Install the scheduler, then verify health.

# review config/notes_snapshot.env first
./notesctl run --no-status
./notesctl install --minutes 30 --load
./notesctl verify
./notesctl doctor

Fail fast:

• If ./notesctl verify says FAIL: no last_success record; run ./notesctl run, you have not completed the first manual export yet.
• If macOS permissions block the first run, use ./notesctl permissions and the public troubleshooting guide.
• The full, authoritative guide lives at docs/quickstart.
• The public proof page shows the repo-side gates, live-surface checks, and trust boundary in one place.
• Maintainer-grade verification lives later in Proof and verification; it is not required for the first successful snapshot.

Choose the right lane

Keep the operator lane and the maintainer lane separate.

• Operator lane
  • ./notesctl run --no-status
  • ./notesctl install --minutes 30 --load
  • ./notesctl verify
  • ./notesctl doctor
  • ./notesctl status --full
  • optional after the local state exists: ./notesctl ai-diagnose, ./notesctl web, and ./notesctl mcp
• Maintainer lane
  • ./notesctl clean-cache --dry-run
  • ./notesctl clean-cache
  • ./notesctl rebuild-dev-env
  • ./notesctl update-vendor
  • ./notesctl setup / ./notesctl self-heal

If your goal is a healthy backup loop, stay in the operator lane first. The maintainer lane is for repo upkeep and contributor verification after the local workflow already makes sense.

Why this exists

The upstream notes-exporter project is great when you want to export Apple Notes right now. This repository exists for the moment when "run it once" turns into "keep it healthy every day."

Apple Notes Snapshot wraps the upstream exporter with: