Agent Chat · EtherPK User Docs

Agent Chat lets you ask a language model about your notes from inside a document. You connect a model provider with your own key, and EtherPK calls the provider from your browser, so EtherPK's servers never see what you send. The model can only read, and only what you allow in each chat. A chat stays on the device you had it on, and nothing goes into a document unless you save it there.

Agent Chat is for asking questions while you write. For an agent on your computer that reads and changes your notes, such as Claude Code, see Using AI Agents With Your Notes.

Connect a model

Open Settings > Agents in a graph, or the Agents tab on the Graphs page, and choose Add a model connection:

Choose the provider.
Paste your key, or for OpenRouter choose Connect with OpenRouter.
For a model on your computer or another server, enter the server's address.
Choose Check and list models, which also checks the key.
Choose the model a new chat starts on from the list, or type its model ID, and choose Add connection.

Provider	What you need
Anthropic (Claude)	A key from console.anthropic.com
OpenAI	A key from platform.openai.com
Google Gemini	A key from aistudio.google.com
OpenRouter	An OpenRouter account. Connect with OpenRouter makes a key for EtherPK that you can limit and revoke in OpenRouter's settings, or you can paste a key
A model on this computer (Ollama, LM Studio)	The server running, at a `localhost` or `127.0.0.1` address, and allowing requests from EtherPK's address (below)
Another OpenAI-compatible server	Its `https` address, and a key if it needs one

Your connections belong to you, not to a graph. They are the same on every graph, and on every device where you sign in to sync, kept encrypted in your account like your other settings. Members of a shared graph never see them. With more than one connection, the primary one comes first in every list and is the one a new chat starts on. Make primary chooses another.

Set a spending limit on each key with your provider. Your key is kept in this browser and in your account's Settings Vault (How Encryption Works). An agent you sign in with The Headless Client cannot read it.

Agent instruction, under the connections, is one instruction for every model in every chat, such as the language to answer in or how long answers should be. It is sent before your notes at the start of every question, up to 4,000 characters, and follows you to your other devices like your connections.

A model on your computer

Ollama and LM Studio refuse requests from a web page until you allow its address:

Ollama: set OLLAMA_ORIGINS to the address you open EtherPK at, then start Ollama again. The address in Agent Chat is http://localhost:11434/v1.
LM Studio: switch on Enable CORS in its server settings, or start it with lms server start --cors. The address is http://localhost:1234/v1.

Your browser may ask whether EtherPK may reach devices on your local network. Allow it. EtherPK reaches a model over plain HTTP only at localhost or 127.0.0.1. A model on another computer needs an https address, as another OpenAI-compatible server.

Start a chat

Type /Agent on a line, or press Alt+A. On an empty bullet the chat opens beside the bullet's dot, as a code block does. On a line with text it opens beneath the line, and under the document's last line it opens at the left edge. When the document already has chats, or a chat's document was deleted, you first choose New Agent Chat in the document or a chat to resume.

The chat starts small and grows once it has a question. Choose its model from the Model list, and type to narrow the list by a model's name or its connection's name.

Type a question and press Enter. Shift+Enter starts a new line, and Stop ends an answer early. Retry answers a failed or stopped question again, and Answer again asks for a new answer to the last one. Open in side panel moves the chat to the Agent Chats view (below).

The empty bullet a chat sits beside belongs to the chat: the cursor skips over it, and a tap or a click there does nothing. To type on that line, close the chat.

On a phone the chat opens over the whole screen. Close goes back to the document, where a line saying Agent Chat opens it again. Opening a document or the Agents settings from the chat closes it, so you see where you went. The Agent Chat button at the right end of the command bar opens a chat too: at the cursor while you are typing in the document, and at its end otherwise (EtherPK On A Phone).

In a journal entry or page that has not been created yet, a chat opens without creating it, whether you type /Agent or use the button. Saving turns into it creates it. Until then, This document has no text to send, and the chat says so.

