Keeping A Local Copy Of A Synced Graph

The Sync Server keeps a synced graph encrypted, and every device opens it from there. Until you set up a Local Mirror, you have no folder on your device where you can read the graph's files. A Local Mirror is a plain Markdown copy of a synced graph in a folder on your device: the documents as Markdown files, the attachments as ordinary decrypted files, and the graph settings.

The mirror is one-way. The app writes to the folder but never copies changes from it back into the graph, and the graph on the Sync Server remains the copy that counts. After the app has checked the list of documents with the Sync Server, it makes the folder match the graph, and from then on the mirror owns the folder.

Each mirror belongs to the browser and device where you set it up, so another computer or browser has no mirror until you set one up there. Mirroring runs only while the graph is open in that browser, and catches up the next time you open the graph. It needs a browser that can give the app a folder: Chrome or Edge on a computer, or Chrome on Android. See Choosing Where To Store Your Notes for more information.

An export is a one-off zip of the same files. Unlike a mirror, it does not stay up to date, and you can take one in any browser, phones included. Mirrors and exports are plain files that backup tools, Git and other Markdown editors can read. They have the same layout as a local graph folder, so Import can turn either one back into a graph.

Protected documents stay encrypted in a mirror and in an export. Each copy also holds your protection key, wrapped with your passphrase, so in a graph rebuilt from the copy the same passphrase opens those documents. In a shared graph (Sharing A Graph) the copy holds only your key, so in the rebuilt graph you cannot open documents that another Player protected. See Protected Documents for more information.

Before you begin

A synced graph that you can open (Synced Graphs).
For a mirror, an empty folder.
For an export, a connection to the Sync Server, because the export downloads the attachments from it.

Start a Local Mirror

Open the synced graph.
In the toolbar, select Graph name and settings, or on a phone, select Settings in the Graph Sidebar.
Select the Mirror and Export tab.
Select Choose a folder and start mirroring….
Choose a folder when the browser asks for one.

If the folder has nothing in journals/, pages/, assets/ or etherpk/, mirroring starts at once. Otherwise the app asks before it starts, and tells you how many files the first pass would delete, replace or leave alone.

Choose an empty folder, because the first pass deletes Markdown files in journals/ and pages/ that are not documents of the graph, and replaces files that have the same title as a document. In assets/ it deletes only files named the way EtherPK names attachments, and it touches nothing outside the four folders. To go ahead, select Mirror and replace contents, or Mirror to this folder when the pass would change no file. Select Cancel to leave the folder as it is.

Two graphs in one folder would delete or mix each other's files, so the app will not mirror to a local graph folder or to another graph's mirror folder on this device. If it refuses the folder, select Choose another folder, or stop mirroring the other graph first.

You also cannot open a mirror folder on this device with Open folder (Local Graph) on the Graphs page, because the mirror would undo your changes there the next time it runs.

If your browser cannot give the app a folder, the tab shows a message in place of the button, and you can still use Export as zip….

Folder contents

The mirror saves each page as a Markdown file named after its title. In a shared graph it writes only your own favourites, quick notes and bookmarks, because those lists belong to whoever made them. See Graph Folder Layout for more information.

Edits in the folder

Because the mirror is one-way, editing a mirrored file does nothing to the graph. The mirror overwrites the file with the graph's version the next time that document changes, or the next time it goes through the whole graph, for example when you open the graph.

To work on the files as your own notes, import the folder as a new local graph instead, with Import on the Graphs page.

Mirror status

While a mirror is set up, a dot in the toolbar shows its state:

Green: the last pass has finished, even if it skipped documents that were still syncing or attachments it could not download, or it could not check for edits on other devices.
Amber: the mirror is writing, getting ready, or waiting to try again.
Red: mirroring has stopped. If the mirror lost its connection to the Sync Server, it carries on by itself once you are back online. Any other stop (a lost folder permission, a missing folder or a file it could not write) waits until you act on the Mirror and Export tab.
Grey: another tab in this browser is mirroring the graph.

Select the dot to open the Mirror and Export tab, which lists anything the mirror is still waiting for or could not write. On a phone, the state appears only on that tab.

Updates while the graph is open

The mirror catches up on its own when you open the graph, as long as the app still has permission to write to the folder. Browsers usually drop that permission when they restart, and the dot then stays red until you select Reconnect and carry on and allow access again.

If you install EtherPK as an app in Chrome on a computer, the permission survives a restart, so the mirror carries on by itself. See Installing EtherPK As An App for more information.

A device that never opens the graph never updates its folder. For a backup that stays current, open the graph on that device from time to time.

Stop a Local Mirror

On the Mirror and Export tab, select Stop mirroring. The app forgets the folder on this device but leaves the files in it as they are.

Export a zip

Open the synced graph.
In the toolbar, select Graph name and settings, or on a phone, select Settings in the Graph Sidebar.
Select the Mirror and Export tab.
Select Export as zip….

In Chrome or Edge on a computer, you choose where to save the zip and the app writes straight into that file, so you can export a graph of any size. In other browsers, the app first builds the zip in browser storage on your device and then downloads it, so the zip has to fit in the space the browser has left. If the attachments need more space than that, the export does not start.

If a document is still syncing or an attachment failed to download, the app holds back the finished zip, because an export has no later pass to fill the gap. Select Keep the incomplete export to save it anyway, or Discard.

Rebuild a graph from a copy

On the Graphs page, select Import.
Select Choose folder… for a mirror folder, or Choose a zip… for an export.
Enter a name for the new graph.
Choose where the new graph goes: Local folder or Synced graph.
Select Import.

