Using AI agents with your notes

Coding agents - Claude Code, Codex, Copilot, Cursor and the like - can read and write your notes. How you connect one depends on the type of graph (Local or Synced):

Your graph is	Connect an agent by	Where it's set up
Local - a folder on your computer	Pointing the agent at the folder. EtherPK writes an `AGENTS.md` (and a `CLAUDE.md`) into it that tells the agent how the files work and what to leave alone.	Nothing to set up; the files appear the first time EtherPK opens the folder. Settings → Agents on the graph says where they are
Synced - kept on a Sync Server	Running the Headless Client, a small program on the agent's computer that signs in as one of your devices and serves the graph to the agent over MCP.	Settings → Agents on the graph, which shows the two commands

Both graph types have an Agents tab in the graph's settings: on a local graph it explains the files in the folder, on a synced graph it shows the commands. The two never cross over - a local graph has nothing to connect to, and a synced graph has no folder for an AGENTS.md to live in, because the Sync Server never holds your notes in a readable form. This page covers both.

Local graphs: the agent works in your folder

A Local graph is plain files in a folder you chose (see Your Notes In Your Own Folder), so an agent can read and edit it like any other project. Start the agent in that folder, or give it a file path - right-click a document's tab and pick Copy full file path to clipboard.

What EtherPK puts in the folder for the agent

The first time EtherPK opens a local graph it writes two small files at the top of the folder, beside journals/, pages/ and assets/:

File	What it's for
`AGENTS.md`	The file most agents read before they touch anything. EtherPK's part of it explains what the folder is, how the files are laid out, how the markdown is written (bullets and indenting, `[[links]]`, tasks and their tags, images and files, code and maths blocks, tables) and what must be left alone. It links back to these docs for the detail.
`CLAUDE.md`	Claude Code reads this name rather than `AGENTS.md`, so this one just pulls `AGENTS.md` in. There's nothing in it to read.

Both files are yours. Add your own instructions - "never touch the Archive page", "always link a new page from today's journal" - anywhere outside the part between the  and  lines. That part is EtherPK's: it's rewritten every time the graph opens so it always describes the version you're running, so anything you type inside it is lost on the next open, and anything outside it is kept exactly as written. If you delete either file, EtherPK writes a fresh one.

What the agent is told to leave alone

The two things a well-meaning edit can ruin, which is why they're stated up front in AGENTS.md:

