EtherPK

Where Your Data Is Stored

Each graph in EtherPK has one original. For a local graph, that is a folder of Markdown files on your device, and no other copy exists. For a synced graph, it is on the Sync Server in Managed Sync, and your device encrypts it before sending it there.

Everything else is in browser storage, the site data EtherPK keeps in one browser on one device. Other browsers and devices cannot see it, and clearing the site data deletes all of it. Most of it is a copy or an index of the original, which EtherPK can rebuild from the folder or download again from the Sync Server. Some of it exists only in the browser and cannot be rebuilt: edits and files that have not reached the Sync Server, Agent Chat chats and the demo graph.

Local graphs

A local graph's folder is the original, so Forget graph and clearing the site data both leave your files on disk (see Local Graphs). The graph's notes are ordinary Markdown files, and other editors can read them (see Graph Folder Layout).

EtherPK saves a protected document with its body as ciphertext and its title and aliases readable. The protection key is in etherpk/protection.json, wrapped under your protection passphrase, so back that file up along with the documents. See Protected Documents for more information.

Synced graphs

The Sync Server stores your documents, images and files encrypted, and never sees your notes or their titles, the graph's name and settings, or your images. It does see your account, the graphs you belong to, and the size and timing of the encrypted data. See How Encryption Works for more information.

It also keeps your Encryption Keys, sealed so that it cannot read them. On a new device, you unlock them with your Recovery Code or with approval from another device. The Recovery Code holds no notes, so it cannot bring back a document deleted from every copy (see Recovery Code And Device Approval).

Each browser where you open a synced graph keeps its own copy, stored readable. Anyone who can use that browser can read all of it except the bodies of protected documents. Only the sign-in or lock screen on your device protects the copy, not a device passcode.

Edits the Sync Server has not received yet, and files you add without a connection, wait encrypted in the browser and nowhere else (see Working Offline). If you clear the site data before the graph shows Synced, you might lose them.

The demo graph

The demo graph lives only in private browser storage and is never backed up, so clearing the site data deletes everything you wrote in it. A phone browser can also delete it to free space. Either way, EtherPK builds a fresh demo on your next visit. To reset it yourself, see Managing Your Graphs.

Browser storage

Browser storage holds the graph list, access to local graph folders, search indexes and the copies of synced graphs. It also holds the Encryption Keys you have unlocked, encrypted under your Device Passcode if you set one. Passkeys for protected documents, per-device settings such as the layout, and Agent Chat chats are there too, and they never sync.

Clearing the site data deletes those Encryption Keys, so you need your Recovery Code or approval from another device to reopen a synced graph.

Storage cleared by the browser

A phone browser can clear the larger part of the site data to free space, unless it has agreed to keep the data. EtherPK keeps a second copy of your synced graph list and your passkeys in the part that survives, so both come back the next time EtherPK loads. Edits and files not yet sent are lost, and EtherPK downloads the documents again from the Sync Server.

The This browser section on the This Device tab of the Graphs page shows whether the browser has agreed. Installing EtherPK as an app can encourage the browser to agree. See Installing EtherPK As An App for more information.

Sign-out and shared computers

Sign out of EtherPK hides your synced graphs until you sign in again, and leaves local graphs alone. It also locks the Encryption Keys on the device, so signing in again takes your Recovery Code or approval from another device. The browser keeps the copies, with their search indexes, images and files, per-device settings and Agent Chat chats, so remove them before you leave a shared computer.

Remove them from the Synced graphs in this browser section on the This Device tab, which covers every synced graph opened in this browser by any account. Before deleting anything, Remove checks for changes the Sync Server has not received. If any documents have them, it shows how many and lets you choose Download unsent changes or Discard changes and remove. That count leaves out files waiting to upload, which are deleted with the copy.

Remove then deletes the copies with their search indexes, remembered tabs, images, files and Agent Chat chats, and locks the Encryption Keys held in the browser. The graphs themselves stay on the Sync Server, and you can add them to the device again.

Summary by kind of data

Data Local graph Synced graph
Notes and graph settings The folder (the original) Encrypted on the Sync Server, readable in each browser
Images and files The assets folder Sync Server and browser, encrypted
Protected documents Body encrypted in the folder Body encrypted in every copy
Graph list This browser This browser, and membership on the Sync Server

Data sent from the device

