Local sync

Local Sync keeps a local folder of Markdown Pages connected to your Context. Save a file in Obsidian, your editor, or with an agent, and the background app sends the edit to Pensieve. Cloud changes arrive in the same folder. Sync is included with Pensieve desktop on macOS. You can also install it separately when a standalone installer is available for your Mac. You do not need GitHub.

Set up a folder

1. Open Access → Local files. In Pensieve desktop on macOS, choose Open Local Sync. If prompted, update the desktop app first. In a browser, choose Download Local Sync when an installer is available for your Mac, then install it in Applications.
2. Sign in to Local Sync with your own Pensieve account.
3. Choose your Context and a separate local folder. Enable syncing and choose whether it should start at login.
4. Open that folder as a vault in Obsidian, or use any editor that saves ordinary Markdown files.

The desktop app opens the included sync app directly; there is no separate download. Local folder sync is not yet available on Windows or Linux.

If you installed Pensieve desktop before Local Sync was released, the normal desktop update includes it. Choose Check for updates from the Pensieve application menu, install the update and relaunch Pensieve. Then open Access → Local files → Open Local Sync, sign in and choose a folder. Updating the app does not start syncing a folder automatically.

If the browser says an installer has not been published, a standalone download is not available for your platform yet. This message is independent of whether you have Pensieve desktop installed. You can use the sync app included with an up-to-date macOS desktop installation.

The first version edits the bodies of existing Pages. Keep the generated frontmatter, heading and filenames intact. Create, rename, move and delete Pages in Pensieve; those cloud changes are reflected locally. Deleting a local file never deletes its cloud Page.

Links between Pages open local files. Source citations and other external links open in your browser. When adding links in Obsidian, turn off Use [[Wikilinks]] under Files and links so it writes ordinary Markdown links. Some source references carry extra identity inside Pensieve; edits that cannot preserve that identity ask you to finish the change in Pensieve. Adding a new source citation may require supporting evidence through Pensieve or its MCP tools; a Markdown link alone does not provide that evidence.

Saved, offline and paused

The menu-bar app shows whether edits are saved, uploading, waiting for a connection, or need attention. Saved to Pensieve means the cloud has acknowledged the saved file's current edit. Unsaved editor buffers stay in your editor.

You can edit offline. Files and pending work stay on disk and resume when the app reconnects. Closing the status window or the desktop app leaves sync running. Pausing or stopping sync leaves files and pending edits in place; it does not turn the folder into an overwrite-only mirror. If you enable startup at login, the background app starts when you sign in to your Mac.

Local files shows your devices' last contact and last reported sync. A disconnected device may be offline, asleep or stopped. A plain Markdown file cannot show live sync health when the background app is not running.

Sync included with desktop updates with that app. If desktop asks you to stop sync before updating, choose Stop Local Sync from the menu-bar app, install the update, then open sync and resume. Enable startup at login again if you want it. Standalone sync offers its own installer updates.

When both versions change

Local Sync compares the downloaded version, your saved file and the latest cloud Page. Separate edits can merge automatically. Overlapping or uncertain changes pause that Page and retain both versions; other Pages continue syncing.

Open the sync app to choose a version or edit the conflict, then resolve it. Nothing is silently overwritten because a newer timestamp won. A cloud deletion with local edits preserves your file and asks what to do. If the cloud Page moved while you were editing, accept its new location before reapplying the preserved edit so relative links keep their meaning.

Settings → Open recovery folder opens safety copies kept before local files are replaced. These backups are separate from unresolved conflicts, which appear on the main sync screen. Both live inside .pensieve-sync. Keep that hidden folder until pending work is resolved. Signing out does not delete your Markdown files.

Using an agent

Local Sync creates an AGENTS.md guide in your folder when one does not already exist. Existing instructions are preserved. This file stays local and does not become a Page. Agents connected through MCP can also request info(help="local_sync") for the current versioned guide. MCP access alone does not give a remote agent access to your Mac: it should check the command's status and connected folder before using it.

With your agreement, an agent can keep the primer and version in its harness instructions or memory. Live sync status and conflict lists should always be checked again, never saved as standing facts.

An agent can edit the files normally. Opening Local Sync automatically installs ~/.local/bin/pensieve-sync; there is no separate package or Node requirement. Settings → Terminal command → Copy copies the full path for your terminal or agent, including when ~/.local/bin is not in its PATH. Add that directory to PATH if you prefer the short name. Run pensieve-sync status --json for status or pensieve-sync sync --wait --json to wait for the current saved edits to be acknowledged. A failed or timed-out wait means the agent must inspect status; it must not claim the edit reached the cloud.

The agent can also use Pensieve's MCP edit tools directly. Both routes use the same Page validation and history. Editing a Page does not automatically lock it against future curation or turn its text into source evidence.

Git mirror is separate

The Git mirror publishes a read-only cloud copy to a repository. It needs no installation and does not upload local edits. You may use both features, but choose different folders: Git pulls and Local Sync must not both write the same checkout. Installing sync never changes a mirror into a two-way connection.

The mirror README links to Local files for the same Context, where you can open or download Local Sync. Cloning the mirror does not install or start the app.