Protected documents. A protected page is stored as scrambled text inside an ```etherpk-cipher block (see Protecting Sensitive Documents). The agent is told it can't read it, shouldn't try, and must never reformat, re-wrap or tidy it - one changed character and the document is unreadable, with no way back. If a task needs what's in a protected page, unlock it in EtherPK and do that part yourself.
The etherpk/ folder. It holds the graph's settings and, if you use protection, the wrapped key that opens your protected pages. Deleting or editing it loses them.

It's also told the things that quietly change meaning: two-space indenting for nested bullets, no markdown formatters, no stripping of trailing whitespace, one page per title.

Working alongside EtherPK

You can keep EtherPK open while an agent edits the folder. EtherPK notices files that change on disk and reloads them; if you also had unsaved edits to the same file, it stops and asks which version to keep rather than merging behind your back. See Your Notes In Your Own Folder for the detail.

When the notes folder is inside a bigger project

Claude Code finds the CLAUDE.md on its own as soon as it touches a note in the folder, even if you started it a few directories up. 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 live and to read the AGENTS.md in there first.

Synced graphs: the Headless Client

A synced graph's content only exists in readable form inside EtherPK on your devices; the Sync Server holds it encrypted and can't read it (see Where Your Data Lives). So there's no folder to point an agent at. Instead, the agent talks to the EtherPK Headless Client: a small program you run on the agent's own computer that signs in as one of your devices, keeps one graph in sync, and lets the agent read, search and edit it. It needs Node.js 22 or later.

Because the Sync Server never sees your notes in the clear, the Headless Client has to run where your keys are. That has one consequence worth knowing up front: agents that live entirely in the cloud can't reach a synced graph. Claude Code, Codex, Cursor and anything else running on a computer you control can.

Setting it up

Open the graph in EtherPK, click the cog for its settings and pick the Agents tab. It shows the two commands below with your graph and server filled in, and a Copy button for each.

Sign the computer in, once:
```
npx @appsoftwareltd/etherpk-mcp login --server https://server.etherpk.com
```
That's the managed service's Sync Server. If you self-host, give your own server's address instead; the Agents tab fills in whichever one this graph is on.

It asks for a Personal Access Token - make an account-wide one at your Sync Server's portal under Access tokens (the Agents tab links straight to it, and so does the account menu in EtherPK, on the managed service and self-hosted alike) - and then shows a short code and the address of your EtherPK. Open EtherPK there in a browser where you're signed in to the account and its graphs are unlocked - any page will do, it doesn't have to be a note - and a prompt appears with a code; confirm it matches and the computer holds your keys from then on. This is the same approval step as adding a phone, and nothing secret is typed into the terminal. If you'd rather use your Recovery Code (a server you reach over SSH, say), press r while it's waiting, or add --recovery-code up front.

When it's done it lists the graphs it can see, by name and id.
Tell the agent about the graph. Pick your agent in the Agents tab and copy the command it shows; for Claude Code it's:
```
claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --graph <graph id>
```
Codex has the same shape; Cursor and other tools take a small block of MCP JSON, which the tab shows instead. One Headless Client serves one graph - to give an agent two graphs, add it twice under two names.

That's it. When the agent starts, the Headless Client connects, catches up with the graph and stays connected while the agent works. Other members of a shared graph see it as a device called Agent on <your computer's name>, so an edit from an agent never looks like it came from nowhere.

What the agent can do

It can	It can't
List every page and journal entry, with aliases	Read or change a protected document - those are listed by name only, and every attempt is refused
Read a document, search the graph, follow backlinks, list tasks and their tags	Rename or delete a document, or touch images and files (do those in EtherPK)
Edit a document by replacing an exact piece of text, so its change merges with anyone typing elsewhere on the page	Replace a whole page in one go
Append to a page or to a day's journal entry (creating the entry), and create new pages	Reach any graph you're not a member of, or any other account - that's checked by the Sync Server on every request

Edits arrive in your open tabs the way another member's typing does, and an agent's four-space bullets are put on EtherPK's two-space grid as they land.

What the Headless Client keeps on your computer

Two things, both readable only by your user:

Your keys, in ~/.config/etherpk/mcp.json - the same trust as a browser you've signed in on.
A cache of each graph it serves, under ~/.cache/etherpk/mcp/. Without it, every start would download the whole graph again and rebuild its search index; with it, a restart only fetches what changed. Like a signed-in browser's own storage, it holds your notes readably, so treat the computer accordingly. Protected documents are never in it.

The cache is never the source of truth, and it keeps itself current the same way EtherPK's own tabs do:

On every start the Headless Client asks the Sync Server which documents have changed since it last looked and fetches only those. A document deleted elsewhere is removed; a page or entry it never saw is added.
While it runs, edits made in EtherPK or by other members arrive as they happen, and the agent's own edits are confirmed by the server before a tool reports them done.
A newer version of the Headless Client that stores the cache differently simply discards the old one and rebuilds it from the server. Nothing you do is needed.
logout deletes it along with the keys.

If a cache ever looks wrong, deleting ~/.cache/etherpk/mcp/ is always safe: the next start rebuilds it.

Stopping it

Revoke the token at the portal under Account → Tokens and the Headless Client is cut off the next time it talks to the server.
npx @appsoftwareltd/etherpk-mcp logout forgets the token and keys cached on that computer.

Anyone who can read your files on that computer can read this account and the cached notes (see above), so treat the computer accordingly; logout removes both, and revoking the token stops the account being reachable from there at all.

The two other ways to give an agent a synced graph

A Local Mirror. A synced graph can keep a live, read-only copy of itself as files on one computer (see Keeping A Local Copy Of A Synced Graph). An agent can read that folder; anything it writes there is overwritten by the next mirror pass, so it's for questions, not edits.
Copy and paste. For a one-off, the text of any page is yours to paste into a prompt.