The browser on your device reads and writes a local graph, so none of its content leaves the device unless one of the features below sends it. For a synced graph, EtherPK sends the Sync Server encrypted data, along with identifiers, your account and membership details, and byte counts for your plan limits.

  • Spell Check downloads dictionaries from the EtherPK dictionary host and sends no text.
  • Images for Maps come from the EtherPK map host, which learns the area you are viewing.
  • Extensions from the Extension Directory can read the documents in open graphs, protected ones included, and send them to other websites.
  • Agent Chat sends the chat from your browser to the model provider you chose, not to EtherPK.
  • A published site holds only the documents marked public for it, and never a protected one (see Publishing Your Notes As A Website).
  • The Headless Client serves your notes to a coding agent on the computer where it runs, and refuses protected documents.

Backups

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.

Keep your Recovery Code outside EtherPK. Protected documents open only with your protection passphrase or a passkey. A forgotten passphrase cannot be recovered, and a passkey stays on the device where you bound it, so bind passkeys on more than one device.

Before you clear the site data or retire a device, open each synced graph while online and check that its sync status is Synced. That status counts edits to documents, but not files still waiting to upload. See The Graph Sidebar for more information.

  • Choosing Where To Store Your Notes
    • The demo graph holds sample content for trying the editor. It lives in private storage in this browser only, so it opens in any current browser with no account or folder. Nothing backs it up, so keep your real notes elsewhere: clearing the browser's site data loses your changes, and your next visit after that starts a fresh demo. See Where Your Data Is Stored for more information.
  • Device Passcode
    • Because the passcode does not protect the copies of synced graphs, remove them before you leave a shared computer. On the This Device tab, select Remove under Synced graphs in this browser. See Where Your Data Is Stored for more information.
  • EtherPK On A Phone
    • Edits to a synced graph wait in browser storage until they reach the Sync Server. If the phone runs short of space, the browser can clear that storage, and any edits still waiting there are lost. If you install EtherPK as an app, the browser usually keeps that storage. See Where Your Data Is Stored and Installing EtherPK As An App for more information.
  • Glossary
    • | browser storage | The data EtherPK keeps in one browser on one device, which no other browser or device can see. | Where Your Data Is Stored |
  • How Encryption Works
    • Each browser keeps a readable copy and a search index of every synced graph it has opened, for every account that has used it, so only the device lock protects them. See Where Your Data Is Stored for more information.
  • Local Graphs
    • Your browser reads and writes the files. It remembers which folder belongs to each graph and asks your permission to edit the folder. The search index and the list of graphs are kept in browser storage, not in the folder. If you clear site data, you lose no notes, and EtherPK rebuilds the index from the files. See Where Your Data Is Stored for more information.
  • Spell Check
    • A word counts as correct if one of your spelling languages accepts it, or if it is in the graph dictionary, a list of extra words for that graph. The app downloads each language's dictionary from dictionaries.etherpk.com the first time a graph needs it and keeps it on your device, so spell check then works offline. For what a download sends, see Where Your Data Is Stored.
  • Synced Graphs
    • Each browser where you use a synced graph keeps its own working copy, so the graph opens quickly and you can work offline. The main copy stays on the Sync Server. If you remove or lose a working copy, it can be rebuilt from the main copy, the same way a new device gets one. Edits that have not reached the Sync Server exist only in the browser where you made them, so check for Synced before you clear the browser's site data or remove the graph. See Where Your Data Is Stored for more information.
  • The Graph Sidebar
    • Edits that have not reached the Sync Server exist only on this device, so check that the status is Synced before you clear the browser's site data. See Where Your Data Is Stored for more information.
  • Troubleshooting
    • The browser cleared some of EtherPK's data to free up space. EtherPK restored what it could (the synced graph list and the passkeys for protected documents), but it cannot restore edits that had not reached the Sync Server. See Where Your Data Is Stored for more information.
  • Using AI Agents With Your Notes
    • You lose your chats if you lose this device or remove the graph from it. See Where Your Data Is Stored for more information.
  • Working Offline
    • Once the Sync Server has received every edit from this device, the sync status shows Synced. If you clear the browser data or retire the device before then, you lose the unsent edits, so check for Synced first. You lose waiting files the same way, but Synced does not mean they have uploaded. See Where Your Data Is Stored for more information.