Your notes, in your own folder

A Local knowledge graph keeps your notes as ordinary markdown files in a folder you choose on your computer. There is no server and no account required: the files are your notes. You can open them in any other editor, back them up, or sync them with a tool like git or Syncthing - they are plain text and they are yours.

Status: works in Chromium-based desktop browsers (Chrome, Edge, Brave, Arc, and similar) on Windows, macOS, and Linux. Firefox and Safari - including everything on iPhone and iPad - cannot open a local folder yet, because they do not offer the browser feature EtherPK needs. On those, you will be able to use a Server graph instead (coming later).

Choosing your folder

When you create a Local graph, EtherPK asks you to pick a folder. Choose an empty folder (or one you are happy to dedicate to this graph). EtherPK sets up a tidy structure inside it - journals/, pages/, assets/ - and from then on your notes live there as files.

You only do this once per graph.

Will I have to choose the folder every time I open EtherPK?

No - you never re-pick the folder. EtherPK remembers which folder each graph uses.

What can happen is that, when you come back to EtherPK in a new browser session, the browser asks you once to confirm that EtherPK may still read and write that folder. It is a single click - "Let this site edit files in MyNotes?" - not choosing the folder again.

This is the browser keeping you safe: a website is never allowed to quietly reach into your files in the background. EtherPK shows a clear "Grant access" (or "Reconnect") button when this is needed, and you are straight back into your notes.

How to stop being asked

If the once-per-session confirmation is annoying, you have a few options, simplest first:

• Install EtherPK as an app. In a Chromium browser, use Install (the icon in the address bar, or the browser menu). Once EtherPK is installed as an app, the browser remembers your folder permission, so the prompt goes away.
• Keep using the same browser and profile. The permission is tied to the browser profile you granted it in; switching browsers or using a private/incognito window will ask again.
• Visit regularly. Browsers increasingly remember access for sites you use often, so the prompt tends to fade with regular use.

Whatever you choose, your notes are never at risk here - they are sitting in your folder the whole time. The prompt is only about reconnecting EtherPK to them.

Editing your notes outside EtherPK

Because your notes are just files, you can change them with another app, or have git or Syncthing update them. EtherPK is built for this:

• When you switch back to EtherPK, it notices files that changed on disk and quietly brings them up to date.
• If a file changed on disk and you had unsaved edits to that same file in EtherPK, it stops and asks you which to keep - keep mine or take the version from disk. It never silently overwrites your work or merges behind your back.
• If a file disappears (for example, a git checkout removed it), EtherPK simply updates its list rather than breaking.
• If you change a page's title: in another editor, EtherPK treats it as a rename that has already happened: the open tab follows the file to its new name within a few seconds. See Titles Aliases And Frontmatter.

Handing a file to an AI agent or another editor

Right-click a document's tab (press and hold on a phone) and pick Copy full file path to clipboard. You get something like /home/you/notes/pages/Weekly Review.md, ready to paste into a prompt or an "open file" box.

Browser restrictions mean EtherPK only ever learns the name of the folder you picked, never where it sits on your disk, so the first time you use this on a device it asks you for the folder's full path and remembers it. If the path is wrong or the folder moves, change it under Settings → General → Folder path on this device. It is remembered on that device only and never leaves it: a path on your laptop means nothing on your phone, and it is never written into the graph.

The AGENTS.md and CLAUDE.md in your folder

Next to journals/, pages/ and assets/ you'll find an AGENTS.md. EtherPK writes it the first time it opens the folder, and it's there for exactly the situation above: a coding agent (Claude Code, Codex, an editor's chat) reads a file of that name before it touches anything, and this one tells it what the folder is, how the files are laid out, how the markdown is written (bullets, links, tasks, images) and, most importantly, what it must leave alone - the scrambled body of a protected document (see Protecting Sensitive Documents) and the etherpk/ folder, either of which is ruined by a well-meaning edit. It links back to these docs for the detail.

There's a CLAUDE.md beside it too. Claude Code reads that name rather than AGENTS.md, so the file just pulls AGENTS.md in; there's nothing in it you need to read. If your notes folder sits inside a bigger project, Claude Code picks the file up on its own as soon as it touches a note in there. Other agents look for AGENTS.md in the folder they were started in and its parents, not below it, so for those add a line to the project's own AGENTS.md saying where the notes are and to read their AGENTS.md first.

The file is yours. Add your own instructions to it - "never touch the Archive page", "always link new pages from the journal" - anywhere outside the part between the <!-- BEGIN ETHERPK --> and <!-- END ETHERPK --> lines. That part is EtherPK's, and it's rewritten every time the graph opens so it always matches the version you're running; anything you type inside it is lost on the next open, and anything outside it is kept exactly as written. The same goes for CLAUDE.md. If you delete either file, EtherPK just writes a fresh one. Using AI Agents With Your Notes has the fuller picture, synced graphs included.

If access is ever lost

If you move the folder, revoke permission, or clear your browser data, EtherPK may no longer be able to reach your notes. Nothing is lost - the files are still on your disk. Just open the graph again and reconnect (or re-pick the folder if it moved).

What EtherPK keeps private to your browser

A few things - like the search index that makes find-as-you-type fast - are kept inside your browser's private storage, never written into your folder. Your folder holds only your notes and their attachments. If that private index is ever cleared, EtherPK simply rebuilds it from your files; you lose nothing.