What the model reads

Context, at the top of the chat, sets what each question sends with it. A chat opened on a bullet with other bullets beside or above it starts on Block siblings and ancestors, and any other chat starts on This document. You can change it at any time, and the chat notes the change.

Context	What is sent with each question
Nothing else	Only the chat
Block siblings and ancestors	The chat, the bullet's ancestors, and its siblings with what is under them
This document	The chat, and the document's text as it is now
This document and its links	The above, and every document the document links to directly
The whole graph	The above, and the model can search and read any other document (below)

Under each question the chat lists the documents sent with it. A linked document too long to send whole is left out and named.

With Block siblings and ancestors, This document or This document and its links, you can send without typing anything, when your notes already hold the question: the message box says Send block siblings and ancestors, for example. The turn then reads Sent block siblings and ancestors. Nothing else and The whole graph need a prompt, and the box says Prompt the agent.

Block siblings and ancestors is offered when the chat is open on a bullet. It is read from the document each time you ask. If you go on with the chat in the Agent Chats view, it sends the outline as it last read it, until you reload EtherPK. After that, open the chat on its bullet again with /Agent, or choose another context.

A protected document is never read, listed or named to the model, even while it is unlocked (Protected Documents). A link to one in a document you send stays in that document's text.

How the whole graph works

The model gets the document and its direct links, and tools it can use to find more. It decides which to use, and each use shows in the chat, such as Read Kitchen or Searched for "beans". Everything a tool finds is sent to the provider like the rest of the chat.

Tool	What it does
Search	Finds the documents whose text matches words, as Search does
Read	Reads one document by its name
List	Lists the graph's documents, newest journal entries first
Links	Names the documents one document links to
Backlinks	Finds the documents that link to a name
Tasks	Lists tasks, of one name or the whole graph

A model that cannot use tools cannot read the whole graph. The model picker leaves such models out while The whole graph is chosen.

Images and web search

When the model takes images, paste or drop an image into the message box, or use +. Large images are made smaller before they are sent.

Each chat on Anthropic, OpenAI or OpenRouter has a Search the web switch. It starts on or off as Search the web by default in the Agents settings says, and you can change it in each chat. The providers run the search themselves and charge for it. A Gemini connection and a model on your computer cannot search. The words searched for go to the provider's search, and text in a note the model reads can change what it searches for.

Save a chat into the document

Choose Save, and each turn gets a box at its top left. Untick the turns you do not want, or use Select all and Deselect all, and choose Save with the number of turns. The turns are written beneath the line the chat sits under, as ordinary blocks you can edit, search and link:

- Agent Chat with Claude Opus 5 on 2026-10-15
  - What should I plant beside the beans?
    - Marigolds, as your [[Garden]] notes suggest.

A saved turn shows a document icon under its question. Images in the saved turns are added to the graph as files, and a bar shows how many have been added while they upload. While the chat stays open, your ticks are kept: a turn not yet saved starts ticked, a new turn arrives ticked, and a turn unticks itself once saved. A second save is written as a new block beneath the one before.

The Agent Chats view

The Agent Chats tab in the right sidebar lists every chat of the graph kept on this device, saved or not. A chat is kept from its first question: one you close before asking anything is not kept. Choose one to read and continue it there. Its document opens beside it, and Save writes into that document.

Rename gives a chat a name of your own.
Delete, Delete ticked and Delete all remove chats from this device. A deleted chat cannot be brought back. What you saved into documents stays.
Removing the graph from this device deletes its chats too.

When a chat's document is deleted, the chat stays. You can read and continue it, but it can no longer read that document. To give it a document again, type /Agent in another document and choose it under Chats without a document.

Turn Agent Chat off

Agent Chat is an extension that comes with EtherPK. Switch it off in Settings > Extensions to remove /Agent, the Agent Chats view and its settings. The switch is for this device. Your chats stay, and come back when you switch it on again.