EtherPK User Docs

Local Graphs

A local graph is a folder on your device that EtherPK opens as a graph. Each note is a Markdown file in the folder, with journal entries in journals (one file per day) and named pages in pages. Images and other files go in assets, and graph settings go in etherpk.

You do not need an account or a server for a local graph. The files are the only copy of your notes, so use your own tools, such as Git or Syncthing, to back up the folder and copy it to other devices. EtherPK encrypts only protected documents, so anyone who can open the folder can read the rest of your notes.

EtherPK reads and writes the folder through your browser, which remembers the folder for each graph and asks you for permission to edit it. The search index of your notes is kept in the browser as well, never in the folder. Clearing browser data loses no notes, and EtherPK rebuilds the index from the files.

Other programs, such as a text editor, Git, Syncthing or a coding agent, can change the files while the graph is open. EtherPK checks the folder for changes every few seconds and whenever you switch to its window.

A local graph cannot become a synced graph. To put its notes in one, import the folder into a new synced graph with Import on the Graphs page. The import leaves the folder unchanged. See Importing A Knowledge Base for more information.

Before you begin

You need Chrome or Edge on a computer, or Chrome on Android. If the Graphs page has no Open folder (Local Graph) button, your browser cannot give a website access to a folder. See Choosing Where To Store Your Notes for more information.

Open a folder as a graph

  1. On the Graphs page, select Open folder (Local Graph).
  2. In the folder picker, choose the folder.
  3. When the browser asks, allow EtherPK to view and edit the files.

EtherPK creates whichever of the four folders are missing and opens the graph under the folder's name. Renaming the graph in EtherPK (Managing Your Graphs) does not rename the folder on disk.

Only the Markdown files directly inside journals and pages are read as documents. To bring in notes from another app, use Import instead.

Folder access

When you open the graph later, the browser might ask for permission again. In a browser tab on a computer, it asks once per browser session. If you install EtherPK as an app on a computer, the permission carries over between visits, so the question stops appearing. On Android, Chrome asks every time you open the graph, even in the installed app. See Installing EtherPK As An App for more information.

Open on the Graphs page asks for permission before it opens the graph. If you refuse, the graph stays closed and its row says that permission was denied.

EtherPK asks for permission itself when it starts up and when you open a graph from its address. If you refuse or dismiss the question while the graph is opening, you see the message "EtherPK needs permission to read and write this graph's folder." Select Grant access to be asked again. If you have not clicked anything yet, the browser might not ask at all, and the graph stays closed. In that case, open it from the Graphs page.

Automatic saving

EtherPK saves each edit to its file shortly after you stop typing, so there is no save command and Ctrl+S (Cmd+S on a Mac) does nothing.

If a save fails, a notice tells you why and what to do. Until a save succeeds, your edits are only in the open tab, so select Retry saving before you close or reload the tab.

Changes made by other programs

When another program changes a file, EtherPK reloads the document, unless you have unsaved edits in it. It never merges two versions of a file, so in that case it shows the External change dialog. Select Keep mine to write your version over the file, or Take disk to replace your edits with the version on disk.

Markdown files that another program adds to journals or pages appear as new documents, and files removed from those folders drop out of the graph. If another program changes the title in a file, EtherPK treats the change as a rename (Titles Aliases And Frontmatter). For EtherPK to read a file, the file must follow the rules on Graph Folder Layout.

Copy the path of a file

A browser tells a website only the name of the folder you picked, so the first time you copy a path on a device, EtherPK asks where the folder is. Copy agent instruction asks the same question, and you can skip it there (Tasks).

  1. Right-click the document tab.
  2. Select Copy full file path to clipboard, below Copy name to clipboard. The Copy full file path to clipboard item, outlined, at the foot of the menu that opens on a right-click on a document tab
  3. If EtherPK asks for the folder path, enter it and select Remember and copy.

Instructions for coding agents

EtherPK writes AGENTS.md and CLAUDE.md at the top of the folder to describe the folder to coding agents. Each time the graph opens, EtherPK rewrites the section of each file between the BEGIN ETHERPK and END ETHERPK lines, so anything you type inside it is lost. Put your own instructions above or below that section, where EtherPK leaves them alone. See Using AI Agents With Your Notes for more information.

Reconnect a graph to its folder

If a graph's folder has been moved, renamed or deleted, the graph does not open and a message says that its folder could not be found on disk. To reconnect the graph:

  1. On the Graphs page, find the graph and select the cross button in its row.
  2. In the Forget graph dialog, select Forget. The files stay on disk.
  3. Select Open folder (Local Graph) and pick the folder where it is now.

Other browsers and profiles do not list the graph, and neither does this browser after you clear its data. To use the graph there, add the folder with Open folder (Local Graph). See Where Your Data Is Stored for more information.

  • Choosing Where To Store Your Notes
    • Your edits go straight into the files. The notes are plain Markdown, so other editors, Git, sync tools and coding agents can work on them alongside EtherPK, and whatever they change shows up in the graph. See Local Graphs for more information.
  • Glossary
    • | local graph | A folder of Markdown files on your device, with no account or server. It is the only copy of your notes, so backups are up to you. | Local Graphs |
  • Graph Settings
    • | Folder path on this device | Record where a local graph's folder is on this device. The MCP command on the Agents tab uses the path, and the first time you use Copy full file path to clipboard in a document tab's menu or Copy agent instruction on a task or a lane, EtherPK asks for the path. See Local Graphs. |
  • Managing Your Graphs
    • The Graphs page has buttons for creating a graph, with a row below them for each of your graphs and its actions. See Local Graphs and Synced Graphs for more information on creating a graph.
  • Pages And Wikilinks
    • On a local graph, a Markdown file you add to the pages folder also becomes a page. See Local Graphs for more information.
  • PDFs: Reading, Annotating and More
    • On a local graph, the annotations and form values for each PDF sit in one file in the folder, etherpk/pdf-<hash>.json. Annotations reach another device only if you sync the folder with your own tool, but if the file conflicts in that tool, you lose one side. If the file is damaged, EtherPK does not write over it, and a message above the pages gives the reason. Changes to that PDF are not saved until you fix or remove the file and open the PDF again. See Local Graphs for more information.
  • Running EtherPK On Your Own Computer
  • Scoped Concepts
    • Search reads the brackets in a name as spaces, so typing garden tools finds [[Garden]] Tools. In Local Graphs, the inner brackets stay in the file name, as in pages/[[Garden]] Tools.md. See Graph Folder Layout for more information.
  • Tabs And Panes
    • The same menu also has Copy name to clipboard and, in a graph kept in a folder on your computer, Copy full file path to clipboard. See Local Graphs for more information. For the rows that act on the document itself, see Keyboard Shortcuts.
  • Titles Aliases And Frontmatter
    • On a local graph, when another editor or an agent changes a page's title, the app treats it as a rename that has already happened. You see a notice, and the open tab follows the page to its new name. Links to the old name stay as they are, because the other program rewrote none of them and the app leaves them alone. To point them at the new name, right-click one of those links, select Rename… and enter the new name. See Local Graphs for more information.
  • Troubleshooting
  • Using AI Agents With Your Notes
    • A local graph is a folder of plain Markdown files, which an agent opens like any project. Start the agent in the graph folder and there is nothing else to connect. See Local Graphs for more information.
  • Where Your Data Is Stored
    • 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).
  • Working Offline
    • EtherPK runs in your browser. After you open it once with a connection, the browser keeps the app files on your device, so EtherPK can start without one. Because Local Graphs are folders of files on your device, the app files are all they need to work offline.