@appsoftwareltd/etherpk-mcp 0.3.0 → 0.4.1

package/README.md

@@ -1,12 +1,14 @@
 # @appsoftwareltd/etherpk-mcp
 
-The EtherPK **Headless Client**: an [MCP](https://modelcontextprotocol.io) server over one of
-your synced [EtherPK](https://etherpk.com) knowledge graphs, run on the same computer as your AI
-agent (Claude Code, Codex, Cursor and the like).
+An [MCP](https://modelcontextprotocol.io) server that gives your AI agent (Claude Code, Codex,
+Cursor and the like) one of your synced [EtherPK](https://etherpk.com) knowledge graphs, run on
+the same computer as the agent.
 
-EtherPK's Sync Server never sees your notes in the clear, so nothing hosted can serve them to an
-agent. This program signs in as one of your devices, holds your keys, keeps one graph in sync and
-speaks MCP to the agent beside it. Protected documents are listed by name and never served.
+EtherPK's Sync Server never sees your notes in the clear, so nothing hosted can serve them. This
+program is EtherPK's **Headless Client**: to the Sync Server it is one of your devices - so it can
+hold your keys, read a graph and keep it in sync. To your agent, it is an MCP server.
+
+Protected documents are listed by name only, never served.
 
 Needs Node.js 22 or later.
 
@@ -32,7 +34,7 @@ npx @appsoftwareltd/etherpk-mcp login --sync-server https://sync.etherpk.com
 
 # Tell the agent about the graph (Claude Code shown; the Agents tab has the others).
 claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server https://sync.etherpk.com --graph <graph id>
-```
+```client
 
 `npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs each signed-in account can reach, by
 name and id. For a scripted setup, `ETHERPK_PAT` and `ETHERPK_RECOVERY_CODE` stand in for the
@@ -67,10 +69,48 @@ unique old→new replacement that merges with anyone typing elsewhere on the pag
 `append_document` (a page, or a day's journal entry, created if needed) and `create_page`.
 One running instance serves one graph.
 
-## What it keeps on your computer
+## Searching by meaning
+
+`search` matches words. With one more step it can also match **meaning** - "when do I pay my
+taxes" finds the note that says "due 31 January" - by running a small embedding model on this
+computer; nothing is sent anywhere, and protected documents are never embedded. Once per
+computer:
+
+```sh
+npx @appsoftwareltd/etherpk-mcp semantic setup     # ~300 MB runtime (via your npm) + a 23 MB model, into the cache dir
+```
+
+Semantic setup installs the native runtime into `~/.cache/etherpk/mcp/runtime/` and the three
+model files into `~/.cache/etherpk/mcp/models/all-MiniLM-L6-v2-int8/`.
+
+- **Any order, no restart.** Run it before or after registering the agent, even while an agent
+  is connected: a running `serve` notices within 30 seconds and starts building; until
+  then a search by meaning is refused with this command in the message, so the agent can tell
+  you what to run. Nothing in the registration changes (`--no-semantic` on `serve` is the only
+  switch, to keep one agent text-only).
+- **What the agent gets.** `search` accepts `mode: "semantic"` (and `"hybrid"`, both groups
+  side by side). Every result carries the document, its kind, the breadcrumb of headings and
+  parent bullets, the passage's 0-based line range and its text with a similarity score - the
+  agent is told to cite them. Passage text has bullet markers and `[[ ]]` stripped: right for
+  quoting, wrong as the `old` text of `edit_document`, which should come from `read_document`.
+- **Progress.** The first pass over a large graph takes minutes and runs in the background;
+  after that only edits are processed. `semantic status` lists each cached graph with how many
+  passages are done; every semantic result says `embedded`/`total` and `complete`; run by
+  hand, `serve` prints a line every 30 seconds. `semantic remove` deletes runtime and model.
+- **Load on the machine.** The first pass uses a quarter of the cores, at most four, and pauses
+  between model calls; `ETHERPK_MCP_SEMANTIC_THREADS=8` in the registration's `env` makes it
+  faster and hotter. `ETHERPK_MCP_DEBUG_MEMORY=1` logs the process's memory if you ever need
+  to see it.
+- **One cache directory for both.** Setup and `serve` must see the same cache root - by default
+  `~/.cache/etherpk/mcp` (`C:\Users\<you>\.cache\etherpk\mcp` on Windows). If you set
+  `ETHERPK_MCP_CACHE_DIR` in your shell, put it in the agent registration's `env` too, since
+  the agent spawns `serve` with its own environment.
+
+## What this client keeps on your computer
 
 - **Keys**: `~/.config/etherpk/mcp.json`, one entry per Sync Server, readable only by your user -
-  the same trust as a browser you've signed in on.
+  the same trust as a browser you've signed in on. (On Windows both paths sit under your user
+  folder: `C:\Users\<you>\.config\etherpk\` and `C:\Users\<you>\.cache\etherpk\`.)
 - **A cache of each graph you serve**: `~/.cache/etherpk/mcp/`, so a restart catches up on what
   changed instead of downloading everything again. It holds your notes readably, like a signed-in
   browser's own storage does. It is never the source of truth: on every start the Sync Server is
@@ -78,7 +118,8 @@ One running instance serves one graph.
   newer version of this program discards a cache it no longer understands and rebuilds it.
 
 Revoke the token at the portal to cut the agent off, and `npx @appsoftwareltd/etherpk-mcp logout`
-to forget that server's keys and delete its cache on that computer (`--all` for every server).
+to forget that server's keys and delete its cache on that computer (`--all` for every server,
+which also removes the semantic runtime and model).
 
 ## Building and publishing