Agent Chat & MCP Server
memrynote can run an in-app Agent Chat backed by a provider-neutral agent backend. Claude CLI is the first full backend, local OpenAI-compatible servers can be used for BYO local models, and the Codex CLI backend uses the same contract when enabled. After a vault opens, the desktop app keeps the Agent runtime idle until Agent Chat or Agent MCP is opened. At that point it starts a local MCP endpoint on 127.0.0.1 with a random port, then gives the selected backend only the vault tools for the current conversation.
Opening the Agent MCP settings uses the same lazy start path as opening Agent Chat. If the runtime is still starting, memrynote retries the status check until the vault-scoped endpoint, bearer token, and tool list are ready to copy.
The Agent runtime and MCP endpoint are scoped to the open vault. Closing or switching vaults stops active turns, clears pending tool approvals, and restarts the Agent services for the next vault. The MCP endpoint is stopped with the vault even if the Agent runtime itself failed to start, so the next vault always gets a fresh endpoint and bearer token instead of the previous vault's.
The same MCP endpoint can also be copied into other desktop AI clients for vault read tools.
Open Settings -> AI Assistant -> Agent MCP to copy the current endpoint and bearer token. Open Settings -> AI Assistant -> Agent Permissions to set the default Agent Chat access mode and action-confirmation behavior.
Agent Chat
Open the right sidebar, choose Agent, and pick a provider. The compact Day/Agent switch keeps the active view highlighted at the top of the right sidebar, and switching to Agent takes effect on the first click even when the sidebar opened on the Day view. The assistant backend still starts up on first use rather than at launch, so the panel can show a brief loading state while providers and conversation history are detected. The Agent header includes a new-conversation button, a history menu for switching back to recent conversations, and a pop-out button for moving the current conversation into a workspace tab. On Windows, where the window's minimize, maximize, and close buttons share that row, these three actions sit in one More agent actions (...) menu instead. Popped-out conversations keep the generated conversation title as the tab name, use the same centered reading column as notes, and leave the right sidebar ready for a new chat. The popped-out tab keeps the scroll bar at the window edge while the chat content stays centered, and the tab name is the only conversation title shown in that workspace view. Assistant responses render as full-width text in both the sidebar and popped-out tabs instead of bordered bubbles, with text aligned to the prompt input. For Claude CLI, memrynote checks that claude is available on PATH, that it reports version 2.1.0 or newer, and that the Agent disclosure has been accepted; the Codex CLI and the Antigravity CLI (agy, version 1.2.7 or newer) are detected the same way. On macOS and Linux, memrynote resolves your login shell's PATH at startup, so CLIs installed in shell-managed locations (~/.local/bin, Homebrew, nvm, volta) are still found when the app is launched from the Dock or Finder rather than from a terminal. These checks run in the background rather than pausing the app, and a successful check is reused for a few minutes so a burst of turns does not re-run it. A failed check is never remembered: if you install or upgrade a CLI while memrynote is running, the next message or provider check picks it up without a restart. If the CLI is removed, replaced, or loses its executable bit between that check and the moment a turn actually starts, the turn ends right away with a Claude CLI failed to start: ... (or Codex CLI failed to start: ..., Antigravity CLI failed to start: ...) error naming the reason, and the conversation is free to accept a new message as soon as the CLI is back. A CLI that is not detected is not hidden: the composer's model picker still lists the Claude, Codex and Antigravity sections with a muted "Not detected — set up in Settings…" row that opens Settings -> AI Assistant -> Agent Permissions, where a CLI agents group shows the live detection status of each CLI (version when found) alongside install and sign-in instructions (claude login / codex login / a first interactive agy run).
Antigravity models carry their own reasoning tier in the model id (gemini-3.1-pro-high versus -low), so picking an Antigravity model replaces the separate reasoning control rather than adding to it. Any model id your Google account can reach can be typed in, not only the listed presets.
When the model exposes its reasoning (Claude thinking, Codex reasoning summaries, and local models that stream reasoning), the reply opens with a "Thinking…" block that follows the reasoning as it arrives. Once the answer starts, the block folds into a "Thought for Ns" line you can click to reopen. If the model thinks again later in the same turn, for example between tool calls, the line shows "Thinking…" again but stays folded. An open block keeps the newest reasoning line in view unless you scroll up inside it; scroll back to its bottom to follow again. The reasoning is stored encrypted with the reply and is only displayed: it is never sent back to the model in later turns or in conversation summaries. Antigravity does not report its reasoning, so its replies show the plain thinking indicator.
If a reply has started and then nothing new arrives for 3 seconds, the thinking indicator comes back under the partial answer with a timer counting from the last thing received. It goes away as soon as more text or reasoning arrives, and when the turn ends. With reduced motion the timer still counts but does not animate. If you are reading at the bottom of the chat, the chat scrolls to keep the indicator in view; if you have scrolled up, it leaves your position alone.
Unlike the other two CLIs, Antigravity has no per-run configuration flag: it reads MCP servers from ~/.gemini/config/mcp_config.json and tool permissions from a project file, both at process start. So the first Antigravity turn registers one app-managed entry named memry in that file (every other MCP server there is preserved) and writes a memry-agent-vault / memry-agent-computer project that grants the vault tools and denies shell commands. No credential is written to either file: the endpoint token and the turn's single-use write capability travel in the spawned process's environment, which the bridge it launches inherits. A mcp_config.json that cannot be parsed is left untouched and the turn fails with a message naming the file. If you already had an MCP server named memry there, it is replaced by the app-managed one. Your own agy sessions also list the memry server; outside a running memrynote turn its tools report that no turn is active. For local models, configure a compatible server in Settings -> AI Assistant -> Agent Permissions first. If the global AI switch is off in Settings -> AI, the Agent tab and Agent MCP current-note bridge are hidden and inactive.
Agent Chat can:
- keep local conversation history in the vault database
- attach the active note as context for a turn
- mention notes, tasks, journals, inbox items, and calendar events inline in a prompt with
@ - attach small text files, such as a log or a CSV, to a prompt without importing them
- stream assistant text back into the sidebar, with each new word resolving out of a soft blur
- link returned or created memrynote items directly in assistant replies, showing cited items as inline citation chips and listing all of them behind a source count under the reply
- fold a turn's tool calls, tool results, and optional approvals into one collapsed activity row
- stop an in-flight turn
- compact older conversation history when a prompt grows too large
Naming a new conversation and compacting its history both run the CLI in the background. A CLI that prints a lot of diagnostic output while doing so no longer stalls the turn: memrynote reads that output as it arrives rather than waiting for the CLI to finish. If the CLI then fails, the tail of that output is written to the local log, the conversation falls back to a title derived from your first message, and the turn continues with its history uncompacted — your message and the conversation are never lost.
Each compaction folds the previous summary into the new one, so a long conversation keeps its start (your goal, the decisions made, and the notes and tasks the agent created) however many times it compacts. Conversations that an older version compacted more than once get back the earlier summary and the messages between the two summaries on their next message.
Conversation history is stored encrypted, so every message you send has to decrypt the transcript before the agent can see it. memrynote reads and decrypts that history once per message and reuses it for the rest of the turn, so sending a message into a long conversation costs the same single pass whether or not the turn also compacts. Long conversations stay responsive instead of getting slower with every reply.
While a turn runs, its tool calls collapse into a single activity row instead of stacking one row per step, so a long turn no longer pushes the answer off screen. The row names the tool the agent is running, counts the steps so far, and shows a spinner until the turn ends. Once the turn is done the row settles to a step count, and selecting it expands the individual tool calls with their parameters and results. A tool that needs your approval keeps the row open, because the Allow and Deny buttons live inside it.
Tool activity is saved with the conversation, encrypted in the vault database like the rest of the transcript. Reopening a conversation later — after a restart, after a sync, or after memrynote has dropped an older transcript from memory — still shows which tools ran, with what parameters, and whether each one succeeded, failed, or was denied. The saved record is deliberately smaller than the live one: it keeps the tool name, its identifying parameters (long values are shortened), and the outcome, but not the tool's returned data. Only tools that finished are recorded, so a turn stopped mid-tool leaves no half-finished row behind. Conversations from before this was added simply show no tool rows; nothing else about them changes. Saved tool rows are a record for you, not context for the assistant — they are never replayed into a later prompt.
When a tool result includes a real memrynote reference, Agent Chat renders that item as a clickable mention instead of plain text. Lists link each returned note, task, inbox item, journal entry, calendar event, project, or folder that has a navigable reference. Create and update confirmations also link the affected item when the tool returns its ID or journal date. Inbox snooze confirmations use the same explicit inbox item reference as other inbox writes.
Every finished reply carries an action row. Copy hands you the markdown the assistant wrote, not the flattened text on screen, so it pastes into a note with its formatting intact; the button acknowledges the copy for a moment and then returns. Next to it, replies that cited memrynote items show the first few item icons and a source count — 3 sources — that expands into the full list. Each row in that list opens the item and names its type on the right. A reply that cited nothing shows only Copy.
A link the reply also cited renders as an inline citation chip: a compact pill carrying the item's icon and its title, shortened when the title is long. Source references arrive over the course of a turn, so a link can appear as running text first and settle into a chip a moment later, without the text around it being redrawn. Links memrynote did not cite stay as ordinary item mentions.
Both the blur-in on streaming text and the chip's arrival stand down when your system asks for reduced motion; the reply still updates, it just does so without the movement.
memrynote only links explicit tool-provided references. Plain titles without an ID or date stay as normal text. Uncited item mentions use memrynote's standard link color, show a dotted underline on hover, and display the matching item icon before the title. Each link shows exactly one icon: the item's own icon when it has one, otherwise the icon for its type. Note icons are read directly from the vault, so a linked note shows the same custom icon it has in the sidebar even while the reply is still streaming, and regardless of which agent backend produced the link. When a backend writes an item's emoji into the link text itself, memrynote moves that emoji into the icon slot rather than showing it next to a generic one. Inbox items use their capture-type icon, and journal, calendar, and task links use the same visual language as the main app surfaces.
Press Enter to send the prompt. Press Shift+Enter to insert a new line in the prompt box.
When a CLI backend is selected, send stays disabled until that CLI has actually been detected — including the brief check that runs as a conversation opens. A send button that is greyed out for a moment on open, or that stays greyed out, means the CLI has not been found; the CLI agents group in settings shows the detection status and the install hint.
Type @ in the prompt to open the mention picker. Notes, tasks, journals, inbox items, and calendar events appear with their item icons, and calendar events are read from the local calendar with archived events hidden. Choosing a result replaces the active @ query with one inline tag, so a prompt such as summarize @Star Wars Movies keeps the referenced item visibly attached inside the prompt. Mention tags submit as readable @Title text plus an encrypted structured attachment reference.
The picker waits for a brief pause in typing before it searches, so typing a long mention runs one search rather than one per character. The list always reflects the last thing you typed — a slower search for an earlier query is discarded rather than shown.
The prompt box uses the operating-system text editing menu, so Cut, Copy, Paste, Select All, and native right-click editing work like other text fields.
Attaching a text file
To ask about a file without importing it into the vault, click the paperclip in the prompt bar or drop the file onto the prompt box. Agent Chat accepts .txt, .md, .log, .csv, .tsv, .json, .yaml and .yml files that are UTF-8 text, up to 100 KB in total per message. Each file shows as a chip with its name and size, and the chip's remove button takes it off the message. A binary file, a file of another type, a file that takes the message over the limit, or a file that cannot be read (for example, one moved or deleted after you picked it) is refused, and the prompt box says why.
When you send, the file text is added to the end of your message as a fenced block whose first line is memry-file name="app.log" bytes=2048, so the model sees the file name and size with the content. The transcript shows the block as a collapsed card with the file name and size; click it to read the content. The file is not copied into the vault. Its text is stored only in the message, which is encrypted and syncs like any other message. Older app versions show the plain fenced block.
Agent memory
Claude, Codex and Antigravity turns run in one folder per vault, kept in the app's data folder and outside the vault: agent-workdirs/<vault id>. A vault id that is not a plain uuid is hashed into the folder name. Claude Code keeps its project memory for that folder, so what the agent saves about the vault in one turn is still there in the next turn and in the next conversation. Nothing in this folder syncs.
Settings -> AI Assistant -> Agent Permissions -> Clear agent memory asks first, then deletes the folder and the project memory Claude Code keeps for it. This cannot be undone. Notes and chat history stay. The next turn starts with an empty folder.
Dictating a prompt
The microphone in the prompt bar records a prompt and types it for you. Click it once to start recording — the icon turns red and nothing else on the bar moves. Click it again to stop; the icon becomes a spinner while the audio is transcribed, then the text is appended to whatever is already in the prompt box.
Dictation uses the same engine as inbox voice memos, so it needs a transcription backend configured first — see Voice Transcription. Audio recorded here is transcribed and discarded; it does not create an inbox item. If the microphone is blocked at the operating-system level, memrynote points you at the relevant privacy settings.
Queueing a message while the agent works
The prompt box stays editable while a turn runs. Press Enter, or the arrow button next to Stop, and the message waits in a Queued messages list above the prompt box instead of interrupting the turn. When the turn ends, the oldest queued message goes out as its own turn, then the next one when that turn ends. Nothing is added to a turn that is already running. Stopping a turn also counts as its end, so the next queued message goes out after Stop.
Each queued message keeps the model, permissions and context it was sent with. Use the pencil to change its text or the cross to remove it before it goes out. While the next message's editor is open, the queue waits for you to save or cancel. If memrynote cannot send a queued message, it stays in the list marked Not sent and holds the messages behind it, including new ones you send; edit it to send it again, or remove it to let the rest go out. Pressing Stop while a queued message is on its way stops that message's turn too. A queued message that goes out only after you press Stop, because the turn ended on its own first, is not stopped. After Stop the cursor returns to the prompt box. The queue lives in the window it was typed in and is not saved, so reloading the window clears it. Switching to another vault marks every queued message Not sent, so nothing goes out to the vault you switched to. Switch back to edit and send it, or remove it.
Connected tools
While Google Calendar is not linked, a tray peeks out below the prompt box offering it. Clicking the Google Calendar icon opens the same consent dialog as the Connect Google button on the calendar page, and the tray disappears once the account is linked — from either place.
Stop requests are scoped to the active conversation across Claude, Codex, and local providers. Automatic title generation and conversation summaries run through the selected backend without exposing memrynote MCP tools.
Stop works from the moment you send a turn, including the pause before the backend starts answering — while a local provider is being checked for streaming and tool support, or while Claude or Codex is launching. Pressing stop in that window ends the turn there instead of letting it run to completion in the background.
Stopping a turn — and quitting memrynote while one is running — asks the chat backend to shut down first, and forces it to close if it has not stopped shortly afterwards. Quitting waits for that to finish, so a backend is never left running in the background after memrynote is gone. A backend that has to be forced closed does not get to finish writing its own scratch files, so the unfinished reply is lost; your message and the rest of the conversation are kept.
The prompt bar holds four controls. The + button opens the mention picker and the per-turn permissions menu; a dot on the button means at least one permission differs from your defaults. The first chip shows the active provider and model, and its menu switches either. The second chip sets reasoning effort. The microphone dictates a prompt by voice, and the arrow sends the turn.
The provider is pinned per conversation; changing it after messages exist updates the conversation and records the switch in the chat history. Claude and Codex expose prompt-time reasoning effort settings, with provider-specific settings shown only for the active provider. The built-in model connection offers Default, High, and Max depth for any preset except Ollama; see Provider Setup. The permissions menu starts from your default Agent Permissions setting, then lets you send a single turn as Vault only or Computer access, and optionally allow web search for that turn.
Vault only keeps the CLI backend constrained to memrynote vault tools. Computer access gives the backend broader local CLI access for that turn. Web search is passed through only when the selected backend supports it.
The built-in model connection (local or custom OpenAI-compatible endpoints) has memrynote vault tools only: no shell, no files outside the vault, and no web search. With that backend selected, Computer access and Web search show as unavailable with the reason "Vault tools only with this model", and the turn runs vault-only with web search off. Your saved default does not change, so switching back to Claude, Codex, or Antigravity picks it up again. The prompt tells the model the same thing in its permissions section: "Runtime: built-in model connection. Tools: memrynote vault tools only." Agent Backends lists what each backend can reach.
Claude and Codex conversations also have a per-conversation model selector. memrynote starts Claude on opus and Codex on the highest suggested GPT version, then passes the selected model through to the CLI for each turn. The built-in model list is only a shortcut for common CLI aliases; type a custom model ID when you want to pin another CLI-supported model.
Local model support uses OpenAI-compatible HTTP APIs. memrynote ships presets for Ollama, LM Studio, and llama.cpp server, plus a Custom endpoint. Local tool access is gated by a capability probe. If the model can emit tool calls and continue after a tool result, memrynote enables the full vault tool set. If the probe fails, local chat can still answer from attached context, but vault tool calls stay disabled. The reply then starts with a note that vault tools are off for this model and why, in plain words: the provider refused requests with tools, the model answered without calling the test tool, the model failed after getting the tool result back, or the provider did not stream. When the provider sent its own error message, the note quotes it. The model gets instructions without any tool sections or tool names, and is told that tools are off and not to write tool calls as text. If it writes one anyway, the note adds that the model wrote a tool call as text and nothing ran.
Models call tools in different ways, and memrynote adapts to each provider configuration instead of asking you to. Hosted OpenAI-compatible APIs work through the Custom preset. The probe records what worked and every chat turn repeats it:
- The probe first asks the model to call a named tool, and retries without naming one when the provider rejects that, as DeepSeek does in thinking mode. The chat then sends no tool choice either.
- Reasoning models that return
reasoning_content(DeepSeek, and reasoning models behind LM Studio or llama.cpp) get it sent back between tool steps, and their reasoning shows in the reply. - Some servers return a model's tool call as plain reply text, as
<tool_call>{...}</tool_call>. memrynote reads these calls out of the text and runs them like any other tool call, also when the probe saw the model call tools the native way. Only the names of the vault tools count, so a model that quotes the syntax for another name keeps it as text.
The probe costs a couple of model generations, so memrynote runs it once and keeps the verdict until you change the preset, base URL, model, or API key, or restart the app. An unreachable provider is never remembered: start your local server and the next message picks it up. A temporary provider error during the tool check (network failure, timeout, rate limit, or a 5xx server error) does not turn tools off. That message keeps its tools, and the next message checks again. If you swap the model behind an unchanged configuration, press Probe Tools in Settings to force a fresh check.
A turn with tools on the built-in backend can make up to 24 model calls, and each tool round uses one. The model is told this budget at the start of the turn. The 24th call runs without tools and asks the model for a short handoff: what is done, what is left, and what to send to continue. The reply then ends with Stopped at the step limit and a Continue button. Continue sends "Continue" as a normal message in the same conversation with your current model and settings, so the agent picks up from the handoff in a new turn. Claude Code, Codex, and Antigravity turns have no step limit set by memrynote.
If the configured local provider is not running, the model picker returns no discovered models instead of treating the settings page as an Agent runtime error. Start the provider, then load models or test the connection again.
When no conversation is selected yet, the prompt box stays available. Sending the first prompt creates a new Agent Chat conversation, attaches the active note when one is open, and streams the reply into the sidebar.
New conversations start with a temporary title. When you send the first prompt, the selected chat backend also generates a short conversation title. memrynote stores that title on the encrypted conversation row and refreshes the sidebar title without giving the title-generation subprocess access to memrynote MCP tools.
If a turn fails partway through — a window closing while the reply is still streaming, for example — memrynote stops the chat backend it started for that turn instead of leaving it running in the background. The unfinished reply is lost, but your message and the rest of the conversation are kept, so you can send the prompt again. A turn that is simply taking a long time is never stopped this way. The same applies when a turn fails before the reply even starts streaming, such as a disk or database error while saving the empty reply.
When the provider or the chat backend reports an error, for example a local provider that rejects the request or a CLI that exits with an error, the reply shows as a red box. It says the reply stopped with an error and quotes the provider's own message. Your message is kept, so you can send it again. Errors from memrynote itself, such as a message or a Stop that could not reach the agent, show above the prompt box until the next message goes out.
Conversation rows, message bodies, and message attachments are encrypted at rest before they are written to SQLite. Free accounts keep agent chat history local-only. Paid accounts can sync finalized conversations and terminal messages through memrynote Sync; in-progress streaming messages are not enqueued until the turn finishes.
If memrynote cannot verify the local vault key for the current database, Agent Chat stays unavailable instead of opening unreadable conversation history. A fresh local vault can initialize a new local key without sign-in; an existing vault with a mismatched or missing keychain key must be recovered through the normal vault recovery flow.
Connection
The endpoint is:
http://127.0.0.1:<port>/mcpExternal MCP clients must send:
Authorization: Bearer <token>The token is generated in memory for the current app launch. It is not saved to disk, changes when memrynote restarts, and can be rotated manually from settings. Missing or stale tokens receive 401.
The localhost MCP endpoint can serve overlapping Agent Chat turns and external read requests. memrynote keeps the URL/token stable for the app session, but handles each MCP request with an isolated transport so one client connection does not block another.
If the operating system refuses a connection to the endpoint — for example when the app has run out of file handles — memrynote records the failure in the app log as an AgentMcpServer error and keeps the endpoint listening on the same URL and token. Individual client connections can be dropped, but Agent Chat and external clients can reconnect without restarting the app or reopening the vault.
Client-specific config keys vary. Use the copied URL as the MCP server URL and the copied token as a Bearer authorization header. External clients are read-only. The token admits a client to the read tools; it does not admit it to the write tools.
Every vault write has to be authorised by a turn memrynote itself is running. When Agent Chat starts a turn it mints a fresh single-use write capability, hands it only to the backend it spawns for that turn, and destroys it when the turn ends. The write tools accept nothing else. An external client holding the endpoint token, or a stale capability from a turn that has already finished, is refused with PERMISSION_DENIED and the reason that writes need a running memrynote Agent turn. A conversation id is not a credential: knowing one, even a real one, does not let a client write.
A note or folder the owner locked refuses every write tool, approved or not, with PERMISSION_DENIED and the message "The owner made this note read-only.", or "The owner made this folder read-only." when it adds something to a locked folder or renames, moves, or deletes the folder. This includes vault_desktop_write operations that report a refused write as { success: false }. The agent can still read it. Canvases are not lockable: the canvas tools never write a note's file, and the canvases folder does not appear in the folder tree.
External clients still see the write tools listed. They are advertised to every client because memrynote's own Claude CLI, Codex CLI, Antigravity CLI, and local-model backends discover their tools from that same list. Calling one without an active turn fails rather than writes.
A write is only approved for a conversation that still exists. A conversation that has been deleted — including one deleted on another device and carried here by sync — no longer counts as an existing conversation, so its write tools are refused rather than writing into a record that is gone from your chat history everywhere.
Closing the vault or quitting the app destroys every live write capability, so a backend that somehow outlives its turn cannot write afterwards.
Tools
The Agent API reference lists every tool and desktop operation with its parameters and a recorded example call and reply. The same schemas are published as JSON Schema at /agent-api/memry-agent-api.schema.json.
Read tools are available to Agent Chat and external MCP clients:
vault_search_notesvault_read_notevault_view_filevault_list_foldervault_get_current_notevault_list_tasksvault_get_taskvault_list_projectsvault_get_projectvault_list_statusesvault_get_journal_entryvault_list_journal_entriesvault_list_inbox_itemsvault_get_inbox_itemvault_get_tagsvault_list_canvasesvault_read_canvasvault_read_canvas_elementsvault_desktop_readvault_desktop_describememry_help_searchmemry_help_read
Memry help
memry_help_search and memry_help_read answer questions about using Memry itself, such as "how do I show a note on the calendar?". They search the user guide that ships inside the app, so they work offline and never touch the vault. The guide is in English, so the search works best with English feature words. The CLI and agent reference pages are left out, because Agent Chat answers these questions in plain steps, not in code.
Notes and filed files
Filing a PDF, image, audio file, or video into the vault indexes it alongside your markdown notes, so it can turn up in vault_search_notes. Every search hit therefore carries a file_type:
markdown— a real note.vault_read_notereturns its content. When the note embeds PDFs, images or HTML blocks from its attachments folder, the reply addsattachment_text: one{ file, text }entry per file with the text read from it, about 100 KB at most (attachment_text_truncatedsays when it was cut).vault_search_notesmatches the note on that text too.pdf,image— a filed file whose text Memry reads on this device: the PDF's own text layer, or OCR for scanned pages and images (see Text in PDFs and images).vault_search_notesmatches on that text, andvault_read_notereturns it asextracted_textinstead of markdown: one{ page, text }entry per page, astatusofextracting,done, orfailed,page_count, andpages_read. A reply stops at about 100 KB on a page boundary and namesnext_page; pass it back asfrom_pageto read on.audio,video— a filed file with no text.vault_read_noterefuses it with aVALIDATIONerror naming the file type instead of returning bytes for the client to treat as text.
vault_update_note refuses every filed file, so an agent cannot overwrite a filed document with markdown.
vault_update_note builds the update from the note file as it is on disk, so it reads the file before it writes. When another program holds the file and that read fails, it reads once more a moment later. If the second read fails too, nothing is written and the error names the cause, for example EBUSY.
Looking at images and PDF pages
vault_view_file hands the model an image, or one page of a PDF, to look at. It works on files already in the vault and needs nothing installed:
- a filed image or PDF: pass its
id. For a PDF,pagepicks the page, page 1 by default, one page per call. - an image or PDF that a markdown note embeds from its attachments folder: pass the note's
idand the file name asattachment, the name afterattachments/<note id>/in the note or thefileof anattachment_textentry.
The image is downscaled so its long edge is at most 1568 px and sent as image content, PNG or, for a large image, JPEG. A PDF page is rendered on this device by the same reader that extracts PDF text. The JSON part of the reply says what was sent: file, file_type, mime_type, width and height, source_width and source_height for an image, and page and page_count for a PDF. A page past the end fails with a VALIDATION error that names page_count.
A file that is a symlink to something outside the vault, or a symlink whose target is gone, fails with a PERMISSION_DENIED error that names its vault path and says it points outside the vault. So does a missing file inside a folder that links outside the vault, so an error never tells whether a file exists out there. Nothing outside the vault is read. A symlink to another file in the vault works, and so does a vault folder that is itself a symlink. Text extraction skips the same files, and drops text an earlier version read through such a symlink.
Notes and journal entries follow the same rule. A note or journal file replaced by a symlink to a file outside the vault fails every tool that reads or edits it with the same PERMISSION_DENIED error, notes.get through vault_desktop_read and notes.update or properties.set through vault_desktop_write included. A canvas file replaced that way reads as not found. So vault_read_note never returns text read from outside the vault.
Claude Code, Codex, and Antigravity receive the image from the MCP server as it is. For a local or OpenAI-compatible provider, Memry checks once whether the model takes images, by sending it a one-pixel image, and sends the picture after the tool result. A model that does not take images gets a text notice instead, so the turn goes on. The chat shows the call, but the image bytes are not kept in the chat history.
vault_list_folder lists a filed file as kind: "file" with its file_type, and a note as kind: "note" with file_type: "markdown". The approval for vault_delete_folder counts the filed files it would delete apart from the notes.
Checking that a write reached the server
vault_read_note, vault_search_notes, vault_list_folder (note entries), vault_get_journal_entry, and vault_list_journal_entries add a sync object to each note:
{ "state": "confirmed", "body_confirmed_at": "2026-10-07T10:00:00.000Z" }state is pending (changes waiting on this device, since waiting_since), sent (a push has no answer yet, last_sent_at), confirmed (the server stored the last text push at body_confirmed_at), not_recorded (nothing waiting, but no confirmed push recorded since the update that added this field), rejected (the server refused the latest push, last_rejected_at), local_only, or not_syncing. last_failed_at appears after a push that will be retried. Times are ISO strings and appear only when known. To check a write, read the note again until state is confirmed and body_confirmed_at is later than the write. A record push the server reports as already seen never counts as confirmed.
vault_add_html_artifact lets an agent put a diagram, chart, or small interactive explanation in a note. The HTML is saved as an attachment of that note and appended as a file block, which renders it inline in the same sandbox as an .html file you attach yourself: scripts run, https: resources load, but the page cannot read the vault or the app. It syncs like any other attachment. The HTML is capped at 512 KB and the call needs your approval. Its visible text is searchable under the note, and [[wiki links]] in it count as the note's links (see Text in HTML blocks).
Pass file_types to narrow the search up front — ["markdown"] for notes only, or ["pdf", "image"] to look for filed documents. The filter runs inside the search query, so limit counts only matching rows. Omit file_types to search every file type.
Notes indexed by older memrynote versions have no recorded file type; those are always treated as markdown, so upgrading never hides existing notes.
Acting on several notes
vault_bulk_tag_notes, vault_bulk_move_notes and vault_copy_notes take up to 100 note ids and ask for approval once for the whole batch. The approval card names the first notes and the count, and shows the tags added or removed, or the destination folder. The reply lists one result per id, ok or the error that note hit, and a failure on one note does not stop the rest.
vault_copy_notes copies markdown notes inside the open vault. Each copy has a new id and keeps the title, body and tags. Custom properties are not copied, and links to the original are not rewritten. The originals stay where they are. Copying into another vault is not supported.
vault_insert_at_cursor puts text and [[wiki links]] to other notes at the cursor of the note open in the editor. It fails when that note is not open, and it does not write the file directly: the editor saves the change like a keystroke.
Write replies
A write reply can carry a warnings list of plain sentences:
- A note or journal write whose stored body is not the body it sent says so with both byte counts. That includes
notes.createandnotes.updatethroughvault_desktop_write, whose replynote.contentis the stored body. Forvault_update_noteinappendorprependmode, and forvault_add_html_artifact, the body sent is the whole body the call asked the note to hold: the current body joined with the new text by one blank line, not the new text alone. The note is read back once any save it was waiting on has run. Line endings count, so an LF body saved into a CRLF note is reported. Only the final newline at the end of the body does not count. The body sent is measured after the checkbox step below, so a checkbox line stored with{check}or turned into a task is not reported. - While this device runs without its CRDT store, every write reply says so. Note edits are still saved to the vault and synced, but without merge history for that session.
warnings is the first key of the reply, so a reply cut at the size limit still starts with it. A reply that is not a plain object comes back as { warnings, result }.
Checkboxes in agent writes
A checkbox line an agent writes into a note or journal entry stays a plain checkbox: memrynote stores it as - [ ] Check the log {check}, and the editor never turns it into a task. Agents create tasks with vault_create_task. This covers vault_create_note, vault_update_note, vault_create_journal_entry, vault_update_journal_entry, and the notes.create, notes.update, journal.createEntry, journal.updateEntry, templates.create and templates.update operations of vault_desktop_write. It also covers the checkbox lines that notes.applyTemplate, inbox.convertToNote, inbox.convertToReminder, inbox.file, inbox.bulkFile, inbox.linkToNote, notes.importFiles and tasks.importFilesToProject write when an agent calls them, and the template body a note created by an agent starts from (a template it names, or its folder's template when the body is empty), whoever wrote the template, the inbox item or the imported file. A checkbox line that was already in the note before the write is left exactly as it was.
To let agents' checklists become tasks, turn on Turn checklist items in agent writes into tasks in Settings → Editor. The note and journal tools then create the tasks during the write and list each one in the reply as created_tasks, with its id and title. vault_desktop_write replies with the operation's own result, so its checkbox lines are left for the editor to convert when the note opens.
Folder paths
Every tool names a folder by its path from the vault root, with no leading slash: projects/active. That form appears in folder_path on notes and in path on vault_list_folder entries. Tools that take a folder path also accept the form with a leading slash, so /projects/active still works. A note directly in the vault root has a folder_path of null.
vault_list_folder fails with a NOT_FOUND error that names the path when the folder does not exist, so a stale or misspelled folder name no longer looks like an empty folder. An empty folder that exists returns an empty list. Omit path to list the vault root and find the right name.
Create, update, delete, archive, move, and reorder tools require Agent Chat context. They pause for inline approval unless you set the Agent Permissions confirmation to Always allow:
vault_create_notevault_rename_notevault_delete_notevault_create_foldervault_rename_foldervault_delete_foldervault_create_taskvault_delete_taskvault_complete_taskvault_uncomplete_taskvault_archive_taskvault_unarchive_taskvault_move_taskvault_reorder_tasksvault_duplicate_taskvault_convert_task_to_subtaskvault_convert_subtask_to_taskvault_create_projectvault_update_projectvault_delete_projectvault_archive_projectvault_reorder_projectsvault_create_statusvault_update_statusvault_delete_statusvault_reorder_statusesvault_create_journal_entryvault_update_journal_entryvault_delete_journal_entryvault_add_to_inboxvault_update_inbox_itemvault_snooze_inbox_itemvault_archive_inbox_itemvault_unarchive_inbox_itemvault_delete_inbox_itemvault_add_inbox_tagvault_remove_inbox_tagvault_update_notevault_add_html_artifactvault_update_taskvault_add_tagvault_remove_tagvault_move_to_foldervault_bulk_tag_notesvault_bulk_move_notesvault_copy_notesvault_insert_at_cursorvault_add_canvas_itemvault_remove_canvas_itemvault_create_canvasvault_draw_on_canvasvault_edit_canvas_elementsvault_desktop_write
Canvas
| Tool | What it does |
|---|---|
vault_list_canvases | Every canvas, with how many items sit on each |
vault_read_canvas | One canvas: the notes/tasks/events on it (with titles) and any text written on it |
vault_read_canvas_elements | The shapes on one canvas: ids, position, size, text, colors, arrow bindings |
vault_create_canvas | Create an empty canvas |
vault_add_canvas_item | Put existing notes/tasks/events on a canvas as cards |
vault_remove_canvas_item | Take a card off a canvas |
vault_draw_on_canvas | Draw shapes, text, arrows, lines, freedraw, frames, images and embeds |
vault_edit_canvas_elements | Move, restyle, retext or delete elements already on a canvas |
Canvas tools need the Spatial Canvas feature turned on (Settings → Features). With it off they return a message saying so rather than failing silently.
There are two ways to read a canvas, for two different questions. vault_read_canvas answers "what is on this canvas" — the notes, tasks and events, with their titles, and any text written on it. It returns no geometry, because a scene is mostly coordinates and style properties and dumping that into an agent's context crowds out everything useful. Long canvases cap the amount of text returned and say so with texts_truncated. vault_read_canvas_elements answers the other question — "where is everything" — and is the read to use before drawing: an element id from it is what an arrow binds to and what an edit changes.
Drawing
vault_draw_on_canvas takes Excalidraw's own element skeletons, in camelCase, so anything you can draw by hand you can ask for: rectangles, ellipses, diamonds, text, arrows, lines, freedraw, frames, images and embeds, with the full style vocabulary (strokeColor, backgroundColor, fillStyle, strokeWidth, strokeStyle, roughness, opacity, roundness, fontSize, fontFamily).
Two things make it a diagram rather than a pile of shapes:
- Refs. Give an element a
refand other elements in the same call can point at it. The response maps every ref to the id it became, so the next call can keep building on it. - Real bindings. An arrow with
startandend— either{"ref": "..."}for something in the same call or{"elementId": "..."}for something already on the canvas — is bound on both sides. It follows the shapes when you drag them, exactly like an arrow you drew yourself. Frames work the same way: children can be new elements or ones already there.
An agent cannot mint entity cards this way. A card is a rectangle carrying the entity reference that canvas_entity_refs is rebuilt from, so cards go through vault_add_canvas_item, which checks that the note/task/event actually exists. vault_edit_canvas_elements will move and restyle a card, but not rewrite its text — that text lives in the note.
Images need a fileId already attached to the canvas; agents cannot upload binaries.
Adding an item applies to the open editor when you have that canvas open, so the card appears while you watch instead of being overwritten by the next autosave. A canvas nobody has open is updated directly, and the write is rejected if it changed in the meantime. If the result is too large to sync, the tool response says so.
Some canvas operations are deliberately unavailable through vault_desktop_read / vault_desktop_write:
canvas.get— returns the whole scene; usevault_read_canvasorvault_read_canvas_elementscanvas.update— replaces the entire scene with no version check, which would overwrite whatever you have open; use the item and drawing toolscanvas.librarySave— saves the shape library as one whole list, so a partial one deletes shapescanvas.uploadAsset— binary image upload, no agent path yet
An arrow an agent draws is a picture, not a stored relationship. It is bound, it moves with the shapes, and it is genuinely useful on a diagram — but nothing queries it. When you want a connection the rest of the app can follow, use wiki links between notes or the project link layer; the arrow is the drawing of that connection, not the connection.
vault_desktop_read and vault_desktop_write cover the remaining desktop CRUD surface through an allowlisted desktop API operation name plus an args array. They are used for desktop domains such as templates, saved filters, bookmarks, reminders, calendar events, folder views, properties, tags, search reasons, inbox conversions, project links, and settings. The write bridge uses the same in-app approval flow as named write tools. Security-sensitive and system operations stay outside the allowlist, including account/auth flows, provider connect/disconnect/refresh actions, app updater actions, external open/reveal actions, import dialogs, OS settings panes, telemetry, feedback and diagnostics reporting, and raw secret writes. Unsupported or unavailable desktop API operations return a structured MCP error instead of falling back to an arbitrary desktop call.
A desktop API call on a filed PDF, image, audio file, or video, such as notes.get or notes.rename, returns the file's metadata in place of the note: id, path, title, fileType, mimeType, fileSize, created, modified, contentOmitted: true, and contentAccess, a sentence that says how the content can be read. For a PDF or an image it names vault_read_note, which returns the text read from the file (see Notes and filed files), and vault_view_file, which shows the image or a PDF page (see Looking at images and PDF pages).
A desktop API reply whose JSON is longer than 100 KB in UTF-8 bytes, counted after source links are added, comes back as { truncated: true, totalBytes, message, partial }. partial holds the start of the JSON reply, cut on a character boundary so the whole reply stays within 100 KB. It is not valid JSON on its own. message says what to call instead: a shorter date range for calendar.getRange, calendar.getRange with a date range for calendar.listEvents, and a list with a smaller limit or vault_read_note for anything else.
args are the operation's positional arguments. Every allowlisted operation has a schema for its arguments, and vault_desktop_describe returns it, so an agent can look a call up before making it. With operation, the reply names the tool that runs it (vault_desktop_read or vault_desktop_write), whether it needs approval, its parameters in call order and args_schema, the JSON Schema (draft 2020-12) of the args array with every type, required key, allowed value and default. Without operation, the reply lists every operation with its tool and call shape, such as notes.list(options?), where ? marks an argument the call may leave out. Where the app reads a null optional argument as left out, such as the options of notes.list, the tags of inbox.linkToNote or the days of tasks.getUpcoming, the argument also takes null, and its schema lists null as an allowed type. An operation that takes no arguments has no prefixItems in its args_schema, only "maxItems": 0. An operation whose last arguments are optional lists each call length it accepts as its own tuple under anyOf, so notes.list has one entry for [] and one for [options]. Strict validators such as Ajv refuse a prefixItems tuple that may stop early, and this form compiles under them.
{
"operation": "notes.ensurePropertyDefinition",
"tool": "vault_desktop_write",
"call": "notes.ensurePropertyDefinition(name, type)",
"requires_approval": true,
"params": [
{ "name": "name", "required": true },
{ "name": "type", "required": true }
],
"args_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "array",
"prefixItems": [
{ "type": "string", "minLength": 1 },
{ "type": "string", "enum": ["status", "select", "multiselect"] }
],
"minItems": 2,
"maxItems": 2
}
}Every call is checked against that schema before it reaches the app, and before the approval prompt for a write. A call that does not match fails with a VALIDATION error and nothing runs. The error names each field (the parameter name, then the key path inside it), the type it takes, the allowed values and what was sent, for example type: expected one of "status", "select", "multiselect", got "text" or scope: expected { kind: "folder", path: string } | { kind: "tag", tag: string, andTags?: string[] }, got "Projects". Its details.issues list the same as { field, expected, allowed, received }. A call that passes more arguments than the operation takes names the parameters instead. Options go inside the operation's input object, never in an extra argument. A key inside an input object that the operation does not take fails the same way and is named with its argument, for example notes.createPropertyDefinition does not take input.optionz or folderView.setView does not take view.colour. Every key the operation's handler reads is accepted; the open record of properties.set accepts any property name. A settings write takes any subset of that group's settings. calendar.getRange still takes the older (start, end) pair of strings, and calendar.listEvents its options as a JSON string.
A desktop write whose reply carries no record (adding an inbox tag, changing a setting, a property option, a tag color, pinning a note to a tag, saving a folder view, creating a folder) gets a stored field with the record read back after the write. Writes whose reply is already the record (create and update calls) do not need one. These writes reply without stored:
- Deletes, which leave nothing to read: every
delete*operation,bookmarks.bulkDelete,inbox.deletePermanent,notes.deleteFolder,notes.deleteVersion,tags.deleteCategoryandfolderView.deleteView. - Reorders, which reply
{ success }:notes.reorder,tasks.reorder,tasks.reorderProjects,tasks.reorderStatuses,savedFilters.reorder,bookmarks.reorder,homePages.reorderandtags.reorder. Read the list again to see the new order. - Bulk calls and conversions, which reply with counts or the new item's id: the
bulk*operations,inbox.fileAllStale,inbox.convertTo*,tasks.captureUrlToProject,tasks.importFilesToProjectandnotes.importFiles. inbox.trackSuggestion,search.rebuildIndex,search.clearReasonsandvault.reindex, which store no record.
If the write lands but the read after it fails, the reply is the write's own reply with a warnings entry that says so. The write is not reported as failed, so do not repeat it; read the record instead. Named write tools do the same.
properties.set(entityId, properties) replaces the entity's whole property record. It does not merge: a property the call leaves out is deleted. The legacy id, title, created and modified keys that older notes carry in their frontmatter are the exception for agents: they are kept when the call leaves them out, and a call deletes one only by passing it as null. Any key the call does not change keeps its line in the file byte for byte and in its place, whatever order the call lists the keys in, so created: 2024-03-05 stays exactly that. A value passed back as a read returned it is written as the file holds it, so a date stays a date. A new value for a key that holds a date and spells a real calendar date, such as 2026-10-09, is written as a plain date, not a quoted string (2026-02-30 stays text). The reply lists the stored properties and the names it removed, and spells a date as the file does (2026-10-07, or the full timestamp when it has a time of day). Stored note and journal records in write replies spell dates the same way, and so do the reads: properties.get values and the frontmatter that vault_read_note returns. The tag writers that edit a note's tags list (tags.renameTag, tags.mergeTag, tags.deleteTag and tags.removeTagFromNote) keep the other lines byte for byte too.
Named note, journal, task, project and inbox writes answer with the record as a read returns it after the write. The other named writes answer with what the write itself returned, as listed below. Every tool rejects an argument it does not take, at any depth (inside a list of statuses or canvas items too), before the approval prompt. The error names the key: Unknown argument: colour.
- Note writes (
vault_create_note,vault_rename_note,vault_update_note,vault_add_html_artifact,vault_move_to_folder, andvault_add_tag/vault_remove_tagon a note) reply withid,title,folder_path,tags,properties,body_bytesandbody_sha256. Both arenullfor a note too large to read.vault_update_notealso reportstags_addedandtags_removed, because inline#tagsin the new body change the note's tag set. - Journal writes reply with
id,date,tags,properties,body_bytesandbody_sha256. The journal writer keeps the user's keys and the legacyid,createdandmodifiedan older entry carries, byte for byte. It drops any other key Memry reserves, such as a legacyemoji, andvault_update_journal_entrylists what it dropped infrontmatter_removed. body_bytesandbody_sha256cover the body exactly as the file stores it after its frontmatter, in UTF-8. The file writer ends the body with a newline, so a body sent without a final newline is stored with one. Checkbox lines the agent added are stored with the{check}marker, or rewritten as the tasks they became when the owner turned on task conversion (see Checkboxes in agent writes). To check a write, hash what you sent with those two changes applied and compare. Any other difference means the stored body is not the one you sent.- A note or journal write that turned checkbox lines into tasks also lists them in
created_tasks. vault_create_noteandvault_move_to_folderlist the folders the call created increated_folders, shallowest first, when the folder they wrote into did not exist yet. So do thevault_desktop_writeoperationsnotes.create,notes.importFiles,notes.moveandinbox.filewith a destinationpath. They list only folders that exist once the write lands, so anew-notedestination, which ignorespath, lists none. Apathofrootis an ordinary folder calledroot; an emptypathfiles to the notes root, the vault root unless a default note folder is set. The field is absent when every folder already existed.- Task, project and inbox writes reply with the stored task, project or inbox item.
vault_create_statusandvault_update_statusreply with the status the task store returned from the write, not a fresh read. Reorders (vault_reorder_tasks,vault_reorder_projects,vault_reorder_statuses) reply with the ids and the stored records in order. Deletes reply with what they deleted. vault_create_folderandvault_rename_folderreply with the folder'spath.- Canvas writes (
vault_add_canvas_item,vault_remove_canvas_item,vault_draw_on_canvasandvault_edit_canvas_elements) reply with an outcome object. Adding and removing items list the itemsappliedandskipped; drawing and editing list the element ids created, updated and deleted. Read the canvas to see it whole.vault_create_canvasreplies like thecanvas.createdesktop write. - Tools that take no arguments (
vault_get_current_note,vault_get_tags,vault_list_projectsandvault_list_canvases) list an empty object schema withadditionalProperties: false. A call may send{}or omitarguments.
notes.resolveWikiTarget follows a wiki link the way the editor does: Meeting#Decisions resolves to the note Meeting and reports heading: "Decisions", while a note genuinely titled Sprint #4 still resolves to itself. notes.resolveByTitle stays a plain title lookup and returns nothing for a target carrying a heading, so use notes.resolveWikiTarget when the string came out of a [[…]].
Inbox items convert through the bridge into any of the four targets the app itself offers: inbox.convertToNote, inbox.convertToTask, inbox.convertToEvent, and inbox.convertToReminder. notes.applyTemplate applies a template the agent can already read through templates.get to an existing note.
settings.getFeaturesSettings reports which surfaces are turned on — home, inbox, journal, tasks, calendar, graph, and spatial canvas — so an agent can tell whether an action is even available before suggesting it, and settings.setFeaturesSettings toggles them. settings.getInboxSettings and settings.setInboxSettings cover the daily inbox review reminder.
Tag categories are reachable through the same bridge. tags.listCategories is a read operation that returns {"success": true, "categories": [...]}, where each entry carries its id, name, sort order, and tag count. tags.createCategory, tags.renameCategory, tags.deleteCategory, and tags.reorder are write operations behind the usual approval flow; tags.createCategory returns {"success": true, "category": {...}} and the other three return {"success": true}. Like the rest of the desktop bridge, these operations report their own failures as {"success": false, "error": "..."} rather than raising an MCP error, so check success before reading the payload. tags.reorder applies a drag result — tag-to-category assignments, category ordering, or both in one transaction — and is the only way to move a tag into a category. Deleting a category keeps its tags and makes them uncategorized.
vault_get_tags returns each tag with its color, icon, sort_order, category_id, and category_name. Both category fields are null for an uncategorized tag.
Calendar desktop reads accept the same single-object shape as the renderer bridge. For example: calendar.listEvents accepts args: [{}], and calendar.getRange accepts either args: ["2026-05-14", "2026-06-14"] or args: [{"startAt": "2026-05-14T00:00:00.000Z", "endAt": "2026-06-15T00:00:00.000Z"}].
Google-integration operations — calendar sources, provider status, Google calendar lists, promoting external events, and Google calendar settings — are excluded from the agent allowlists outright.
Events from external calendars are gated on explicit user consent, asked separately for each calendar service (Google, subscribed calendars, CalDAV). calendar.getRange builds the list of services whose events it may return (externalProviders) from the stored answers, never from the caller: an agent that passes includeExternal: true still gets native-only results unless the user allowed at least one service, and then only that service's events. Not asked yet, declined, or a settings read that failed all count as not allowed. See Calendar → AI Access Is Asked Per Calendar Service.
Google user data is never used to train or improve AI models, in line with the Google API Services User Data Policy (Limited Use).
Read tool calls are accepted automatically. The chat shows each one as compact, subdued text with a readable label such as Reading note or Reading tasks. Click the label to open or close the details area with the raw MCP tool name, parameters, and results.
Changes are different. Ask before changes is the default, so memrynote pauses the turn and shows inline approval controls inside the tool row. A row waiting on you opens itself and folds back once you answer, so a paused turn is never hidden behind a collapsed summary. You can approve the request once, grant it a standing approval, reject it, or edit it before approving. Write requests that present no active-turn capability — every external MCP client, and any call arriving after its turn ended — continue to be denied, whichever confirmation setting you choose.
A paused request always shows what it would change, in the shape that fits the item:
- Field changes for tasks, projects, statuses, inbox items, tags, moves and renames. Each changed column is one row: the value now, then the value the agent proposes. A value that is not set yet reads as such rather than as an empty string.
- A body diff for the text of a new note or inbox item. The changed words are highlighted in place and long runs of untouched lines are collapsed, so a one-word edit reads as a one-word edit. Edits to an existing note or journal entry are reviewed in the note itself instead; see Reviewing an edit in the note.
- What would be lost for deletes. A delete has no "after", so the card names the item and what goes with it instead.
Each preview reads the item as it stands right now, not as the agent last saw it, so the value in the "before" position is what the write is actually about to land on. Field rows list only the columns that move: an agent request often repeats every column it read, and those are left out.
A body diff also offers Edit before applying, which opens the proposed markdown in a text box. Applying from there replaces the whole body with what you see, so an append you edited is applied as the finished document rather than appended a second time. Field changes and deletes have no text box; use Edit and allow on the tool row to change raw arguments instead.
Reviewing an edit in the note
When the agent wants to change the body of an existing note or journal entry, the change is shown in that note, not in the chat. The note's text is drawn with the change in place: added words are highlighted, removed words are struck through, and each changed block has a bar at its start. A bar at the bottom of the note offers Accept, Edit and Reject.
- Accept applies the change as shown.
- Edit turns the suggestion into an editable copy. Add, change or delete anything, switch back with Show changes to see the result against the current note, then Accept edits. Your copy stays on this device until you accept it: nothing reaches the note, the vault file or your other devices before that.
- Reject refuses the change and puts the note back as it was.
While a change is under review the note's own editor is set aside, and it comes back exactly as you left it once you decide. If the note changes underneath the review, from sync or another window, the changes are recomputed against the new version. If you were already editing the suggestion, the bar tells you, and you can start over from the latest version or keep your copy.
The chat row points at the note while this happens. If the note is not open, the row offers Open note (or Open journal) to see the change, or Accept to apply it without looking.
Note and journal edits ask every time. They cannot be given a standing approval, and one granted before this change is ignored; Settings → Agent → Always allowed marks it as such, and Revoke still removes it. Only the global Always allow confirmation setting skips the review.
Always allow
Always allow on a paused request asks how long it should last:
- Always allow in this chat ends with the conversation. Nothing survives it.
- Always allow in this vault outlives the chat and is listed under Settings → Agent → Always allowed, where Revoke takes it back. The list is per vault and stays on this machine; it is never synced.
Deletes always ask. A standing approval is a promise about work you can still look at afterwards, and a delete is the one write where that is not true, so the gate refuses to trust a delete tool at either scope and the menu says so.
If you prefer the old behaviour, set tool confirmations to Always allow in Settings → Agent. That setting is per install and applies to every conversation.
If you had never touched this setting before upgrading, you now get asked where you previously did not. An explicit Always allow choice you made earlier is kept.
Stopping the turn while an approval is waiting counts as a denial: the pending request is refused, the tool never runs, and the approval controls disappear. Nothing is written to your vault.
An approval you never answer expires after 30 minutes. The controls disappear, the tool never runs, and the tool row is marked as expired rather than denied — the agent is told the request timed out, not that you refused it. Take as long as you need to read a request or its diff; half an hour is there so a prompt left open overnight does not keep the request waiting forever, not to hurry you. If a request expires and you still want it, ask the agent again. Local and OpenAI-compatible backends wait for the same 30 minutes: the tool call no longer fails after a minute while the approval is still on screen.
Project Links
vault_list_projects returns each project's icon, home_note_id, and linked_counts (notes, files, events) alongside task_count. Nonzero linked_counts are the signal that a project has a hub link layer worth reading; task_count alone says nothing about it.
The hub's link layer is reachable through the desktop bridge. Reads, via vault_desktop_read:
| Operation | Args | Answers |
|---|---|---|
tasks.listProjectContents | [projectId] | Which notes, files, and events a project holds |
tasks.listProjectLinks | [projectId] | The raw link rows, including pin state |
tasks.listForItem | [itemType, itemId] | Which projects a note, file, or event belongs to |
itemType is one of note, file, or calendar_event.
Writes, via vault_desktop_write, behind the same approval flow as other writes:
| Operation | Args |
|---|---|
tasks.linkProjectItem | [{ projectId, itemType, itemId }] |
tasks.unlinkProjectItem | [{ projectId, itemType, itemId }] |
tasks.setProjectLinkPinned | [{ projectId, itemId, pinned }] |
tasks.setProjectHomeNote | [{ projectId, noteId }] |
tasks.captureUrlToProject | [{ projectId, url }] |
tasks.importFilesToProject | [{ projectId, sourcePaths }] |
setProjectHomeNote takes noteId: null to clear the project's home note, the same way the hub's own overview rail does.
captureUrlToProject fetches the page title over the network, and importFilesToProject copies files from paths you supply into the vault — both on caller-supplied input, like the already available inbox.captureLink and notes.importFiles. Operations that open native UI or hand an item to the OS stay out of the allowlist.
importFilesToProject waits for the indexer to assign an id to each imported file, so importing several large files at once can exceed the bridge's ten-second window. The import still completes; the tool call reports a timeout. Import in smaller batches to see the result.
Current Note
vault_get_current_note can snapshot the active note when the request is associated with a memrynote window. Plain external clients do not have that window context, so the tool returns null instead of guessing.
Privacy
The MCP server binds only to localhost. Read tools still expose the content they return to the client you configure, so only paste the token into clients you trust on this machine. Write tools still require an active Agent Chat conversation context, and by default that conversation pauses and shows you the change before it is written. The in-app tool confirmation setting is what decides that; setting it to Always allow accepts the call without a preview.
Provider privacy depends on the selected backend:
- Claude and Codex providers may send prompts, attachments, and tool results through that provider.
- Local loopback providers keep model prompts on this machine, except for the actual tool effects memrynote applies inside the vault after approval.
- Custom non-loopback endpoints send data to the configured endpoint and must be explicitly enabled with the not-fully-local warning.