Settings → Agents
This page gathers the coding agents that work with Mnemosyne OS. The rail entry is Agents. The title carries a Beta badge. The subtitle reads The coding agents that run on these machines.
The page has three tabs: Connect, herdr and Machines. The page remembers the last tab you picked. A link from elsewhere in the app can open a given tab without changing that memory.
Connect
The Connect tab holds two cards. The first connects a coding agent that runs on this computer. The second opens a door for an agent that runs elsewhere.
Connect my coding agent
This card lets your coding agent reach the app's two MCP servers: the memory server and the actions server. The agent can then set up Mnemosyne OS for you. The same panel shows on the first screen of the setup wizard.
The card shows one row per agent. The names are product names, the same in
every language: Cursor, Antigravity and Claude Code.
For Cursor and Antigravity, the row has a Connect button. It writes the
two servers into the agent's config file. The app keeps every other server of
that file. Cursor's file is .cursor/mcp.json and Antigravity's is
.gemini/config/mcp_config.json, both in your home folder. Once both entries
are in place, the row shows Connected.
A row can also say:
| Line | Meaning |
|---|---|
| Not found on this machine | The agent is not installed. |
| Its config file is not valid JSON: left as it is | The app refuses to rewrite a broken file. |
| A Mnemosyne entry is already here: it will be replaced, a copy of the file is kept | An entry the app did not write. |
| Half connected: the actions server is missing | Only one of the two entries is present. |
| Points at an older install of the app | The entries launch an older copy. |
A press of Connect can fail with:
| Line | Meaning |
|---|---|
| AppImage: use the line above | The AppImage path changes at each launch. |
| The MCP servers are missing from this build | The build carries no server. |
| The config file could not be written | Writing failed. |
| Development build: connecting an agent is off here | A dev build refuses to connect. |
For Claude Code, the app writes no file. The row shows two claude mcp add
command lines, each with a Copy button. Run them in a terminal.
The card can warn above the rows:
- This build does not carry the MCP servers
- Development build: connecting an agent is off here
- This AppImage moves at each launch. Add this line to the agent instead:,
followed by
npx -y @mnemosyne_os/mcp.
The card ends with Restart the agent, then tell it: and the sentence to type: Set up Mnemosyne OS for me. Both lines stay on the card.
If the app cannot read the agents of this machine, the card says Could not read the agents of this machine.
For the MCP package itself and manual setup, see Connect Claude to Mnemosyne OS.
Remote agents
This card opens a door for an agent that runs on another machine or in the cloud. Grok Bot, ChatGPT and Claude.ai are examples. The agent reaches your memory through a URL protected by OAuth. You approve each new connection in a Mnemosyne OS dialog. The card title is Remote agents. Its subtitle reads A remote agent (Grok Bot, ChatGPT, Claude.ai) reads and writes the memory through a protected URL. Each connection is approved here.
The door needs Tailscale to publish its URL. While the card reads its state, it says Reading the state…. If the read fails, it says The door’s state could not be read. with the code and a Retry button.
Where memories go and what the agent reads
Memories are written in is a list of vaults. The default write vault is
named GROKBOT. The list never offers a vault with MAXIMUM protection.
When the chosen vault does not exist, the list shows {{vault}} (does not exist). Two cases follow:
| Line | Case |
|---|---|
| The vault {{vault}} will be created when the door opens. | No vault of that name exists anywhere. The open button then reads Create {{vault}} and open the door. |
| The vault {{vault}} does not exist. Create it (isolated) in the Vault Manager, or pick another one. Until then, writes are refused. | A vault of that name exists but is out of reach. |
The created vault mixes with no other vault. What a remote agent writes stays apart from your memory.
Readable vaults is a row of checkboxes, one per vault offered. The hint reads The write vault is always readable.
Tools that cross the door
Tools that cross the door lists four checkboxes. By default, read and
write are ticked.
| Box | Note |
|---|---|
| read | Read the chosen vaults. |
| write | Write in the write vault. |
| dream bridges (all vaults) | Tagged reaches beyond the chosen vaults. |
| developer (coding agents, git) | Tagged reaches beyond the chosen vaults. |
Agents already approved
This choice says what a change does to the agents already connected.
| Choice | Effect |
|---|---|
| Get what is ticked later (default) | Ticking a box or adding a vault applies at once to the agents already connected, without a new question. |
| Are approved again one by one | A new box, a new vault or a new write vault disconnects the agents. Each one reconnects and sees an approval window with the new list. Choosing this mode disconnects nobody. |
Each change in these sections is saved at once. The app refuses a value it does not offer and says why.
Opening the door
Open the door starts the door. It reads Opening… while it starts, then Close the door. When the write vault must be created first, the button reads Create {{vault}} and open the door. Opening can take up to a minute: the app reads Tailscale and waits for the door.
Under the button, one line says where the tunnel stands:
| Line | Button |
|---|---|
| Reading Tailscale… | none |
| Tailscale is not installed. The door needs it to publish a URL. | Install Tailscale, which opens https://tailscale.com/download |
| Tailscale is not running on this computer. | none |
| Tailscale is waiting for a sign-in to an account. | none |
| Funnel must be allowed on the tailnet to publish the URL. | Allow Funnel, when Tailscale gives a link |
| Publishing the URL… | none |
| The tunnel stopped. | none |
Once the tunnel has printed the URL, the card shows it under URL to paste in the agent’s connector, with a Copy button. The hint reads Grok Bot: grok.com/connectors, then Custom. The URL printed after your press of Open the door is copied once by itself. The card then says Address copied: paste it in the agent’s connector.
When an agent asks for access, a line says the request waits for your answer in the app's approval window.
Connected agents and calls
While the door is open, Connected agents lists each agent by name, with a Remove button. With none, it says No agent connected.
The last call shows as one line, with its age:
| Line | Outcome |
|---|---|
| Last call: {{tool}}, {{ago}} ago | answered |
| Last call refused: {{tool}}, {{ago}} ago | refused |
| Last call failed in the memory: {{tool}}, {{ago}} ago | failed |
With more than one call, a fold Last {{n}} calls lists up to 8 calls. Each line gives the tool, answered, refused or failed in the memory, and the age.
When the door does not start, the card says The door did not start. with the code. Known codes get their own sentence.
| Sentence | Code |
|---|---|
| The door is not in this installation. | DOOR_BUNDLE_MISSING |
| The memory server is not in this installation. | MEMORY_SERVER_MISSING |
| The write vault has MAXIMUM protection: pick another one. | WRITE_VAULT_PROTECTED |
| The write vault could not be created. | NO_WORKSPACE_ROOT, WRITE_VAULT_NOT_CREATED, VAULT_CREATE_FAILED |
| The door is already opening. | ALREADY_STARTING |
The next build reshapes this card in five ways.
A default setting and a setting per agent. The choices above become Default setting (every new agent gets it). Under Connected agents, a hint reads An agent can be set once it is connected. A new agent gets the default setting. Each agent row gets a list with follows the default setting and its own setting. Its own setting starts as a copy of the default. It shows the agent's own Readable vaults and its own boxes.
A driving level. The choice Driving Mnemosyne OS sets how far an agent may drive the app. Each level includes the one before.
| Level | Label |
|---|---|
| none | none |
| look | look: actions that only read (graph, lists, states) |
| propose | propose: plus questions shown in the app, answered here |
| drive | drive: plus opening apps, running their actions, changing things |
Three more boxes. They follow the driving level.
| Box | Note |
|---|---|
| make pictures, video clips and avatar films | Tagged as spending credits. |
| ask for a review of a video or a picture (review panel, phone) | Review panel. |
| send files to this computer (PDF, pictures, videos; 12 MB each) | Files sent to this computer. |
Full control ticks read, write, the three boxes above and the drive
level in one press. It leaves the two boxes that reach beyond the chosen
vaults as they are. Its hint reads Memory, driving at the top level and media
in one click. Files made come back to the agent as 24-hour links.
A choice of who reaches the door. It is saved at once and applies at the next opening.
| Choice | Note |
|---|---|
| The internet (Tailscale Funnel) | The default. For agents that call from their cloud: Grok Bot, ChatGPT, Claude.ai. The address is public, guarded by OAuth and the approval here. |
| My tailnet only (Tailscale Serve) | For an agent on a device of the tailnet: a server, a phone, OpenMausBot. The address exists only inside the tailnet. |
When the door is open on the other choice, a line says Applies at the next opening of the door. On the tailnet, some lines change:
| Line | Replaces |
|---|---|
| HTTPS must be allowed on the tailnet to serve the address. with Allow HTTPS | The Funnel line and Allow Funnel. |
| Opening the address on the tailnet… | Publishing the URL… |
| Reachable from the devices of the tailnet. | The Grok Bot hint under the URL. |
| A Tailscale Funnel already publishes this computer on the internet. The door opens on the tailnet once that Funnel is stopped. | New: a Funnel already runs here. |
A reopen at start. A new checkbox reopens the door when the app starts. It connects Tailscale if Tailscale is only stopped, and a notice says so each time. After such a start, the card says Reopened at start, as ticked.
herdr
herdr is a terminal multiplexer made by another publisher. It runs coding
agents in terminals and shows which one waits for an answer. The heading
herdr is hardcoded. The card text reads herdr runs the coding agents
(Claude Code, Codex, Hermes…) in terminals and shows which one is waiting for
an answer.
The app installs its own pinned copy of herdr. The card says where the install stands:
| Line | State |
|---|---|
| Checking herdr… | Reading. |
| Could not read herdr’s state. | The read failed. A Try again button follows. |
| herdr has no build for this machine. | No build for this system. |
| herdr is not installed yet. | Not installed. Downloads {{mb}} MB, checked before launch. follows. |
| herdr {{version}} is installed. | Installed. Installed on {{date}}. and the program path follow. |
Install herdr starts the install. Progress reads Step {{n}} of {{of}}: {{stage}}, with the seconds elapsed. The four stages are downloading, checking the file, putting it in place and trying it. A bar shows only while bytes are counted. Stop cancels: Install stopped.
The install can fail:
| Sentence | Cause |
|---|---|
| The file received is not the expected version. It was deleted. | Checksum mismatch. |
| The file received is incomplete. It was deleted. | Size mismatch. |
| herdr was downloaded but does not answer as expected on this machine. | Version check failed. |
| The download failed. Check the connection and try again. | Download error. |
| The download stopped: no data for 2 minutes. | Stalled download. |
| The install failed. | Any other code, shown beside it. |
The card ends with two lines. The first gives herdr's licence, Apache-2.0. The second says that herdr downloads its agent detection rules and checks for an update on the internet when it starts.
herdr running
Once herdr is installed, the card reads its state every 3 seconds:
| Line | State |
|---|---|
| herdr is running. Agents on the board: {{n}}. | Connected. |
| Connecting to herdr… | Connecting. |
| herdr is closed. Open it to run agents. | herdr said it is not running. |
| Could not ask herdr whether it is running ({{error}}). An antivirus may be blocking it. | The status call failed. |
| herdr is running, but the connection failed ({{error}}). Close herdr and open it again. | The server refused. |
Open herdr opens herdr in a terminal. If it cannot, the card says Could not open a terminal. with the code.
Start an agent
While herdr runs, the card adds Start an agent. Its hint reads The agent must already be installed on this computer. herdr starts it in a new terminal, in this folder.
- Pick the agent
In Agent, pick one of these names, hardcoded in the app:
Claude Code,Codex,Gemini CLI,Hermes,OpenCode,GitHub Copilot CLI,Cursor,Qwen Code. Claude Code is the default. - Pick the folder
Press Choose a folder. The line Folder shows the path, or Choose a folder first.
- Start
Press Start. It reads Starting…. On success the card says Started: {{name}}. Its card is on the board.
A failed start says This folder does not exist. or The agent did not start., with the code.
Machines
The Machines tab holds My machines. It links your own computers that run Mnemosyne OS, never other people's. Its text reads The other computers with Mnemosyne OS. Once paired, the agents of each one appear and are driven on the board of the other. The My machines manual page walks through it.
Pairing needs P2P. The line Turn on P2P in Settings › P2P, then add the other computer as a contact. shows while P2P is off.
With P2P on and no contact, the card says First add the other computer as a contact in Settings › P2P. It will appear here.
Pairing
- Ask from one computer
Pick the other computer in the Contact list and press Pair this computer. This side then says Waiting for {{label}}. Check that its screen shows this code, then accept there., with a 6-digit code and a Cancel button.
- Compare on the other
The other computer says {{label}} asks to join these machines. with the same code. Under it: Accept only if the other screen shows the same code.
- Accept
Press Same code: accept only when both codes match. Refuse turns the request down.
Paired machines are listed with connected or not connected. Remove asks for a second press: Press again to remove. When the other side forgot this computer, the row says so and asks you to remove it and pair again. The card ends with Each computer keeps its own license. Pairing signs a certificate with both wallets.
Pictures drawn by another machine
The checkbox This computer draws the pictures my other machines ask for declares this computer's role. Its hint reads With this computer's graphics card and local image engine. Untick to refuse. Each paired machine's role shows as {{label}} draws pictures, {{label}} draws nothing for the others or {{label}}: role not known yet.
Under Ask a machine for a picture, pick the Machine, type the Picture description (2,000 characters at most) and press Send. Each task is a line with its state:
| Line | State |
|---|---|
| waiting for {{label}} for {{ago}} | The machine is off or unreachable. The task waits. |
| sent to {{label}} | Delivered. |
| {{label}} has been drawing for {{ago}} | Running. |
| arriving from {{label}} | The picture is coming back. |
| ready, {{ago}} ago | Done. Open opens it with the system viewer. |
| failed | With the reason. |
The cross on a line is Remove from the list.
A refused action shows its sentence and the raw code. Some examples:
| Sentence | Code |
|---|---|
| P2P is off on this computer. | NODE_OFFLINE |
| The other computer is not connected. | NOT_CONNECTED |
| The request expired. Start again from the other computer. | NO_PROPOSAL |
| The two clocks are too far apart. | STALE |
| The other computer runs a version without this feature. | NO_MACHINES |
An unknown code shows The operation failed. and the code.