If you chose Local folder, the browser then asks for a folder, and the app refuses one that is not empty. Import builds a new graph from the copy, so the original graph's members and edit history do not carry over. See Importing A Knowledge Base for more information.

Linked references

Bookmarks
- A Local Mirror or export of a synced graph holds only your own bookmarks, in etherpk/bookmarks.json. Importing an EtherPK folder or export adds its bookmarks to your list. The importer skips bookmarks from other tools. See Graph Folder Layout, Keeping A Local Copy Of A Synced Graph and Importing A Knowledge Base for more information.
Choosing Where To Store Your Notes
- A Local Mirror is a plain Markdown copy of the graph that sits in a folder on one device and updates while the graph is open there. Since it writes to a folder, it needs the same browsers as local graphs. In any other browser, Export as zip… saves the Markdown files, attachments and settings as a zip file instead. See Keeping A Local Copy Of A Synced Graph for how to set up a mirror.
Glossary
- | export | A one-off zip of a synced graph's documents, files and settings, which you can make in any browser. | Keeping A Local Copy Of A Synced Graph |
- | Local Mirror | A plain Markdown copy of a synced graph in a folder on one device. EtherPK never reads the folder back, so edits there never reach the graph. | Keeping A Local Copy Of A Synced Graph |
Graph Folder Layout
- If you edit a file in a Local Mirror, EtherPK overwrites the edit the next time it updates the whole folder. For example, it does that when you open the graph, select Mirror now, or rename or remove a page. To work on the files, import the folder, or a zip made with Export as zip…, as a new graph on any device. See Keeping A Local Copy Of A Synced Graph for more information.
Graph Settings
- The Local Mirror is a one-way, plain Markdown copy of the graph in a folder on this device, kept up to date as you edit while the graph is open. Export as zip… makes a one-off zip of the Markdown files, attachments and settings, which you can import as a new graph. See Keeping A Local Copy Of A Synced Graph for more information.
How Encryption Works
- A Local Mirror (see Keeping A Local Copy Of A Synced Graph) and an export are readable Markdown copies too, though protected documents stay encrypted in both.
Images And Files
- A synced graph stores its files encrypted, so there is no folder to open them from. To get readable copies in a folder on your device, keep a Local Mirror. See Keeping A Local Copy Of A Synced Graph for more information.
Importing A Knowledge Base
- For each import, you choose whether the new graph is a local graph, kept in an empty folder on this computer, or a synced graph on Managed Sync. You cannot switch an existing graph between local and synced, so importing a copy is also how you move notes from one kind to the other. To move a local graph to Managed Sync, import its folder. To move a synced graph to a local one, first make a Local Mirror or an export zip of it (Keeping A Local Copy Of A Synced Graph), then import that copy. Either way, the original graph stays as it was.
Protected Documents
- In a synced graph, the key record is stored with your Encryption Keys, and a Local Mirror or an export carries a copy of it. See Keeping A Local Copy Of A Synced Graph for more information. If the key record is damaged, see Troubleshooting.
Quick Notes
- Notes still on the list go into a Local Mirror or an export, so a copy taken before a move includes them. See Keeping A Local Copy Of A Synced Graph for more information.
Sharing A Graph
- Deleting also removes the copy in this browser, so the dialog warns you about unsent changes and offers Download unsent changes. Files you mirrored to a local folder are kept. See Keeping A Local Copy Of A Synced Graph for more information.
Synced Graphs
- You can also turn on a Local Mirror to keep a plain Markdown copy of the graph up to date in a folder on one computer. See Keeping A Local Copy Of A Synced Graph for more information.
The Graph Sidebar
- On a local graph, your favourites live in etherpk/settings.json (see Graph Folder Layout). In a shared graph (see Sharing A Graph), EtherPK does not show your favourites to the other members. Every member has the graph key, though, so the list is not secret from them. To keep a document's text private from them, protect it (see Protected Documents). A Local Mirror or an export of a synced graph carries only your own favourites. See Keeping A Local Copy Of A Synced Graph for more information.
Theming A Published Site
- A theme in the graph is stored with the graph settings, so every device and member of a shared graph sees, edits and publishes with the same theme. It is not a page, and it does not appear in search or backlinks. In a local graph folder, an export or the Local Mirror of a synced graph, each theme is one file, etherpk/theme-<id>.jsonc. See Keeping A Local Copy Of A Synced Graph for more information on Local Mirrors.
Troubleshooting
- See Keeping A Local Copy Of A Synced Graph for more information.
- See Keeping A Local Copy Of A Synced Graph for more information.
- See Keeping A Local Copy Of A Synced Graph for more information.
Using AI Agents With Your Notes
- An agent can also read a Local Mirror, a plain Markdown copy of a synced graph kept in a folder on one device. EtherPK never reads changes back from that folder, so it overwrites anything the agent changes there. See Keeping A Local Copy Of A Synced Graph for more information.
Where Your Data Is Stored
- A local graph's folder is the original, so you can back it up with any file tool. For a synced graph, keep a Local Mirror (a plain Markdown copy in a folder on one device), or make a one-off zip with Export as zip…. Protected documents stay encrypted in both, so you still need your protection passphrase to read them. See Keeping A Local Copy Of A Synced Graph for more information.
Your EtherPK Account
- Sync+ ends when a cancelled subscription reaches its end date, or when Stripe cancels it after a failed payment. The graphs you own then become read-only and the Graphs page marks each one Read-only, but you can still open, export and delete them. Before EtherPK deletes them, export anything you want to save, or keep a Local Mirror (a plain copy of the graph). See Keeping A Local Copy Of A Synced Graph for more information.