A mental bridge between a hacker and their LLM(s) of choice.
noid docs memories project agent-interface.md
3.3 kB · 22 lines
Markdown
at main


name: agent-interface description: noid's MCP server for agents - one stdio server (mcp.js) per agent, serving any vault named per call; the vault lock decides who writes graph.edn; one pure core (noid.agent) runs in both direct and relay mode. metadata: type: project #

Approved by Arcadia 2026-09-26 (tasks: the agent interface, slices A and B). Vault per call approved by Arcadia 2026-09-27 (task 09).

  • Agents change files with their own tools. The MCP tools cover only what the file system can't express: the graph, authorship, activity, and move_file (a rename that keeps connections).
  • Every tool takes a vault argument (an absolute path; --vault is only an optional default), so one user-scope registration per agent serves every vault. Any existing folder may be a vault. The server realpaths it, and main compares realpaths too. A read-only call on a folder with no .noid/ answers from a scan and creates nothing; the first write creates .noid/. Agents are told vault paths; there is no discovery tool yet.
  • Only the holder of <vault>/.noid/lock writes graph.edn. noid holds it while the vault is open. An MCP server holds it for one tool call at a time (a 30 s lease, plus a token checked before writing).
  • noid closed (or open on another folder): the server works in direct mode, reading graph.edn and scanning the folder under the lock. noid open: the server relays over a local socket, and the renderer applies the call as an action.
  • noid.agent/plan is the one pure implementation of every tool, shared by both modes.
  • Permissions follow "add, not override", between agents too: an agent may retype only an untyped connection or one it typed; disconnect only its own connections; write only its own note; claim only files with no author. The human may override anything from the UI. move_file is allowed on any file, because refusing would push agents to mv, which strands connections on a ghost.
  • Every graph.edn writer checks, right before writing, that its lock token is still in .noid/lock: the MCP server before each write or move, and the app in save-graph! (it re-acquires if the token is gone). Taking over a stale lock isn't atomic; the token checks are the real guarantee. Never add a graph.edn write path without one.
  • The app lock records :socket only while electron.agent is actually listening (electron.agent/listening-path, passed in by electron.ipc), because the mcp server treats an unanswering socket as a dead app and takes over the lock. A recorded-but-dead socket would let an agent write under a live app, which then overwrites that write on its next save. The socket lives at noid.lock/socket-path: <userData>/noid-<pid>.sock, falling back to tmpdir when the path is over 100 bytes (macOS caps socket paths at 104), or a named pipe on win32. It isn't kept in tmpdir, because tmp cleaners delete it.

Why: Arcadia chose MCP over folder conventions, wanted agents to work while noid is closed, and wanted several agents per vault. Later (2026-09-27) she wanted the vault chosen at call time, so one registration works from any session.

How to apply: new agent capabilities are new noid.agent tools with pure plan cases. Never write graph.edn without holding the lock. See [[connection-model]] and [[board-architecture]].