Meru is a personal AI assistant that runs on a machine you control, with every model on the same machine as your data. This page describes how it works and why: two programs, three model jobs, one store, one guarded path to outside tools, and the traces that show where each second went.
This is the level-300 page, the full design down to config keys and table columns; if you are new to Meru, start with level 100. ARCHITECTURE.md is the source of truth. We generate this page from it; where the two disagree, the markdown wins and this page has a bug.
meru client to start and connectmeru "hello", the v0.1 targetEngine interfaceDesign targets and model sizes from ARCHITECTURE.md and ROADMAP.md, September 2026. The strip shows targets; measurements from v0.1 and v0.2 appear in the sections they belong to.
Meru runs on a machine you pick: your Mac, a Linux box or a cloud server. It answers questions, searches your notes and calls the tools you already use.
An assistant that reads your notes, your mail and your calendar could leak all three. A cloud model, one that runs on another company's servers, would receive every prompt you type. Meru has no code that talks to one. It runs open-weight models, whose weights anyone can download, through Ollama, a program that serves models locally, and it connects only to loopback, the 127.0.0.1 address that never leaves the machine.
Six principles shape every choice below:
web_fetch, which you turn off by taking it out of [builtin] tools. A page URL that no search result or question of yours gave asks you first, so the model can't send your data out in a URL. Meru measures itself, and the one thing it sends about itself is an anonymous daily count that you choose (see The anonymous usage report). No prompt goes to the internet: the fast and embedding models always run here, an answer model runs here or on a computer on your own network, and a turn goes to one on your network only after you answer "this time" or "this chat" (see Answer endpoints). Other programs Meru talks to on loopback can reach the network on their own: an MCP server you add, such as Gmail, and SearXNG, which web search sends its search words through (see Tools over MCP and Web search).meru.db and it re-indexes. The one exception is the tool log of an incognito or deleted chat, which has no file behind it on purpose (see Organizing past chats and Incognito chats).A command-line tool that starts, loads a model, answers and exits would be too slow. The full profile's main model is 38 GB at 8-bit, meaning each weight stored in eight bits, and it takes many seconds to read from disk. Paying that on every question breaks principle 5, so Meru splits into two programs:
merud is a daemon, a program that keeps running in the background. It keeps models loaded in Ollama, owns the store, holds the MCP and A2A connections, runs the connectors, the indexer and the agent loop, and emits metrics and traces. From v0.5 the scheduler runs jobs through it.meru is a thin client. It connects to merud over a Unix socket, a file path two local processes talk through, at ~/.meru/merud.sock. It starts in about 50 ms, streams the answer back and exits. It holds no model or store code.The desktop app is a second thin client. One more program, the Mac installer, runs once, before merud exists, to set the Mac up (see The Mac installer).
A daemon that keeps models loaded can also run scheduled jobs at little extra cost, so merud comes first and the scheduler joins it later.
merud for programs it doesn't own from two places: the engine, to Ollama, and dispatch, to MCP servers, A2A agents and SearXNG. Each is one guarded entry point, which is where the privacy rules live. The scheduler, new in v0.5, runs jobs through the same loop.meru chat uses Bubble Tea, a Go library for interactive terminal apps. A Bubble Tea program has three parts: a model struct that holds the screen's state, an Update function that turns each event (a key press, a window resize, a streamed token, one of the word pieces a model reads and writes) into a new state, and a View function that draws the state as text. The client reads tokens from the socket in a goroutine, a function Go runs alongside the rest of the program, and passes each one to the program with program.Send, so the answer grows on screen as it arrives.
meru chat also uses Bubbles, from the same authors, for the text input and the scrolling answer pane, and two more Charm libraries for its look:
v0.4.3, or dev and the commit for a build between tags, from internal/about, as the desktop app's rail shows it), the profile, model, what the index holds (2637 docs (11698 vectors, 84 MB), with · indexing while a scan runs), the session, the last hour's use (1h: 4 tasks · 18k in · 2.1k out) and whether merud is reachable; "You" and "Meru" labels; a route badge on each answer, amber when the router fell back; and a stats line with time to first token, tokens per second and total time. Colors adapt to light and dark terminals, and NO_COLOR turns them off. The chat asks merud for the header's numbers every 5 seconds while a scan runs and every 30 seconds otherwise. Typing /usage opens a table of sessions, tasks, tokens in and out, active time, docs touched and tool calls for the last hour, today, this week, this month, the last 30 days and all time; meru usage prints the same table. /usage by model shows one row per answer model (see Model sets). Under the table, /usage draws tasks and tokens in per day as bar lines, today's tokens and time to first token, the five slowest tasks of the week, the tools whose calls failed, and where Prometheus can read the metrics (see Reading the metrics). Typing /model opens a table of the model sets, /model <name> switches to one and /model save makes it the default; the header names the set in use beside the usage, and ends with Meru's website, aarora79.github.io/meru, as a link a click opens; it is the first thing to go when the terminal is narrow. Typing /new starts a new session, so a conversation that went wrong stops shaping the answers after it. In both clients, each source line is a link (OSC 8) to its file:// path, which terminals that support links open on a click.A finished answer puts a dim ⧉ copy N label under each code block. The numbers run on through the session, so /copy N names one block on the whole screen, and /copy or Ctrl-Y copies the newest answer's last block. The chat finds the blocks in the answer's Markdown, not in what Glamour drew, and hands the text to the system's clipboard program (pbcopy, wl-copy, xclip, xsel or clip.exe). With none installed, it sends OSC 52, an escape code that asks the terminal to set its clipboard. A click on a label copies too. That needs the chat to capture the mouse, which takes plain click-and-drag selection away from the terminal, so selecting text needs Option (iTerm2) or Shift (most others); [chat] mouse_copy = false gives plain selection back.
A web or file link in a finished answer shows as its URL without the scheme, cut with … to fit its line, and a click opens the full URL in terminals that support OSC 8 links. A Markdown link keeps its text, with the URL after it, so you see where a click goes before you click. Glamour alone breaks a long URL at its dots and dashes, and the terminal's own URL detection then finds only half of it. With NO_COLOR nothing on screen can open a link, so the chat shows the full URL as plain text: whole where it fits, and in line-wide pieces where it doesn't. Only http, https and file links change; a URL in code stays as the model wrote it.
With [chat] mouse_copy on, the default, the terminal never sees a click, so the chat opens links itself. It finds the OSC 8 link under the pointer, in an answer or in the Sources list, and hands the URL to open on macOS, xdg-open on Linux or rundll32 on Windows. It starts that program with no shell and the URL as one argument. It opens only http, https and file URLs, refuses one that starts with -, which the program would read as an option, and says on the bottom line what it opened. With mouse_copy = false the terminal gets the click, and its own link click, often Cmd-click, opens the link.
While a turn runs, Enter puts the next question in a queue, drawn under the running turn with a dim queued mark. When the turn ends, the chat sends the oldest queued question in the same session, so merud still gets one turn at a time; the queue lives in the client. It holds five questions at most, because each one costs a whole turn and a longer line of them is more often a slip than a plan. Ctrl-C stops the running turn and drops the queue: a user who stops an answer wants the screen back. /new drops it too, since those questions belonged to the old conversation. Commands that only open a box or copy text run at once. A model switch waits for the running turn to end, since merud would unload the model that writes its answer.
The same features as the desktop app. The chat does what the app does wherever a terminal can, with the ops the app already sends; it adds no op of its own. The commands, in the order /help lists them:
| Command | What it does | Op |
|---|---|---|
/new | start a new session | — |
/incognito | start an incognito chat, which merud keeps in memory only (see Incognito chats); meru chat --incognito opens with one | ask with incognito |
/chats [words] | a box of past chats, each with its folder and tags, filtered by the words, which match a title, a folder or a tag; Enter reopens one, and the next question continues it; d twice deletes the marked one | sessions, session_turns, session_delete |
/delete | delete the open chat for good; the first /delete says what it will do, and a second one right after it deletes | session_delete |
/folder [new <name>|rename <old> -> <new>|delete <name>] | list, make, rename or delete chat folders | chat_folders, chat_folder_add, chat_folder_rename, chat_folder_remove |
/move [folder] | put the open chat in a folder, or, alone, take it out of its folder | session_move |
/tag <tags>, /untag <tags> | add tags to the open chat, or take them off | session_tag |
/retry | ask the newest question again, with its scope and images (the app's Try again) | ask |
/scope [auto|files|mail|web|talk] | set where the next questions look, as the app's switch does; the header names a scope other than auto | ask with scope |
/attach [path] | attach a file or an image to the next question; /attach alone takes them all off | attach_file |
/save [chat] | save the newest answer as a note, or the whole chat as a file | save_file |
/used | what the newest answer used: every source, each tool call, the memories recall brought, and who the calls reached | memory_forget |
/copy [N|answer] | copy code block N, the newest answer's last block, or the whole answer | — |
/usage [by model] | the usage box | usage |
/report | the anonymous daily usage report: what goes, the next one, on or off, and t to send today's now | usage_report |
/me [add|prefer <text>] | the profile memories; add saves one to me and prefer one to preferences | memory_list, memory_add, memory_forget |
/mcp | every connector, where f fixes one, o turns it on or off and a adopts one set up by hand; every tool source with each tool's Off, Ask or Allow; and the catalog servers not added yet | connectors, connector_set, connector_fix, connector_adopt, connections, tool_policy, mcp_add, mcp_remove, secret_set |
/folders [add <path>] | the [index] folders and the usual ones not indexed yet | folders, folder_add, folder_remove |
/skills | every skill, on or off | skills, skill_enable, skill_disable |
/model [name|save] | the model sets, a switch, and a save | models, model_use, model_save |
/log | the latest tool calls, the app's Activity | log |
/about | the tagline, the version, the license, Meru's folder and the project's links | — |
/help | every key and command | — |
/exit | quit | — |
Each box opens over the conversation and keeps the keys until Esc or q closes it. In a box with rows, ↑ and ↓ move a marker and the box scrolls to keep it in view. The keys that change something are the same everywhere: ← and → step a tool's policy through Off, Ask and Allow, with Always ask between Ask and Allow for an MCP tool (configure and schedule_job step between Off and Always ask), Enter adds or toggles the marked row, and d removes a folder or an MCP server, forgets a memory or deletes a chat, after a second d, since none of those can be undone from the chat. Adding a catalog server that needs an API key opens a field that shows • for each character; Enter sends the key to merud with secret_set, then mcp_add adds the server. The key never comes back.
/attach takes a path the user types, with ~ for the home folder. The app takes only a real pick or drop, since its page could otherwise choose a path; in the terminal the user types the path, so typing it is the consent. merud applies the same rules to the file either way, and the chat applies the app's: five files at most, one "Read this file" line per file, the images in the request's images, and a scope other than auto or files switches to files when a file comes in. The attachments show on one line above the input box.
A save asks first, as write_file does. The approval box opens where the conversation was, since the save belongs to no turn, and a save waits while a turn runs, so one approval box shows at a time. The approval box for a turn also offers e, Edit first: it answers deny and puts the call in the input as a draft, "Run mail.send with these arguments instead:" and the arguments, for the user to change and send as a new question, as the app does.
The chat leaves out what needs a window: drag and drop, the file and folder dialogs, the SVG preview, image previews, and custom MCP servers, which take a form of their own. meru mcp add stdio and meru mcp add http add those in the terminal.
The stats come from the done event that ends each reply, which carries the turn's timings and token counts.
Answers always stream: meru chat and one-shot meru both show text as the model writes it. When merud warns that an answer claims an action no tool took, meru chat shows the warning in amber under the answer and one-shot meru prints it on stderr as a note: line (see Claims no tool backs). Each tool call shows as a dim line inside the answer, → notes.search while it runs and ✓ or ✗ with its time or outcome when it ends. When a tool call needs your approval, meru chat opens a box under that line with the tool's name and arguments and three choices: approve once, approve for this session, or deny. The box opens with deny selected, so a stray Enter runs nothing (see Approving a tool call).
The UI code holds no model or store logic; it draws what merud sends. One-shot meru "..." doesn't use Bubble Tea at all. It prints the stream as plain text, which also keeps it usable in scripts and pipes.
meru-desktop is a third client: a native window for people who don't live in a terminal. It is as thin as meru chat. It talks to merud over the same socket with the same protocol, holds no model, store or tool logic, and never runs a tool itself; merud runs every call through dispatch, and the app only answers its approval questions.
Wails v3 draws the window. Wails pairs a Go program with the system's own WebView (WebKit on macOS, WebKitGTK on Linux, WebView2 on Windows), so the app is one native binary with no browser engine inside it, and the page is plain HTML, CSS and JavaScript. We pin a v3 beta: v3 has no final release yet, and its beta notes call the API stable. Wails needs cgo and the platform's WebView headers, so the app sits apart from the cgo-free build:
cmd/meru-desktop holds only the window code, behind the build tag desktop. Without the tag the go command skips it, so go build ./..., the five-platform make build and CI's cross-compiles never touch cgo. make desktop builds it on the machine that runs it, with the tags desktop production; production turns off Wails' web inspector and its probe for a development server.internal/desktop holds everything else: the Bridge the page calls, the views it sends, and the page itself, embedded with go:embed. It doesn't import Wails, so its tests run everywhere.The Bridge. The window binds one Go value, the Bridge, whose methods the page calls by name. Send opens an ask request with source desktop and the scope the composer's switch sets, and a goroutine reads the events and hands each one to the page as an Update, through one Wails event, meru:update. The Bridge keeps the running turn and the queue, with the chat's rules: one turn at a time, five questions waiting at most, and Stop drops the queue with a notice. For each tool call it adds a friendly label ("Searched mail", "Read lisbon.md"), and when a turn ends it lists who the turn's tool calls reached: each MCP server and A2A agent by name, "web search" for web_search and the site for web_fetch. The other methods each send one request for the Settings and Setup screens, save a chat or an answer, show the system's file and folder dialogs, and close the app.
One line says what Meru is: "A personal AI assistant that runs on your own computer". The title bar shows "Meru · " and that line, and never changes; the chat's own title sits in the page's header. The rail's logo carries the line as its tooltip.
The chat screen has three columns:
merud doesn't answer, that it isn't running and the command that starts it. A button folds the rail to a column of icons: the logo, a button that unfolds the rail, New chat, chats, Usage, Settings and a status dot.tool_call, "Searched your files" after a sources event, both together, or "Answered from the model" when neither came. A turn on the tools route whose model called no tool once said "Used tools" under a made-up answer; "Show steps" opens the raw tool names, outcomes and times, and an amber "Waiting for you" chip marks an open approval. The answer streams as plain text and renders as Markdown when it ends, as in meru chat; each code block gets its number in the chat and a Copy button, and each answer Copy, Save to a note, Try again (the same question, in the same session and scope, with the same images and none of the files waiting in the composer) and a dim stats line. Under the answer, one closed line, "3 sources", opens to a chip for each source the answer cites, and a chip opens its file. The Bridge picks those sources with rpc.Cited, as meru and meru chat do; an answer that cites none shows no line. When merud sends a notice, because the answer claims an action no tool performed, an amber note with a warning icon sits under the answer, and again when the chat reopens from history. A new chat shows the logo beside "Ask Meru". The composer sends on Enter and adds a line on Shift+Enter; while a turn runs, Enter queues, and the queue shows above the composer with a remove button on each question. Under the text box sit the Where Meru looks switch and the attach button, and a microphone button that turns speech into text in the box (see Speech to text).memory_forget. It ends with a privacy line: "The model ran on this Mac. Only google was contacted." While an approval card is open, the panel turns into Why Meru is asking: why this call waits, the server's tools that are on with their policies, a link, "Change what google may do", that opens Settings at that connection, and a note that every call goes in the tool log under Settings, Activity. The panel doesn't open for a card: the card says why Meru asks, with a link to the panel. In Settings the panel is On this Mac: the answer and router models, what the search index holds, and a line that says there is no account and no cloud, with the path of config.toml. Below 1180 pixels the panel slides over the conversation on demand.Where Meru looks. The composer's switch sets the request's scope: Auto, My files, Mail and calendar, Web or Just talk. A new chat starts on Auto, in the app and after /new in meru chat. Auto runs the router as every other client does, except for a question with images, which takes the direct route because the router's model reads text alone. That turn still offers the tools the search route offers, so the model can read a file the picture is about, such as a PDF the chat already found. Any other scope skips the router, the route rules that widen a route and a picked skill's tools, because a scope is a promise about what the turn may touch. dispatch keeps the promise: on a scoped turn, a call to a tool the round didn't offer is denied and logged, even when config allows that tool, so a model that names web_search from memory on a My files turn searches nothing:
| Scope | Route | Searches first | Tools offered |
|---|---|---|---|
files | search | yes | what the search route offers but the web tools: the file tools, datetime, about_meru, commands that don't ask |
mail | tools | no | every tool of each mail and calendar server, with datetime and about_meru |
web | tools | no | web_search, web_fetch, datetime and about_meru |
talk | direct | no | none |
A mail and calendar server is an MCP server or A2A agent whose tool names hold a noun that ends in "mail" (gmail, email), or "calendar" or "event": the nouns the router's prompt already reads (see Routing). So Meru needs no list of mail providers, and the google server brings Drive and Docs along with Gmail, while obsidian stays out. Deny-by-default still holds: a scope only narrows what config allows. In Auto every route offers web_search and web_fetch while web_search is on (see A question, end to end); of the other scopes only Web does, since My files, Mail and calendar and Just talk each promise where the turn looks. merud logs the scope in the turn's info line and on its span; the value is one of five.
Attaching files. The attach button opens the system's file dialog, which sets no starting folder and takes one or more files from anywhere. Dropping files on the chat screen does the same; while they hover, a "Drop to attach" overlay covers the screen. Picking or dropping a file is the user's consent to share that one file with Meru. The app writes nothing: the Bridge sends each path to merud in an attach_file request, and merud copies the file into <output_dir>/uploads/ under its own name made safe, adding "-2", "-3" when the name is taken. The file tools already read the output folder, so they read the copy under their usual rules and reach nothing new.
merud refuses a folder, a symbolic link, anything but a regular file, a file over 50 MiB (the cap web_fetch puts on a download), a name the indexer treats as a secret (.env, *.pem, id_ed25519 and the rest; see Getting your content in), and a copy read_file couldn't read, such as an archive, which it deletes. A user who drops a folder of files may not know a key file sits among them, so the notice under the text box names each file that stayed out, and why. merud also refuses while read_file is off, since the model couldn't open the copy. A question takes five files at most: each one costs a read_file call, and a small model loses track of more. Each file shows as a chip above the text box with its name, its size and a remove button. Send adds one line per file, "Read this file: ~/meru-output/uploads/garden-plan.pdf", and a scope other than Auto or My files switches to My files, the scope that offers read_file.
Attaching images. An image takes the same button, the same drop and the same attach_file request, and lands in the same uploads folder, but the model looks at it rather than reading it with read_file. merud treats a file as an image when its name ends in .png, .jpg, .jpeg, .gif or .webp and its first bytes, read with Go's http.DetectContentType, are a PNG, JPEG, GIF or WebP file's; a text file renamed garden-bed.png fails the second test and stays out. The secret-name, symbolic-link and regular-file rules still apply. The cap is 20 MiB, which covers a phone photo of 2 to 12 MB with room to spare and keeps a question of five images to about 133 MB of base64 on its way to Ollama. An image skips read_file's test for readable text and needs no read_file at all. attach_file answers with the copy's kind, image or file.
The chip shows a small preview in place of the file icon. The Bridge builds it in Go from the copy, and only from a file inside the uploads folder: an image up to 64 KiB goes to the page as it stands, and the Bridge shrinks a larger PNG, JPEG or GIF to 160 pixels on its longest side and sends it as a JPEG, both as data: URLs, which the page's policy allows for images. A large WebP gets an image icon, since Go's standard library has no WebP decoder and a preview doesn't justify a new module. Send puts the images in the ask request's images field, by the copies' full paths, and adds no "Read this file" line for them; the question's bubble shows the previews above its text. An image switches no scope: it goes with the question in each one. Images and files share the cap of five per question.
merud trusts none of the paths an ask request names. It takes five at most, and each must be a full path right inside <output_dir>/uploads/, a regular file and no symbolic link, opened through an os.Root on that folder, under the cap, with an image's first bytes. It refuses anything else with a message the user reads, before the turn starts. Agent loop says what the turn does with them.
[index] folder could be read where it is, but one rule for every file is simpler, and the question's line keeps working after the user moves or deletes the original.uploads, not attachments. The google server deletes every file in its attachments folder an hour after it was written, and a chat can go on longer.desktop.Drop, a plain function rather than a Bridge method, so the page can't call it with a path of its own choosing.dispatch. The read_file call that reads it goes through dispatch and lands in tool_calls as any other.merud reads the bytes itself, so an image never passes through the socket, and the transcript can name what the question carried.Slash commands. The composer understands the commands meru chat has, each mapped to the app's own screen: /new (as New chat: it stops a running turn and drops the queue, with the chat's notice), /incognito (Incognito chat), /chats (the rail, with the search box focused and filled with any words after the command), /delete (the Delete dialog for the open chat), /folder, /move, /tag and /untag (the same ops as in the chat; the notice line says how each went), /retry (Try again on the newest answer), /scope <name> (the Where Meru looks switch), /attach (the file dialog), /save (Save to a note on the newest answer; /save chat is Share as file), /used (the side panel for the newest answer), /copy N (code block N of this chat, numbered as the chat numbers them; /copy alone the newest answer's last block, and /copy answer the whole answer), /usage (the Usage screen), /me (Settings, About you), /mcp (Settings, Connections), /folders (Settings, Folders), /skills (Settings, Skills), /model (Settings, Models; /model <name> and /model save switch and save as in the chat), /log (Settings, Activity), /about (Settings, About), /help (the command menu) and /exit (close the app, asking first while a turn runs). Typing "/" at the start of the box opens a menu of them, a listbox the arrow keys move through, filtered as you type; Enter or Tab picks one and Esc closes it. A line that starts with "/" runs in the page and never reaches the model; an unknown one leaves the text in the box and lists the commands, as the chat does. The Bridge holds the list, and a test fails when it differs from meru chat's.
Settings has a back link and seven sections:
merud's sentence, an on and off switch, the form, Save and Fix (see Setting up a connector). Below them it has a card per tool source: the built-in web tools, merud's other built-in tools, each MCP server and A2A agent, and the local commands. Each card shows whether the source is connected, the last error when it isn't, "N of M tools on", and a switch per tool whose positions map onto config: Off, the tool isn't in allow; Ask, it is in allow and in confirm; Always ask, for an MCP tool only, it is in allow and in its server's always_confirm, so it asks before every call with no approval for the chat; Allow, it is in allow and in neither list. A tool sits in at most one of confirm and always_confirm. A built-in or an agent's skill has no always_confirm, so its switch has three positions. configure and schedule_job show Always ask and have no Allow: they change config, so the model could grant itself a tool or start a job. Under each MCP tool's name the card shows the server's hint, from its MCP annotations: "read-only", "may delete" or "changes things"; a hint is the server's claim. The local commands show their policy without a switch: each is a [[commands]] entry you edit in config.toml. Add a connection lists the catalog servers not added yet, with what each needs, its start command, and the tools it turns on; an API key goes into a password field. Under them, Add your own MCP server opens a form for a server outside the catalog, with the rules of meru mcp add stdio and meru mcp add http: a name of letters, digits, - and _; either a program with its arguments, one field for each, and environment variables, or a URL. A URL off this machine needs the tick "This server is on another computer", which writes remote = true. A variable ticked Secret goes to secrets.toml and config.toml holds secret:<name>. The server's tools all start Off; once it connects, its card lists them.[index] folders with how many files the index holds from each, a button that opens the folder dialog, the usual folders not indexed yet, and the skip rules.me and preferences, with Edit (a forget and an add) and Forget, and a form to add one, as meru setup user does.[skills] disabled.ollama pull and ollama run commands, each with a Copy button. Use for answers switches the answer model with no restart and saves it; it stays off until Ollama has the model, and a model without tools carries a warning. Above those cards, Model sets shows a card per model set, with what its main model can do when Ollama or the list of models we tried says; Use switches to the set until merud stops, and Make default saves the set in use. The router, the embedding model and the profile change in config.toml, then a restart.tool_calls log, the data meru log prints: time, tool, outcome and duration, with the arguments and result behind a button.config.toml and Meru's folder are, and four links: the source code, the design, a feature request and the license. The Bridge hands the page the links, so the page's own files name no host, and each opens in the browser through OpenURL. Under those paths, "Run setup again" opens Setup.Usage has a button of its own beside Settings at the foot of the rail, and opens a screen with two tabs. Charts, open first, shows four bar charts over 30 days, two to a row: tasks per day, time to first token per day (p50 and p95), tokens in and tokens out per day, each with a labelled y axis. A task is one question or request that Meru answered. Under the charts come Totals, the usage windows the chat's /usage box shows, then the ten slowest tasks of the week, each a link to its chat, tool calls by outcome, and use by answer model. Until the charts arrive, and with an older merud that can't send them, the windows table shows alone. Prometheus queries says how to read the same metrics in a Prometheus you run, with the /metrics address or the line that turns it on, and queries to copy (see Reading the metrics). Everything on the screen comes from meru.db.
Setup has four steps, and opens on its own when merud reports no folders and no profile memory; after that, "Run setup again" in Settings, About opens it. The models lists the three models; with merud down it shows the ollama pull each one needs and the command that starts merud. Meru pulls nothing on its own: a model is gigabytes, and merud answers no question until Ollama has the models it names. Your folders offers checkboxes for ~/Documents, ~/Notes and ~/Desktop where they exist, each with a file count from merud, and "Choose another folder". Connections shows the catalog cards. About you asks your name, your email and how you like answers, and saves each as a memory, as meru setup user does.
**Settings change in merud.** The app writes no file of Meru's. Each change goes to merud as an op, and merud checks it, writes it with the same code meru mcp add and configure use, and applies it at once:
| Op | What merud does |
|---|---|
connections | lists every source with each tool's policy, and the catalog |
tool_policy | sets one tool's allow, confirm or [builtin] lists, then reloads that kind of source |
secret_set | saves one key to secrets.toml, for a name config or the catalog uses, then reloads the MCP servers |
mcp_add | appends a catalog server's block, once its key is saved, or a server of the user's own with no tools allowed and its secrets saved first, then reloads the MCP servers |
mcp_remove | takes a server's block out, then reloads |
folders | lists the [index] folders with file counts, and the usual folders not indexed yet |
folder_add, folder_remove | edits [index] folders, hands the indexer the new list, restarts the watcher and scans |
skill_enable, skill_disable | edits [skills] disabled and loads the skills again |
save_file | saves the chat or an answer as Markdown through write_file |
models | names the models, asks Ollama which it holds, and lists the models we tried with whether Ollama has each, and the model sets |
model_use | switches to a model set until merud stops, unloading the old answer model first (see Model sets) |
model_save | writes the models in use to [models] |
model_set | switches to a model on that list that Ollama has, the same way, then writes [models] main |
jobs, job_set, job_remove, job_run, job_cancel | (v0.5) list, add or change, remove, run now and stop scheduled jobs (see Scheduled jobs) |
usage_report | reads the anonymous daily usage report's state, marks its notice seen or closed, writes [usage_report] send, and sends today's report now on request (see The anonymous usage report) |
A change to a list edits only that list's lines in config.toml: every comment and every other key stays. merud writes a temporary file, loads it, checks that the list came out as asked, and renames it over the old one, so a change that would break config leaves the file as it was. One lock covers every write to config.toml in merud, the configure tool's included. A tool policy checks the tool against what the source offers or config already names, and refuses anything else; a new tool a server starts to offer shows Off. The key a user pastes goes to merud over the socket, which only that user can open, and never comes back in any reply.
An answer model change takes effect without a restart too; see Models we tried.
A folder change takes effect without a restart. The indexer takes the new list, the watcher starts again over it, and a scan adds the new folder's files or drops the removed folder's. The file tools, the prompt's note on the user's folders and the router's prompt read the list on every turn, so the first folder added turns the file tools on. A folder op refuses the whole disk, the home folder itself, Meru's own home, and a folder inside or around one already indexed.
Saving a file. Share as file saves the whole chat, and Save to a note one answer, as Markdown under [skills] output_dir, in chats/ or notes/, named by the date and the first words of the title. merud makes the file with one write_file call through dispatch, in the chat's session, so the save lands in tool_calls and the transcript, and asks first as write_file does. The card shows above the composer; after a yes, the notice names the file and offers "Show in folder", which opens the folder in the file manager. A name already taken gets -2, since write_file never replaces a file.
Approvals sit in the answer. An approval event becomes a card inside the answer, amber like everything that asks. It shows the tool and its arguments, with to, cc, bcc, subject and body laid out as a mail when the arguments hold to or subject, and the rest as indented JSON. Focus lands on the answer that runs nothing, so a stray Enter runs nothing. The answer goes back on the socket as a Reply, as in meru chat. The Bridge gives each card an ID of its own, since merud numbers approvals per connection and a save runs on a connection of its own.
Edit first. The approval card has Send, Edit first and Don't send (Allow once and Don't allow for a call that isn't mail, and Allow for this chat when merud offers it). Edit first answers Don't send, then puts the call as a draft in the composer: "Send this mail instead:" with its To, Subject and Body, for the user to change and send as a new question. The model makes the call again with the new text, and merud asks again. We chose this over approving with edited arguments: dispatch would then run a call the model never made, and the audit line, the approval and the call would need to agree on which arguments ran. The second card shows exactly what will run, so nothing runs that the user didn't see.
Past chats come from the transcripts. Two ops serve the rail: sessions lists the sessions that hold a question, newest change first, with the first question as the title and the folder and tags from the newest meta line; session_turns returns one session's turns, each with its question, answer, route, sources, tool calls, time and token count. merud reads both from the JSONL files, never from meru.db, so they stay right after the database is deleted. Opening a past chat and asking again sends its session ID, so the conversation continues. chat_folders lists the chat folders, so the rail can show a folder that holds no chat yet.
Model output is untrusted. A bad answer, or a page the model fetched, could hold HTML meant to run in the window. Three layers stop it:
marked renders the Markdown with raw HTML escaped, and DOMPurify keeps a short list of tags, no data-* or style attributes, no class but a code block's language, and only http, https and file links. It returns DOM nodes; no code puts a string into innerHTML. Everything else reaches the page as textContent. A code block that holds an SVG drawing also shows as a picture, with a Preview / Code switch: the page draws it as an <img> with a data: URL, where the browser runs no script and fetches nothing, so a drawing can only draw.default-src 'none', and scripts, styles, fonts and connections from the app only. No inline script runs, and no image or font loads from the network, so an answer can't report that it was read.OpenURL, which hands only an http, https or file URL to the system opener, with no shell and the URL as one argument, the same code (internal/opener) that meru chat uses.Everything ships inside. The page loads nothing from the network: the fonts (Newsreader, IBM Plex Sans and IBM Plex Mono, under the SIL Open Font License) and the two libraries (marked and DOMPurify) sit in internal/desktop/web/ with their licenses. There is no Node, npm or bundler: the page is ES modules the WebView loads as they are, and the Bridge's methods are called by name through Wails' runtime, so no generated bindings are needed.
Not yet. An "Earlier" line for turns scrolled out of view, pulling a model from the app, and Linux and Windows builds come in later versions.
Meru is a Go program. meru and merud build as native binaries that you can copy to another machine and run, with no interpreter or virtualenv.
We chose Go over Python, the usual language for AI tools, for these reasons:
merud never stops running, so its idle memory matters, and the meru client starts in milliseconds instead of waiting on Python imports.merud, all sharing one Ollama on the same GPU server. At that point the overhead of each daemon multiplies, and a lean compiled daemon lets one server hold many more people than an interpreted one would. The models dominate the cost on a single laptop; across a rack of servers, Meru's own overhead adds up.context cancellation handle that directly, without Python's global interpreter lock.The trade-off: Python has the stronger libraries for machine learning and PDF parsing. That is one reason models run in Ollama rather than inside Meru. Meru reads PDFs with ledongthuc/pdf, a pure-Go library that reads each page's text and keeps no layout (see Open questions).
These things stay outside the binaries:
merud downloads on first need into ~/.meru/runtime: Node, uv and chrome-headless-shell, at pinned versions, and the SearXNG container it can run (see Connectors and the supervisor).The store uses ncruces/go-sqlite3, a Go library that runs SQLite compiled to WebAssembly, with FTS5 and vec1, SQLite's own vector extension, built in. It needs no cgo, Go's bridge to C code, so a plain go build works without a C compiler, and one command builds for another platform: GOOS=linux GOARCH=amd64 go build ./....
Every part Meru depends on runs on the three major desktop and server systems: Ollama, SQLite, Go's Unix sockets (Windows 10 and later has them too) and the OpenTelemetry stack.
| Platform | Status | Restarts merud after a reboot |
|---|---|---|
| macOS, Apple silicon | Supported and tested. The development machine is a Mac Studio (M4 Max, 64 GB). | launchd |
| Linux, x86-64 or arm64 | Supported, including home servers and cloud virtual machines. | systemd |
| Windows 10 and later | Should work; not tested at first. | none yet; a Windows service is planned |
On a cloud server, Meru still sends no prompt to a model provider or anywhere outside that server's private network, but your notes, email and transcripts live on that server. Meru's promise is "a machine you control"; where that machine sits is your call. You'd run meru over SSH, because it reaches merud through a local socket.
merud as an agent harnessdocs/architecture/harness.md follows one turn through the harness in full, step by step, with the numbers the code uses.
An agent harness is the code that runs a model in a loop: it builds the prompt, runs the tools the model asks for, hands back the results and keeps a record. merud holds a whole one: a model loop with tool rounds, one gate for every tool call, an MCP client, skills with progressive disclosure, local commands and A2A agents as tools, a session record, a context budget and tracing. meru, meru chat and meru-desktop are clients of that harness. Meru the assistant sits on top of it and decides where to look, what to remember and how to catch a small model's mistakes.
| Layer | Packages and files |
|---|---|
| Harness core | engine; the tool rounds in agent/tools.go; dispatch; mcp; skills, with the skill pick in agent/skills.go; commands; a2a; transcript; the budget in agent/budget.go; obs |
| Meru the assistant | router, with the route rules in agent/toolnouns.go; retrieve; memory and the profile (agent/profile.go, agent/recall.go); recall of earlier chats (agent/earlier.go, summarize); web first (agent/webfirst.go, agent/webnotes.go); the fixes for small-model failures: agent/honest.go, the amounts check in agent/amounts.go, the retries after bad output and empty replies in agent/tools.go and agent/agent.go, and agent/notools.go |
Four places tie the loop to Meru today:
agent.New takes the whole config.Config. It reads the assistant's settings, such as cfg.Index.Folders, next to the loop's own cfg.Agent.MaxRounds.Agent.Handle takes an rpc.Request and emits rpc.Event, the socket protocol's types, so the loop speaks Meru's wire format.agent, and run inside one Handle call: routing, search, recall and web first share the function that runs the tool rounds.dispatch asks for approval through rpc.ApproveFunc and writes each call to the store's tool_calls table as a store.ToolCall.A script can drive the harness with no one at the keyboard. meru -image shot.png "find images like this" sends a picture with one question, through the same attach_file step and rules as the desktop app's attach button; -image works with run --json too. meru run --json "question" writes each socket event as one JSON line on stdout and exits non-zero when the turn fails. The command denies a tool call that asks first, as any client with no one to ask does, and dispatch logs it as declined. The command also writes the approval event to stdout, so the script sees which call it refused. A tool doing slow work sends progress events between its tool_call and tool_result, with the call's ID, such as the line web_fetch sends while it installs its page reader. The done event's outcome says when an answer stopped short, such as cut_off, so a script can tell a whole answer from part of one, and its model names the model that wrote it. An escalate event says the fast model's answer ended early and the main model answers again; a script drops the text it had. A sign_in_needed event names, in servers, the MCP servers that wait for the user to sign in, so their tools are missing from the answer; a script can run meru mcp login <name>. Every tool call still goes through dispatch; the mode adds no second path.
A turn is everything between your question and the finished answer. A session is one conversation, a run of turns that share a transcript. Figure 2 follows two turns of one session. In the first, Meru searches your files and calls a tool that only reads. The second builds on the first and calls a tool that changes something, so Meru asks you before it runs. Later sections explain each step.
Four parts share the work. The agent loop inside merud runs the turn. The fast model, which Meru uses as the router, is a small model that picks a route, one of four: answer directly, search your files first, call tools, or search and call tools. It picks nothing else. From v0.4 a second short call picks which skills, files of instructions for one kind of task, to load. The main model chooses tools and writes the answer. Every tool call it makes passes through dispatch, one Go function, on its way to an MCP server, a separate program that offers tools such as search_gmail_messages.
The main model reads the context, everything merud sends it with your question; the agent loop lists the parts. One part is each allowed tool's schema: its name, description and argument types. For each MCP server, config.toml names the tools the model may see (allow, the allowlist) and the allowed tools that still need a yes from you on every call (confirm).
main asks for a tool, gets the result, then answers. Turn 2 searches too: the tools route searches your files, because the router sends some questions about them there, and recall runs on every route. Only turn 2 stops for you, because send_gmail_message sits in the server's confirm list.| Decision | Made by | How |
|---|---|---|
| Answer directly, search, call tools, or search and call tools | the fast model (the router) | It reads the probability of each route letter from one decoded token, and falls back to search and tools when unsure. merud searches anyway when a direct question names an indexed folder or asks about past chats, and adds tools when a question names a connected tool server. From v0.4, a separate short call picks the skills to load, and a picked skill brings the tools its allowed-tools key names when config allows them. |
| What to search for | merud, with no model | The question as you typed it. A question with three or more words that aren't filler names its own subject and is searched alone. A shorter one is a follow-up: merud appends the session's latest earlier question that names a subject, because "and the one after that?" finds nothing on its own. It skips a question made only of filler words, such as "try the last question again". With [index] retrieval = "agentic" no search runs first, and the main model writes its own search_files queries. |
| Which tools the model may use | you, in config.toml | Only tools in each server's or agent's allow list reach the model; the rest don't exist to it. Each [[commands]] entry is one tool. The built-in tools need no entry. |
| Which tool to call, with what arguments | the main model | It reads each allowed tool's name, description and argument schema, as the MCP server, agent card or [[commands]] entry wrote them, and picks. For a local command it picks only the parameter values; the program and its flags come from config. |
| Whether a call runs without asking | you, in config.toml and at the prompt | dispatch stops and asks when the tool is in its entry's confirm list, or its [[commands]] entry says confirm = true, unless you already approved that tool for this session. configure asks every time. web_fetch asks for a URL that no search result or question of yours gave, and before a download. |
| When the turn ends | the main model, with caps | The turn ends when the model answers without calling a tool, or at the round cap ([agent] max_rounds, default 8). The last round offers no tools, and a note at its end says this is the last step: answer from what the tools returned and say in one sentence what it didn't get to check. Without the note, a model holding the receipt it needed spent its last round planning another search and the turn ended with no answer. Meru also cuts its own notes (the cap note, and the tool and web notes in history) out of any reply that copies them, so a copied note never counts as an answer. A model that repeats a call twice loses its tools early. Each model call writes at most [agent] max_output_tokens (default 8,192, thinking included), and the whole turn has [agent] turn_timeout (default 5 minutes). A turn that hits a limit with no answer says sorry instead of going quiet. |
The tools and search+tools routes offer every allowed tool. search offers datetime, about_meru, the seven read-only file tools, read_file, list_folder, grep, search_files, search_images, view_image and analyze_table, and the local commands that don't ask first. A question such as "write about everything in my work folder" lands on search, and ten excerpts can't cover a folder. So does "what changed in the meru repo this week?" when meru is an indexed folder, and a declared git log answers it. A command with confirm = true changes something, so it waits for a tools route. direct offers datetime and about_meru: both only read, and "what day is Christmas?" and "which model are you?" route there. The model can't call a tool it hasn't seen, and the prompt stays shorter.
Every route, direct included, also offers web_search and web_fetch while web_search is on, which takes both [builtin] tools and [web] searxng_url, and a SearXNG that answers its check. A real session drove this, here with an invented song: asked "what does the song maname maname sung by r. devi acvtually mean", typo and all, the router sent the question direct at 0.966, where the model had no web tool. The model knew the song only in part, called the web-research skill as if it were a tool, and told the user it couldn't search the web. A question the router takes for general knowledge is often one a model half knows. With the web tools on offer and one line in the tools note (see Agent loop, step 2), the model can check a fact before it answers. The two schemas are short. web_fetch without web_search stays on the tools routes, since the model would have to guess a URL.
When dispatch reaches a tool in the confirm list, the client shows the tool's name and arguments and offers the choices merud sends, from these:
| Choice | What happens |
|---|---|
| Approve once | This call runs. The next call to the same tool asks again. |
| Approve for this session | This call runs, and dispatch skips the prompt for that tool until the session ends. The approval covers the tool, whatever its arguments. Four kinds of call never offer it and ask every time: configure, web_fetch on a URL no search result or question gave, an MCP tool in its server's always_confirm list, and, in a chat that read outside content, any MCP, A2A or command tool that asks (below). |
| This website for this chat | web_fetch on a URL no search result or question gave, and only for a read, not a download: this call runs, and later reads on the same host run unasked until the session ends. The approval carries the host, which the button names. |
| Always this website | The same, in every session: merud adds the host to [web] trusted_sites (see Web search). |
| Deny | The call doesn't run. Its outcome is declined, and the model hears that you said no, so it can answer without the tool or ask you what to do. |
"reason": "outside", which the clients show as "This chat has read mail or the web, so Meru asks before each call." Outside content is the result of an MCP, A2A or command tool that runs without asking (a tool that asks, such as a send, was already seen and approved), of web_search or web_fetch, and of read_file or grep on a mail attachment or a download under the output folder. The agent loop reads the mark from the chat's transcript at the start of each turn, so a restart can't clear it, and sets it after any round that brought outside content in; it rides on each call as dispatch.Call.Outside. Built-in tools that ask, write_file and edit_file, keep their session approval: they write only inside the output folder and never replace a file unasked. remember asks in such a chat (see Memory), and a job that read outside content declines every send (see Approvals in a job). A clean chat works as before. docs/design/security.md explains the design.merud sends the client an approval event with an ID, the call and the choices it offers, and holds the call. The client writes back one Reply line with that ID and a choice. A choice the approval didn't offer counts as deny.merud appends an approval line to the transcript, between the call's tool_call and tool_result lines, and the tool_calls row keeps the choice:
{"ts":"2026-09-23T10:17:21Z","type":"approval","call_id":"call-1","server":"google","tool":"send_gmail_message","choice":"once","trace_id":"9c2e…"}
merud provides itself instead of an MCP server. They belong to no server entry, so config.toml gives them one section with two lists:
[builtin]
tools = ["configure", "datetime", "about_meru", "remember", "write_file",
"edit_file", "read_file", "list_folder", "grep", "search_files",
"search_images", "view_image", "analyze_table",
"web_search", "web_fetch", "search_notes", "list_notes",
"read_note", "schedule_job"] # all nineteen, the default
confirm = ["write_file", "edit_file"] # the shipped default; add "remember" to approve each memory
off = [] # built-ins you chose to keep off; see below
tools lists the built-ins the model may use. Take a name out and merud doesn't register that tool with dispatch: the model never sees it, and meru tools doesn't list it. configure can go too; meru mcp add still works without it. An unknown name stops merud at load, with the valid names in the message, and so does a confirm entry that tools doesn't list. A listed tool still needs what it works on: the file tools need [index] folders, write_file needs [skills] output_dir, web_search needs [web] searxng_url, and the Apple Notes tools need a Mac. Without it the tool stays off, and merud logs one info line at startup that names the tool and the missing setting.
off lists the built-ins you chose to keep off, and turns nothing off by itself: a tool is on only while tools lists it. Settings and /mcp write it when you turn a built-in off, and take the name out when you turn it on. A built-in in neither list came with a release after your config was written: it stays off, both clients mark it New with a line naming it on the Meru card, and merud logs it at startup, until you turn it on or off. A name in both lists, or an unknown name in off, stops merud at load. A list written by hand is an allowlist, and a new tool such as one that reaches outside the machine must never turn on without a yes; before off, a new built-in stayed off with nothing to say it existed, and in one session a config without search_files couldn't find a CSV file it had indexed.
The built-in tools are configure and schedule_job, which edit config.toml and always ask, whatever confirm says (see First run and setup and Scheduled jobs); remember, which saves a memory without asking in a chat that has read nothing from outside, asks in one that has, and asks every time when you list it in confirm; write_file, which asks before each file it saves because the shipped list names it; edit_file, which replaces exact text in a file in the output folder, such as a name in a page Meru saved, keeps the file as it was in a hidden .<name>.bak beside it, puts in the pictures an edit to an HTML page names, as write_file does (see Built-in skills), and asks before each edit for the same reason; the two web tools, web_search and web_fetch (see Web search); the clock tool, datetime; about_meru, which reports this setup; seven read-only file tools; and three read-only Apple Notes tools. web_search, datetime, about_meru and the file tools run without asking unless you list them. web_fetch runs without asking for a URL a search result or your question gave, and asks otherwise:
| Tool | What it returns |
|---|---|
read_file | A file's whole text, 12,000 characters per call, with the offset for the next call. PDFs come page by page, a Word file as text, and an Excel workbook sheet by sheet under a --- sheet Name --- line, with a sheet or a CSV file one row per line and its cells joined by | . A bare filename that no folder holds is looked up in <output_dir>/attachments/, so the model can pass the name a mail tool reports. An HTML page comes as its text, except one in the output folder, which comes as its markup: the model edits there, and a real turn read back a page of links as text and wrote it again with every link gone. |
list_folder | A folder's folders, then its files with size and modified date, 1 to 3 levels deep, at most 300 entries. |
grep | Every line that holds a word or an RE2 regular expression, as path:line: text (path (page N) for a PDF, path (sheet S, row N) for an Excel sheet, path (row N) for a CSV file), and each file whose name matches as path (file name), until 50 lines (the model may ask for up to 200), 5 seconds or 20,000 files. A line longer than 200 characters shows the 200 around its first match. With no path it searches every folder but the past chats. A plain-text pattern that finds nothing and reads as a regular expression, such as a|b or x.*y, runs again as one, and the result says so. |
search_files | The hybrid search of Retrieval for the model's own query: 8 excerpts by default, at most 20 and 14,000 characters, each numbered after the turn's other excerpts, with its path, heading and lines or page. Its excerpts join the turn's sources event. Offered when [index] folders is set. |
search_images | The indexed images nearest to query, words for what a picture shows, or to image, the path of a picture in the [index] folders or an attached one under the output folder, read with the file tools' rules, a 20 MiB cap and a check that the bytes are an image. 8 by default, at most 20, numbered after the turn's other sources; the text holds only their paths, so the model names and cites them, and one with vision can open them with view_image. Offered when the index reads images. |
view_image | The picture at path, in the [index] folders or attached under the output folder, for the model to look at on its next round. The bytes ride on the tool message's images, as on an attached picture's question; the result's text, which the transcript and tool_calls keep, is one line that names the file and its size, with the picture as an image source. The same checks as search_images apply. A picture over 1,536 pixels on its longest side goes as a JPEG scaled down to that, since the model's cost grows with the pixels: a 4,000 by 3,000 phone photo of a bill cost qwen3.6:35b 1,756 tokens at 1,536 pixels, and it still read every line. A WebP picture goes as it is, since Go's standard library can't decode it. A turn opens at most 8 pictures; a ninth call is refused with text that says so. Offered only while the main model lists vision (see Questions with images). |
analyze_table | An Excel sheet's or a CSV, TSV or .tab file's rows, filtered, grouped, counted, added up (sum, avg, min, max, median, and percentile with p from 0 to 100) and sorted, from fixed fields the model fills in: path, sheet, header_row, where (=, !=, <, <=, >, >=, contains, starts_with, empty, not_empty, in), group_by, aggregate, columns, sort and limit. With only a path it describes the sheet: its columns, their types and sample values, the header row it chose and the first rows. Sums add exact decimals, so a column of cents adds up to the cent; a median or percentile interpolates as Python's statistics.quantiles(method="inclusive") does, exactly. A list field also takes one name, or a string that holds a list. It reads every row, up to 100,000, through the indexer's readers and limits; a call takes at most 10 conditions, 100 values for in, 3 group columns, 10 aggregates, 20 columns and 3 sort keys, and returns at most 200 rows and 10,000 groups. The result cites the sheet and the rows it drew on. A file that isn't a table, such as a PDF, a Word file, Markdown or plain text, gets its text back as read_file returns it, under the line "analyze_table: path isn't a table, so here is its text, as read_file returns it."; only a file read_file can't read either, such as a picture, still fails. The tool once refused such a file and said to use read_file: a real turn called it on a hotel receipt PDF, got that answer, and never read the receipt. Offered when [index] folders is set. |
datetime | The current date and time with weekday and zone; the time in another zone; a date's weekday and how many days it is from today. Offered on every route, direct included, because "what day is Christmas?" routes direct. |
about_meru | merud's own facts, in under 2,000 characters: the profile; the main, fast and embed models and what each does; the main model's capabilities, size, quantization and context length from Ollama's /api/show; the Ollama version, on a labelled line of its own; the computer; the [index] folders with file and chunk counts and the size of meru.db; each MCP server and A2A agent with its state and tool count; the local commands, built-in tools, skills and memory counts by kind; the output folder; and merud's build. It copies names, counts and paths only; secrets, env and header values, a server's last error, a memory's text and transcript lines stay out. Offered on every route, as datetime is: asked "which model are you using?" on a direct turn, a model answered from its training with another company's name and no version. Its description asks the model to quote names, versions and numbers as the tool gives them: with the version inside a sentence, a model read Ollama 0.34.0 and wrote "Ollama 0.44". |
web_search | Web results from SearXNG, numbered after the turn's other sources: title, URL, a snippet and the date when known. Each result joins the turn's sources event as a web source. Offered when [web] searxng_url is set, on every route, direct included. |
web_fetch | One public web page's text, 12,000 characters per call, like read_file; with a prompt, the fast model's answer from the page; with save, a file saved in ~/meru-output/downloads/. A page read takes the turn's next number and joins the sources event as a web source. Offered while [builtin] tools lists it: on every route while web_search is on too, and on the tools routes alone otherwise. |
search_notes | The user's Apple Notes that hold every word of query, in the title or the text, ignoring case: notes whose title matches first, newest first, 10 by default and at most 30, each with its id, title, folder, modified date and a snippet. folder limits it to one Notes folder. Offered on the tools routes, on a Mac. |
list_notes | With no folder, every Notes folder with its note count, then the newest notes; with a folder, that folder's notes, newest first. Each note comes with its id. |
read_note | One note's text by its id, 12,000 characters per call with the offset for the next, like read_file. A locked note gives its title and says it's locked. |
schedule_job | Saves a scheduled job the user asked for in chat, such as "every weekday at 7, brief me": a name, a cron schedule with every_weeks and from, and a prompt with an optional skill, or a declared command with its args, and an optional output. It never sets allow. It always asks, and the approval card shows the schedule in words and the next run beside the cron fields. A job's own turns never see it. See Scheduled jobs. |
[index] folders, [skills] output_dir (~/meru-output) and, for read_file, list_folder and grep, the session transcripts in ~/.meru/sessions (see Facts and episodes). They skip what the indexer skips (see Getting your content in): they never follow a symlink, and they refuse secret, hidden, ignored, binary and oversized files with the indexer's reason. The output folder holds what write_file wrote, what web_fetch downloaded, the mail attachments the google server saves (see Adding an MCP server) and the copies of files the user attaches in the desktop app (see Desktop app). The file tools only read there; write_file keeps its own rules. Outside the output folder and the transcripts, they read nothing that search couldn't already put in the prompt. The indexer never indexes the output folder or the transcripts, so a web page, an attachment or an old chat can't reach a later turn through search. The skip rules apply from the folder a path sits in downwards: the sessions folder sits under the hidden ~/.meru and stays readable, a hidden file inside it stays skipped, and the rest of ~/.meru, config.toml and secrets.toml among it, stays out of reach. merud leaves the file tools out when no [index] folder is listed.
The Apple Notes tools read the Notes app's own database, ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite, through internal/applenotes. Each call opens it read-only, answers and closes it, so an answer shows the notes as they are now, changes still in the database's -wal file included. Meru keeps no index or copy of a note. Apple publishes no schema, so the reader looks up the entity numbers for notes and folders in Z_PRIMARYKEY and the column names with PRAGMA table_info, which differ between macOS releases, and decodes a note's text from its gzipped protobuf with google.golang.org/protobuf's wire reader. Deleted notes and Recently Deleted stay out, and a locked note's text is never read. The tools never write: a row written behind the Notes app's back can break its iCloud sync, and writing through the Notes app needs osascript, which Meru doesn't run (see Local commands).
Reading the database needs Full Disk Access for merud, the program launchd runs. macOS never asks for it; it refuses the open. Until the user grants it, each Notes tool returns one sentence that says where to turn it on, the Settings screen shows the same sentence, and merud logs at startup whether it can read the notes. merud carries an ad-hoc signature, so macOS ties the grant to the binary's exact build: after every update the user turns Full Disk Access for merud off and on again. The Mac installer's Apple Notes step walks the user through the grant (see Installer). A question that says "Apple Notes" or "Notes app" gets the tools on a route that lacks them (see Routing); the router itself isn't told about them.
In tool_calls and the metrics, a built-in call has kind = "builtin" and server = "meru".
[[commands]] entry with confirm = true asks before each run and offers all three choices; one without runs without asking. Read-only commands run freely, and anything that changes something should ask. A command call has kind = "command", server = "meru" and tool = "cmd.<name>", and its tool_call line, prompt and row show the argv it runs (see Local commands).merud. dispatch keeps them in memory, per session and tool. They end with the session or with merud, and never reach config.toml. To stop Meru asking about a tool for good, remove it from the confirm list yourself. Lasting trust then comes from one place, a file you edit and can read back.meru "..." asks on standard error with the same choices, as [o]nce [s]ession [d]eny, so the answer on standard output stays clean. Its session ends with the answer, so "for this session" covers only this question. When standard input isn't a terminal (a script or a pipe), nobody can answer, so the client denies without asking and says so.dispatch ends every call that needs a yes as declined without a prompt. A scheduled job is the one exception, and a narrow one: a tool that would ask once runs when the job's allow names it, and a call that asks every time is declined whatever the job says (see Scheduled jobs). A job's answer says which calls it skipped.meru chat keeps one session open until you quit. Each one-shot meru "..." starts a new session. The desktop app can reopen a past session and continue it.merud loads up to [agent] history_turns (default 10) of your earlier questions and Meru's earlier answers from this session, then drops the oldest until the rest fits the history budget of 8,000 characters. Older turns drop out of the prompt but stay in the transcript, and search can find them there.[image: name] note per picture its question carried.main model resolves the reference. It reads turn 1's answer in the history, which named the thread and the date agreed in it, and works out which thread "that thread" means. It reads answers, not the raw tool results behind them.Both clients can delete a chat, put it in a folder and tag it. Each change is an op to merud, which changes the files first; meru.db follows.
session_delete takes a session ID, never a path. merud checks the ID against the session ID pattern, refuses anything but a regular file, removes the transcript, then deletes the session's rows: sessions, messages and their keyword entries, the summary's keyword entry and vector, and turns. The chat leaves the list and recall at once, and nothing undoes it; usage counts that come from turns drop with it. Its tool_calls rows stay, stored as an incognito chat's are: each keeps its tool, server, kind, time, duration, outcome and approval, and loses its arguments and result, so meru log still shows every call and nothing of what the chat said. If merud stops between the two steps, its next start does the same for every session whose file is gone, which also covers a file removed by hand. The uploads the chat's questions carried stay in ~/meru-output/uploads/, which is yours to clear.~/.meru/sessions/folders.json lists them as a JSON array, so a folder that holds no chat yet survives, and each chat's own meta line says which folder holds it. session_move moves a chat and adds a new name to the list. chat_folder_rename renames a folder and appends a meta line to each chat in it, so every transcript still names its folder; chat_folder_remove takes the name off the list and moves its chats back to the main list. It deletes no chat. A name has at most 60 characters.session_tag adds and removes tags. A tag is one word of letters, digits, - and _, in lower case, of at most 32 characters, and a chat holds 12 at most. Replay copies a chat's tags into sessions.tags and into its summary_fts entry, after the summary, so a keyword search for a tag finds the chat when a turn recalls earlier conversations. The summary's vector holds the summary alone. The meta line keeps the tags in the transcript, where grep finds them.meta line merud puts the file's modification time back, and a chat moved into a folder doesn't jump to Today.One lock in merud makes these ops take turns, so two clients can't write the folder list over each other.
An incognito chat keeps nothing about what was asked. The desktop app's Incognito chat button, /incognito in either client and meru chat --incognito start one. The first ask carries incognito: true, and merud answers with a session ID such as incognito-7f3a09bc, which fails the session ID pattern, so no code that works on files accepts it.
merud keeps the chat's lines in a transcript.Session with no file, so each turn reads the chat's history as usual. Nothing reaches ~/.meru/sessions, so the chat gets no sessions, messages or turns row and no summary.remember, and remember refuses a call from an incognito session, since a model can call a tool it wasn't offered. Recall still reads your memories and earlier chats into the prompt; reading keeps nothing.dispatch and gets a tool_calls row with its tool, server, kind, time, duration, outcome and approval, under the chat's incognito ID, but no arguments and no result. Its span leaves both out even with capture_content = true. The transcript lines dispatch writes go to the chat's memory with the rest.session_delete with the chat's ID, and merud drops the history. merud also drops an incognito chat after an hour with no question, and holds 16 at most, so a chat a client forgot doesn't stay in memory. A question in a chat merud dropped fails with a message to start a new one./save refuse an incognito chat, and it takes no folder or tags. A file you attach is still copied into the uploads folder, since you picked it.tool_calls rows have no transcript behind them, so a rebuild of meru.db loses them, as it loses the stripped rows of a deleted chat. That errs toward keeping less, which is what an incognito chat asks for.The turn's span carries meru.session.incognito. The metrics count the turn as any other, since they hold no text and no ID.
Meru gives models three jobs, called tiers. Code depends on the tiers; config.toml says which model fills each one, so swapping a model never touches the code.
| Tier | Job |
|---|---|
fast | routing, picking a turn's skill, session summaries, answers about a fetched page |
main | reasoning, writing the answer, choosing tools |
large | optional: a bigger answer model you ask for by hand |
embed | embeddings for the index and for queries |
With [router] answers = "routed", the fast model also answers easy direct questions (see Which model answers).
fast and embed always run on the local Ollama: the router needs token probabilities, which only Ollama reports, and search must never send a file or a question anywhere. main may instead name an answer model on another model server, as @name (see Answer endpoints).
An embedding is a list of numbers that stands for a text's meaning, so two passages that say the same thing in different words get nearby lists. The length of that list is its dimension count.
Two profiles ship in config.toml, and lite is the default.
| Tier | lite (default) | full |
|---|---|---|
fast | hf.co/openbmb/MiniCPM5-2B-GGUF:Q4_K_M (1.6 GB) | same |
main | same model as fast | qwen3.6:35b-a3b-mxfp8 (38 GB, 8-bit) |
embed | embeddinggemma-2:440m (713 MB, 768 dims, text and images) | same |
| Hardware | 16 GB of RAM; runs on a CPU, faster with a GPU or Apple silicon | Apple silicon with 64 GB or more |
Both profiles embed with embeddinggemma-2:440m, EmbeddingGemma 2 with its vision encoder. It puts text and images in one 768-number space, so a question can find a picture as well as a page, and it replaced nomic-embed-text and qwen3-embedding:0.6b. Changing the embedding model or its task prefixes makes merud drop every vector and re-embed every file on its next start (see Storage).
lite uses two small models. It downloads in a couple of minutes and runs on almost any computer. One model fills both fast and main, so only two models sit in memory.full swaps in Qwen 3.6 35B-A3B, a mixture of experts that runs about 3B of its 36B parameters per token. Its MXFP8 build runs on Ollama's MLX backend on Apple silicon. It was the fastest model in our benchmark (see Models we tried), and Ollama held 36 to 52 GiB for it while it answered, so full needs a 64 GB Mac.Speech to text runs outside Ollama in its own process, with a Whisper model per profile, so it takes none of Ollama's model slots (see Speech to text).
merud keeps each model loaded by asking Ollama for keep_alive: -1, and warms every tier at startup. Ollama must allow enough models in memory at once: OLLAMA_MAX_LOADED_MODELS set to 3 for full.
The warm-up runs in two parts. Before merud takes questions (its socket is open, and answers that Ollama isn't ready yet), it sends the fast model a one-token "hi" and the embed model one short text: the router needs the first on every question, the store the second to open, and both load in a second or two. The answer model, the one a set in use names (see Model sets), loads next, in the background, while merud already answers pings, settings and the router. Its warm-up prompt is the system prompt a direct question gets, with the tools and skills it lists, and a one-token answer with the set's think setting. A question that reaches its first answer call before the load ends waits for that load, and a model switch waits too, so Ollama never loads the model twice or unloads it while it loads. The info log says loading the answer model, then answer model warm with the time it took; a failed load logs the error couldn't load the answer model with the ollama pull command to run. A model that isn't pulled no longer stops merud; the first question then fails with Ollama's reason.
A real session showed why the warm-up uses a real prompt. merud warmed qwen3.6:35b-a3b-mxfp8, a 38 GB mixture-of-experts model, with "hi" before it took questions; the load took 84 seconds, and Ollama kept the model, as keep_alive: -1 asks, with no reload in its log. Yet the first question, 26 minutes later, spent 2 minutes 17 seconds on a prompt of 1,349 tokens, and the next question spent 6 seconds on 1,460. A mixture-of-experts model runs each token through a few of its many experts, so a three-token prompt touched a sliver of the weights, and the first long prompt read the rest from disk. A warm-up prompt of a thousand tokens or more touches most experts before the user asks, and Ollama keeps its opening for the first question to reuse.
Loading a 38 GB model at every start costs a minute or two of disk reads, in the background. keep_alive: -1 already says the user wants the models in memory, and the other choice, a load on the first question, is the wait the real session hit. So the warm-up stays on for every start.
The fast tier needs a runtime that reports log probabilities, because routing reads them. Ollama added them in v0.12.11. Meru needs v0.40.5 or later all the same, the first release tested to serve its embedding model, embeddinggemma-2, and to embed images; an older Ollama refuses to pull that model with HTTP 412. merud reads /api/version when it starts and every 30 seconds after. On anything older it stays up, answers no question, and says which version it found and where to update (see SearXNG and Ollama). Routing costs no extra model: the fast model is already loaded.
A new embedding model makes every stored vector stale. So does a change to its query or document prefix, even when the model and vector size stay the same. The store records the model name, vector size and a fingerprint of both prefixes. When one changes, the store drops every vector and keeps the text, so keyword search keeps working while the indexer re-embeds your files (see Storage).
A 120B model at 4-bit needs about 60 GB, which leaves even the 64 GB development machine no room and makes it swap. Meru won't support models that size.
[router] answers decides which model writes each answer:
[router]
answers = "routed" # "main", the default: every answer from main
easy_above = 0.8 # how sure the router must be; "routed" only
[models]
large = "" # optional: a bigger model you ask for by hand
With "routed", the fast model answers a question only when every one of these holds, read after the routing rules have had their say:
direct, and the router chose it itself (outcome ok);easy_above sure;Anything else goes to main: a question that searches your files or uses a tool, a direct one the router isn't sure of, a fact question, a picture, a skill. The pick reads the router's existing result and makes no model call. The turn picks once, before it builds its prompt, and every step reads that choice, so the window, the self line and the checks fit the model that answers. The consent question for an endpoint comes after the pick, so a turn the fast model answers never asks.
A weak fast answer goes to main, once. When the fast model's answer ends cut_off, capped, window_full, gave_up or bad_output, merud sends an escalate event ("the fast model's answer was cut off, so … answers.") and runs the question again on main, in a fresh turn that keeps the session, the question and the tool call numbers. The clients fold what streamed into a collapsed "First try" above the new answer. The weak answer never reaches the transcript, and a second escalation never happens.
The large model answers only when you ask. large names a bigger model, on this machine or an endpoint: "Ask the large model" in the app, /large in meru chat, meru -large, or large: true on an ask. When a main answer ends weak and a large model is set, done carries offer_large and the clients offer it. Nothing sends a question to the large model on its own.
done names the model that wrote each answer in model, which meru check records, so the benchmark counts fast answers and escalations (make bench ANSWERS="main routed" runs each set both ways). Metrics carry the tier, fast, main or large.
In September 2026 we tried four models as the main model, on the development machine, an M4 Max with 64 GB, with Ollama 0.34.0 and MiniCPM5-2B as fast. The test question asked how to use btop, and made the model search the web and read pages over several rounds.
| Model | Size | What Ollama lists | What we saw |
|---|---|---|---|
hf.co/openbmb/MiniCPM5-2B-GGUF:Q4_K_M | 1.6 GB | tools, thinking | about 55 s; made up command flags and misread what tools sent back |
qwen3.8:27b (dense) | 17 GB | vision, tools, thinking | the best-grounded answer, with real flags from the man page, but about 5 minutes: 80,000 input tokens, and slow prompt reading |
qwen3.6:35b (mixture of experts, about 3B of 36B parameters per token) | 23 GB | vision, tools, thinking | about 26 s, about 78 tokens a second; now and then a tool call Ollama can't read, or thinking and no text, which merud retries |
gemma3:12b (12.2B parameters, 131,072-token context) | 8.1 GB | vision | answers direct and image questions; Ollama refuses it tools |
MiniCPM5-2B stays the fast model: it routes well and fast. One question can't rank the rest, so we built a benchmark.
The benchmark. In September 2026 we ran six model sets through 50 tasks on the same Mac, with Ollama 0.34.0, MiniCPM5-2B as fast, nomic-embed-text as embed, and think = false in every set. The owner drew the tasks from their own files, mail, calendar and repositories, so we don't publish them; each task has a check that passes or fails the answer. Eight tasks go to the direct route, nine need a search of the files, thirteen need one tool call, twelve need several, four span several turns, and four test honesty. Each set ran every task three times, 150 runs per set.
| Set | Answer model | Passed | Median time per task | 90th percentile | Median time to first token | Tokens a second |
|---|---|---|---|---|---|---|
qwen-moe | qwen3.6:35b-a3b-mxfp8 (38 GB) | 133 of 150 (89%) | 6.8 s | 19.4 s | 4.1 s | 63 |
gemma-moe | gemma4:26b-mxfp8 (28 GB) | 138 of 150 (92%) | 16.3 s | 29.1 s | 15.6 s | 57 |
qwen-dense | qwen3.8:27b (17 GB) | 135 of 150 (90%) | 55.9 s | 121.1 s | 34.6 s | 17 |
qwen-moe-q4 | qwen3.6:35b (23 GB) | 133 of 150 (89%) | 10.6 s | 28.4 s | 5.7 s | 80 |
gemma-moe-q4 | gemma4:26b-a4b-it-qat (15 GB) | 120 of 150 (80%) | 18.7 s | 29.8 s | 17.6 s | 92 |
minicpm-lite | MiniCPM5-2B, the lite answer model (1.6 GB) | 102 of 150 (68%) | 13.1 s | 28.8 s | 11.8 s | 130 |
| Kind of task (runs) | qwen-moe | gemma-moe | qwen-dense | qwen-moe-q4 | gemma-moe-q4 | minicpm-lite |
|---|---|---|---|---|---|---|
| direct (24) | 24 | 24 | 24 | 24 | 24 | 23 |
| search of the files (27) | 27 | 27 | 26 | 27 | 27 | 25 |
| one tool (39) | 37 | 37 | 37 | 35 | 33 | 24 |
| several tools (36) | 22 | 28 | 24 | 24 | 13 | 6 |
| several turns (12) | 11 | 12 | 12 | 12 | 12 | 12 |
| honesty (12) | 12 | 10 | 12 | 11 | 11 | 12 |
The three pass about as often: a gap of five runs in 150 is too small to rank them. They part on tasks that need several tools, where gemma4:26b-mxfp8 passed 28 of 36 and qwen3.6:35b-a3b-mxfp8 22, and on time. qwen3.8:27b, a dense model that runs all 27B parameters on every token, writes 17 tokens a second and took a median of 55.9 s a task, eight times as long as qwen3.6:35b-a3b-mxfp8. qwen3.6:35b-a3b-mxfp8 answers fastest, so it fills main in the full profile and stays the answer model we use. gemma4:26b-mxfp8 suits someone who asks for work across several tools and will wait for it.
The last three rows are the smaller Macs' choices, run the same way. qwen3.6:35b, the same Qwen model at 4 bits, passed as many tasks as the 8-bit build and 24 of 36 across several tools, at 10.6 s a task against 6.8 s. gemma4:26b-a4b-it-qat passed 120 and only 13 of 36 across several tools, and starts as slow as its 8-bit build. MiniCPM5-2B, the lite answer model, passed 102: it handles direct questions, file searches and honesty tasks, but only 24 of 39 one-tool tasks and 6 of 36 across several. It writes 130 tokens a second, yet takes a median of 11.8 s to its first token, most of it reading a prompt of about 20,000 tokens.
Why Gemma 4 starts slow. Both mixture-of-experts models read a prompt at about 1,100 to 1,200 tokens a second, and Ollama honoured think: false for both: on direct tasks, which offer no tools, the first token came after a median of 0.5 s on Gemma 4 and 0.4 s on Qwen. The gap opens on turns that offer tools, whose schemas run to about 13,000 tokens. Ollama keeps the prompts it has read and reuses the longest opening a new prompt shares with one of them. Qwen's chat format writes the tool schemas first and the system prompt after them, so the schemas sit in the shared opening: a new question reused a median of 15,658 tokens and read 4,374 new ones. Gemma 4's format writes the system prompt first and the schemas after it, and Meru's system prompt changes from question to question (see The agent loop, step 2), so every new question reads the schemas again: it reused a median of 1,278 tokens and read 13,778. Over the benchmark, Ollama read 2.2 million new prompt tokens for Gemma 4 against 0.8 million for Qwen, from about 6 million each. Meru sends both models the same request, so the cause sits in how Ollama lays out Gemma 4's prompt, and merud has no bug to fix here. Moving the parts that change out of the system prompt could let Gemma 4 reuse the schemas; we'd measure that on this benchmark before changing the prompt every model gets.
Memory. With a 32,768-token context, Ollama's log put the peak memory of a qwen3.6:35b-a3b-mxfp8 call at 36 to 52 GiB, with a median of 46.6, and of a gemma4:26b-mxfp8 call at 27 to 40 GiB, with a median of 37.0. On the 64 GB test Mac, Ollama let the GPU use 51.8 GiB. MiniCPM5-2B takes about 3 GB more beside the answer model.
Which model for which Mac. The installer offers an answer model only where its file, what Ollama holds for a 32,768-token context, and the router fit beside macOS and a few open apps:
| Memory | Answer model | Why |
|---|---|---|
| 16 GB | MiniCPM5-2B, the lite profile (about 2.3 GB with embeddinggemma-2:440m) | the only answer model we tried that leaves room for the rest of the Mac; it passed 102 of 150, weakest where a task needs tools |
| 32 GB | gemma4:26b-a4b-it-qat (15 GB) | Gemma 4 at 4 bits: 120 of 150 tasks passed. Ollama loaded it in 15 GB with a 32,768-token context, about 18 GB with the router |
| 48 GB | qwen3.6:35b (23 GB) | Qwen 3.6 35B at 4 bits passed 133 of 150, as many as the 8-bit build. Ollama loaded it in 23 GB with a 32,768-token context, about 27 GB with the router. gemma4:26b-mxfp8 peaked at 40 GiB and qwen3.6:35b-a3b-mxfp8 at 52, more than a 48 GB Mac can give them |
| 64 GB or more | qwen3.6:35b-a3b-mxfp8, the full profile; gemma4:26b-mxfp8 for work across several tools | the benchmark's figures above |
We checked the 48 GB and 32 GB lines against memory measured on the 64 GB Mac, not on a 48 GB or a 32 GB Mac.
config.KnownModels lists the six we offer, smallest first: MiniCPM5-2B, gemma3:12b, gemma4:26b-a4b-it-qat, qwen3.6:35b, gemma4:26b-mxfp8 and qwen3.6:35b-a3b-mxfp8, with their sizes and a line each on what they did well and badly. It leaves out qwen3.8:27b, which took about eight times as long per task as qwen3.6:35b-a3b-mxfp8. The desktop app's Settings, Models shows each one with its commands, which also work in a terminal:
ollama pull hf.co/openbmb/MiniCPM5-2B-GGUF:Q4_K_M
ollama run hf.co/openbmb/MiniCPM5-2B-GGUF:Q4_K_M
ollama pull gemma4:26b-a4b-it-qat
ollama run gemma4:26b-a4b-it-qat
ollama pull qwen3.6:35b-a3b-mxfp8
ollama run qwen3.6:35b-a3b-mxfp8
ollama run opens a chat with the model in the terminal, to try it before Meru uses it.
Switching the answer model. "Use for answers" on a model's card sends model_set (see Desktop app). merud refuses a model off the list, and one GET /api/tags doesn't show, with the ollama pull to run. It switches the way a model set switches, unloading the old answer model first, then writes [models] main with the same safe write and lock as the other settings. A pick in Settings is a setting, and every setting made there lands in config.toml; the chat's /model is for comparing, so it waits for /model save. The fast and embed models stay as they are. To set any other model, name it in a model set, or edit [models] main in config.toml and restart merud.
A model set names the models to switch between, so a switch names one thing rather than three. Sets sit beside [models] in config.toml:
[[models.sets]]
name = "qwen-moe"
main = "qwen3.6:35b-a3b-mxfp8"
think = false
[[models.sets]]
name = "gemma-moe"
main = "gemma4:26b-mxfp8"
think = false
A set names at least one of main, fast and embed; a set without main keeps the answer model in use. think = false sends Ollama think: false with every answer call, so a model that reasons before it answers doesn't lose on time to first token for that reason alone; left out, each model does what it does by default. Outside a set, [models] think decides, and it defaults to false: the benchmark ran every model with thinking off, and a fresh install should answer as fast as those numbers say. think = true there turns thinking back on. config.Load checks that each set has a name of letters, digits, ., - and _, that no name repeats, and that each set names a model. At startup merud logs a warning for each model a set names that GET /api/tags doesn't list, and starts anyway: the model can be pulled later. The set in use at startup is the first whose models match the ones merud started with.
/model <name> in meru chat, meru model use <name> and Use in Settings send model_use. The switch lasts until merud stops, which is what a comparison wants; /model save, meru model save and Make default send model_save, which writes the models in use to [models]. model_use runs in this order, because keep_alive: -1 keeps every model in memory, and three main models of 38, 28 and 17 GB would push a 64 GB Mac into swap and make every measurement after it noise.
First, merud waits for the startup load of the answer model to end, if it still runs, then checks that Ollama has the new main model, so a switch that can't finish unloads nothing. Then come the three numbered steps:
POST /api/generate with the model, no prompt and keep_alive: 0 (OllamaEngine.Unload)./api/ps every 100 ms until it no longer lists the old model, for at most 10 seconds.Last, merud hands the model and its think setting to the agent, and only then replies.
Steps 1 and 2 are skipped when the old answer model is the new one, or is also the fast or embed model, as in lite, since the router still needs it. A step that fails comes back as an error that names it, such as "step 2 of 3: ollama still holds qwen3.6:35b in memory after 10s", and the answer model and the set in use stay as they were. One switch runs at a time.
Only the main model changes while merud runs. The router, the skill pick, the summarizer and the index read the fast and embed models at startup, so a set's fast and embed models take effect once the set is saved and merud restarts, and the reply says so. A set that changes embed needs --rebuild: a new embedding model or changed task prefixes make every stored vector stale, and merud re-embeds every file in the [index] folders at that restart. A set that changes fast carries a warning, because the router needs log probabilities and one token per route letter (see Routing).
Which model wrote each answer. Before an answer whose model differs from the session's last one, the agent appends a model_switch line to the session (see Session transcripts); a session's first answer gets one with an empty from. The answer line records the model's time to first token on the round that first wrote text, the time Ollama spent writing tokens, its bad calls and whether the turn hit the cap. The turns table takes these from the transcripts, so /usage by model rebuilds with the rest of meru.db:
MODEL TURNS TTFT p50 TOK/S CALLS BAD CALLS CAPPED
qwen3.6:35b-a3b-mxfp8 41 820ms 24.1 63 2 1
gemma4:26b-mxfp8 38 610ms 31.7 59 7 0
TTFT p50 is the median time to first token. TOK/S divides the tokens written by Ollama's eval_duration. CALLS counts tool calls. BAD CALLS counts what meru.model.malformed_calls counts (see Metrics). CAPPED counts turns that used every round agent.max_rounds allows and wrote no text.
A model without tools. Ollama refuses a request that offers tools to a model whose /api/show lacks tools, with a 400 that says the model "does not support tools". Every route offers some tool, datetime and about_meru at least, so with such a model every turn would fail. Before it builds the prompt, the agent asks whether the answer model lists tools, through the engine's cached Details. When it doesn't, the turn offers no tools, and when the route would have offered more than the tools every route offers (those two, and the web tools while web_search is on), or the scope is Web, a notice under the answer names the model and says how to pick another. So gemma3:12b answers direct questions, questions about images, and search questions from the excerpts search puts in the prompt, and can't read mail, notes, the web or files on its own. Settings says so on its card, and model_set replies with a warning.
Context length. merud sends num_ctx with every chat call. Meru's prompts with tool schemas run to about 25,000 tokens, and Ollama's own default can be far smaller, which would cut the prompt short on a fresh install. Each call to one model sends the same value, because Ollama reloads a model whose num_ctx changes. The CONTEXT column of ollama ps shows what each loaded model got.
The answer model gets a window sized for it. Before it loads, at startup and on each switch, merud asks Ollama's /api/show for the most tokens the model can read and its attention shape: the layers, the cached heads in each, and their width. From the shape it works out the memory a token of context takes in Ollama's cache, at 2 bytes a number:
bytes a token = (cached heads over all layers) × (key width + value width) × 2
The window is the model's most, cut to what fits in an eighth of the memory the model loads into, and never less than [ollama] context_length, 32768 by default. Ollama sets the cache's memory aside for the whole window when the model loads, so the cap matters: qwen3.6:35b caches heads in one layer of four and takes about 20 KB a token, so its full 262,144 tokens cost 5.4 GB and fit an eighth of a 64 GB Mac. On Linux with an NVIDIA card the memory is the card's own; a dense model of its size can take ten times as much a token and gets a smaller window. The fast and embedding models keep context_length, since they read short prompts. When the fast model is the answer model, as on lite, it loaded at context_length before merud sized its window, and loads once more on the next question.
context_length is the fallback for a model whose shape Ollama doesn't report, such as gemma4, and context_length = 0 leaves every window to Ollama and OLLAMA_CONTEXT_LENGTH. The agent loop reads the answer model's window, to keep a turn's tool rounds inside it (see Agent loop, step 5). merud.log says what it chose at info: answer model window model=qwen3.6:35b window=262144 model_max=262144 cache_mb=5120.
An interface in Go names a set of methods a type must have. Everything in Meru that talks to a model goes through this one, which has four methods:
type Engine interface {
Generate(ctx context.Context, msgs []Message, tools []ToolSpec, opts Options) (Completion, error)
Stream(ctx context.Context, msgs []Message, tools []ToolSpec, opts Options) (iter.Seq2[Delta, error], error)
Embed(ctx context.Context, inputs []Input) ([]Vector, error)
Info(ctx context.Context) (ModelInfo, error)
}
OllamaEngine is the main implementation. It talks to Ollama over HTTP on loopback and refuses to start if the configured URL points anywhere else. OpenAIEngine answers the models in [[endpoints]], and Engines, the engine merud holds, sends each call to the right one (see Answer endpoints). Neither can reach one of Ollama's cloud models, and the endpoint engine reaches only the server its entry names, on this machine or your own network.
Ollama itself can: once signed in to ollama.com, a model whose tag ends in cloud, such as gpt-oss:120b-cloud, answers through the local API while Ollama passes the whole prompt to ollama.com. The loopback check can't see that, so Meru refuses such a model twice. Config refuses a cloud tag in [models] and in every model set when it loads. Before its first chat or embedding request for a model, the engine asks /api/show about it and refuses one whose reply names a remote host, which also catches a cloud model copied to a plain name (ErrCloudModel).
Each model writes tool calls in its own format. Ollama converts them to structured JSON, and the engine converts that JSON to Meru's own types, so the agent loop never sees a model-specific token. When Ollama's parser rejects what the model wrote, it sends an {"error": ...} line part way through a stream it had answered 200 OK. Stream wraps any such line in ErrModelOutput, and the agent loop tests for it with errors.Is to retry the round (see Agent loop). Ollama sometimes sends the same parser error as a 500 from /api/chat before any text, as in "XML syntax error on line 8: element <function> closed by </parameter>". That *APIError wraps ErrModelOutput too, by the words Ollama's parsers use, so the round retries the same way. Any other failure before the stream starts, such as Ollama down or a model not pulled, stays an *APIError or a transport error, and fails the turn as before. Each Completion also carries Ollama's counters (prompt_eval_count, eval_count, load_duration, prompt_eval_duration, eval_duration), which feed the metrics described in Seeing where the time went.
For routing, Options gains two fields, LogProbs and TopLogProbs, and Completion gains LogProbs: for each generated position, the chosen token and the alternatives the model weighed, each with its log probability. Both default to off, so other callers see no change, and the interface keeps its four methods.
Embed takes []Input, not plain strings. An Input is a text, an image's bytes, or both, with a Title for a document and a Query flag for a search query. Images reached the embed call as a field, the way they reached the chat call as Message.Images, so the interface kept its four methods. The engine applies the embedding model's task prefixes, which merud hands it from config.EmbedModels: for embeddinggemma-2, task: search result | query: {query} on a query and title: {title} | text: {text} on a document, and none on an image. A model Meru doesn't list gets the text as it is. A text-only input goes to /api/embed as a plain string, and anything with an image as {"text", "image"} with the image in base64. Ollama also accepts two shapes that look right and aren't: an images list beside input, which it ignores, and a data:image/...;base64, string, which it embeds as text. Both return a vector that has nothing to do with the picture. Embed also sends the model's full context as num_ctx on every call, because Ollama may load an embedding model with less and cuts a longer input without an error.
Four more methods sit outside the interface, for the model ops and the capability checks. Unload drops a model from Ollama's memory with a POST /api/generate that sets keep_alive: 0, and Pulled reads GET /api/tags with each model's size on disk. Details and Capabilities come below.
For images, Message gains Images, the raw bytes of each picture: on the user message for an attached image, and on the tool message for a picture view_image opened. OllamaEngine sends them as the message's images array in /api/chat, which Ollama documents as base64 strings; Go's encoding/json writes a []byte that way with no code of ours. Only a model with the vision capability can read them, and Ollama's POST /api/show lists a model's capabilities, such as ["completion", "vision", "tools", "thinking"]. OllamaEngine.Details asks it for the capabilities, the size in parameters, the quantization and the context length, and keeps each model's answer for the life of the engine; a failed call keeps nothing. Capabilities reads the list through Details, and Pulled reads GET /api/tags, the models Ollama has on disk. These sit outside the interface, which keeps its four methods: merud hands the agent a check built on Capabilities for image turns and another for whether the answer model can take tools; about_meru and the models in Settings need Details, and only the models in Settings need Pulled. The "ollama http" debug line counts a request's images; no log line or span holds their bytes.
Speech to text doesn't go through the interface: it runs in whisper.cpp's server, not in Ollama, and internal/speech talks to it (see Speech to text).
An answer model can run on a model server other than the local Ollama: Ollama's own OpenAI-style API, vLLM, llama.cpp's server or LM Studio, on this machine or on a GPU box on your own network or private cloud network. Meru calls such a server near-edge. No endpoint sits on the internet. A [[endpoints]] entry names it, and [models] main, [models] large or a model set's main refers to it as @name:
[models]
main = "@lab"
[[endpoints]]
name = "lab"
reach = "near-edge" # "local" or "near-edge"
url = "http://10.0.0.5:8000/v1"
model = "qwen3.6:35b-a3b-mxfp8" # the name the server knows
context_length = 32768
vision = true
api_key = "secret:lab_key" # optional; never the key itself
@name for fast and embed, so routing, skill picks, summaries, indexing and search never leave the machine.reach says how far requests may travel, and merud checks the address it connects to, not the name in the URL. No engine follows a redirect. local is loopback only, checked at load and when the engine starts. near-edge is your own network: each address the client connects to must be loopback, private (10/8, 172.16/12, 192.168/16, fc00::/7), link-local, or in 100.64.0.0/10, the range mesh networks hand out; loopback.NearEdge holds the rule and a dialer hook applies it after the name resolves, and an IP address in the URL is checked at load too. The client ignores proxy settings, since a proxy would make the connection elsewhere. Config refuses any other reach, so no setting sends a prompt to the internet.near-edge asks before it builds its prompt: "Send this question to @lab?", with what the turn carries (the question, the earlier turns, any pictures, the profile and memories, file excerpts, and the results of any tools it runs), and three answers: This time, This chat or No. The question travels on the approval channel with Approval.Kind = "consent" and an Approval.Consent that names the endpoint, its reach, its model and the list. "This chat" lasts until merud stops; nothing writes it to disk, and no answer means "always". A no, an answer the question didn't offer, an incognito chat, a scheduled job, or a client that can't ask (meru run --json, meru with no terminal) keeps the turn here: the fast model answers, with a notice that says why. A consent line in the transcript records the endpoint, its reach and the answer, never the prompt. Every step of a turn reads the model the turn picked when it started, so a model switch mid-turn doesn't split it.done event of an answer from an endpoint off the machine carries answered_by and reach; Meru.app's footer and side panel, meru chat's stats line and meru's stderr name it.OpenAIEngine sends POST <url>/chat/completions. It reads a stream of server-sent events, joins a tool call's arguments as they arrive in pieces, hands the calls out on the last Delta as Ollama does, and leaves the model's reasoning out of the answer. It doesn't embed (ErrNoEmbed) or report token probabilities (ErrNoLogProbs). It maps the stop reasons to Meru's, so an answer cut at its token cap ends length.context_length, vision and tools, and Engines.Details returns them where OllamaEngine would ask /api/show. The window, the vision check and the tools check then treat an endpoint like a local model. Pulled lists each endpoint as @name, so a model set may name one.merud reads api_key from secrets.toml when it starts and sends it in the API's own header. An entry whose secret is missing leaves merud running; a question for that model fails with a fixed sentence that says to add the api_key entry to secrets.toml. Nothing read from api_key, not even the entry's name, goes into a log line or an error.Two engines may come later, behind the same interface:
LlamaCppEngine would compile llama.cpp into merud through cgo, using the GPU (Metal on a Mac, CUDA on NVIDIA). Meru would then need no Ollama install, but it would have to parse each model's tool-call format itself.MLXEngine, if MLX gets usable C or Go bindings and runs enough faster than llama.cpp to justify a second backend.Meru keeps two kinds of data, with one rule between them: files hold the truth, and the database indexes them. The database is a projection, a copy arranged for fast lookup and built from other data. Delete meru.db and merud rebuilds it. If the index breaks, you re-index and lose no history.
Each session is one JSON Lines (JSONL) file: one JSON object per line, one line per event. merud appends a line as each event happens and never rewrites old ones. Deleting a chat removes its whole file (see Organizing past chats).
~/.meru/sessions/2026/09/2026-09-23T101502-7f3a.jsonl
One question about email takes four lines on disk, and a fifth closes the session:
{"ts":"2026-09-23T10:15:02Z","type":"user","text":"what did we agree on the launch date in email this week?","trace_id":"4bf9…"}
{"ts":"2026-09-23T10:15:03Z","type":"tool_call","call_id":"call-1","kind":"mcp","server":"google","tool":"search_gmail_messages","args":{"query":"launch date"},"trace_id":"4bf9…"}
{"ts":"2026-09-23T10:15:04Z","type":"tool_result","call_id":"call-1","outcome":"ok","ok":true,"ms":812,"result":"Re: Launch date, from Sam…","trace_id":"4bf9…"}
{"ts":"2026-09-23T10:15:09Z","type":"assistant","text":"Sam and Priya agreed on 14 October…","tokens_in":2310,"tokens_out":188,"trace_id":"4bf9…"}
{"ts":"2026-09-23T10:31:40Z","type":"summary","text":"Found the launch date agreed in email: 14 October, in the thread with Sam."}
The file records the whole exchange. The question arrived at 10:15:02. A second later the model asked the google server for search_gmail_messages with the query "launch date", and the server answered in 812 ms with the thread "Re: Launch date" from Sam. The answer landed at 10:15:09 and named 14 October, after the model read 2,310 tokens and wrote 188. The first four lines carry the same trace_id, which links them to the timing data covered later. The session ended at 10:31, and merud asked the fast model for the one-sentence summary on the last line. The indexer embeds that summary, so a later question such as "what date did we pick for the launch?" can find this session.
{"ts":"2026-09-27T09:14:02Z","type":"model_switch","tier":"main","from":"qwen3.6:35b-a3b-mxfp8","to":"gemma4:26b-mxfp8"}
A model_switch line comes before the first answer a new main model writes in a session, so the transcript alone says which model wrote each answer. An assistant line also carries ttft_ms, eval_ms, bad_calls and capped (see Model sets).
{"ts":"2026-09-27T09:20:11Z","type":"meta","folder":"Garden","tags":["bulbs","autumn"]}
A meta line holds the chat's folder and tags as the user set them last. Each one holds the whole state, so the newest wins, and one with no folder or no tags means the chat has none.
A tool_call line gets "caller":"meru" when merud made the call itself before the model's first round (see Web first); a call the model asked for has no caller. An assistant line whose turn read the web gets a web field: up to five notes, each a URL, a title and a gist of at most 300 characters, pages before search results, 1,500 characters in all. History hands them to the model after the answer, under a line that marks them as Meru's, one line each:
(Meru's notes on the pages this turn read, for later questions. They aren't part of the answer above; never copy them into an answer, and cite pages by number as usual.)
- Acme Flow https://acme.example/flow — Acme Flow moves notes between apps.
The line above the notes says who wrote them and that they aren't for the user. When the notes were bare [from the web: …] lines, a model answering a follow-up copied them, run together, onto the end of its answer.
The answers of the last two turns then get tool notes: one line per tool call the turn made, in the order the calls ran, with the tool, its arguments cut to 160 characters, how it ended and the first 300 characters of its result. A turn gets at most 6 lines and 1,200 characters; calls past that go on one last line by name and count. History builds the notes from the turn's tool_call and tool_result lines, pairing them by call_id, so nothing new is stored and an incognito chat reads them from memory. A web tool's line names the tool and how it ended, since the web notes hold what it found; a call merud made itself before the first round is left out. Lines that start "Cite " come out of the result, since the next turn numbers its sources afresh. A line that starts "Saved at ", which Meru adds when it saves a file for a call, such as a mail attachment, moves to the front of the excerpt, so the 300-character cut keeps the path:
(Meru's record of the tools this turn ran, for later questions. It isn't part of the answer above; never copy it into an answer. Use it to say how you got that answer; run a tool again for anything it leaves out.)
- analyze_table {"path":"~/trip.csv","aggregate":[{"fn":"sum","column":"Amount"}]} ok: Matched 3 of 6 rows in trip (rows 4 to 7). | sum(Amount) | | --- | | 1207.00 |
Before the notes, a model asked how it had added up a sheet listed six rows that don't exist, and asked which tools it had used, four steps that never ran.
Before the move, a model downloaded a family photo for a greeting card, and two turns later, asked to put the photo in, searched the user's folders for one and picked ID documents: the cut had kept the attachment's long ID and dropped its path.
A user line gets an images field, the full paths of the copies in the uploads folder, only when the question carried images; the bytes stay in the files. An assistant line gets an outcome field only when the turn ended without a full answer: timeout, cut_off, window_full, capped, gave_up, bad_output or no_vision (see Agent loop). It gets a notice field only when a check on the answer warned, such as a claimed action with no successful tool call, a link to a file that isn't there, a money amount the turn didn't read, or a file the answer says Meru made on a turn that wrote none (see Claims no tool backs).
A tool call's lines share a call_id, because the calls of one round run at the same time and their lines can interleave. An approval line sits between the two when the call asked you first. result holds the first 4,000 characters of what the tool returned, with secrets removed.
You can grep, tail -f or back up these files with no special tools, and a crash loses at most the line being written. The database keeps a copy for search and for meru log.
documents, chunks, chunk_fts, chunk_vec and meta, and v0.3 added tool_calls and turns; the rest arrive with later milestones, as the table below marks. Edit a memory file by hand and the indexer picks up the change the same way it does for your notes.~/.meru/meru.db is one SQLite file, opened through ncruces/go-sqlite3. FTS5, SQLite's built-in full-text search, handles keywords. Vectors sit in plain tables, one row per vector, and vec1, SQLite's own vector extension, supplies the distance function that compares them. merud creates meru.db and its -wal and -shm files with mode 0600, so only you can read them.
| Table | Holds | Rebuilt from |
|---|---|---|
documents | indexed source files: path, mtime, hash, type | your folders |
chunks | pieces of each file's text, plus metadata and the parent document | your folders |
chunk_vec | one vector per chunk, a blob of 32-bit floats scaled to length 1 | chunks, re-embedded |
chunk_fts | keyword index over chunks (FTS5) | chunks |
sessions / messages (v0.4) | every session and message, plus each session's summary and tags, for context and meru log | sessions/*.jsonl |
session_vec (v0.4) | one vector per session summary, for "what did we decide last week" | session summaries |
message_fts (v0.4) | keyword index over messages, for "what did we say about X" | messages |
turns | one row per answered question: session, start time, source, route, tokens in and out, duration, tool calls, the files its prompt read, trace ID, and the answer model with its time to first token, writing time, bad calls and whether the turn hit the cap. meru usage and the chat's usage numbers count it | sessions/*.jsonl (the assistant line holds route, duration, files and the model's numbers; the model_switch lines name the model) |
tool_calls | audit log: every MCP, A2A, built-in and local command call, with its call ID, session, kind (mcp, a2a, builtin or command), server, tool, args, result (first 4,000 characters), outcome, approval choice, duration, trace ID and caller (meru for a call merud made itself); the rows of an incognito or deleted chat keep no args or result | sessions/*.jsonl; the rows of an incognito or deleted chat have no file and don't come back |
memories (v0.4) | one row per memory file: its ID (<kind>/<name>.md), kind, text, created, source, mtime and content hash | memory/*/*.md |
memory_vec / memory_fts (v0.4) | vector and keyword indexes over memories | memories |
turns.job (v0.5) | which job a run belongs to, for each job's last run | the run's transcript: its user line names the job; the jobs themselves are [[jobs]] in config.toml and stay out of the database |
meta | schema version, embedding model name, vector size and task-prefix fingerprint | config |
v0.2 built documents, chunks, chunk_vec, chunk_fts and meta, and v0.3 added tool_calls. Each other table arrives with the milestone marked beside it. Replaying transcripts into messages and message_fts waits for v0.4, where session summaries need it; until then the JSONL files are the only copy of a conversation.
tool_calls is mandatory. An assistant with tools that change things needs a record you can read afterwards. dispatch writes a row as each call ends, and meru log reads the newest rows. When merud starts and finds the table empty, it rebuilds the table from the transcripts, pairing each call's lines by call_id; a call with no tool_result line, because merud stopped mid-call, gets the outcome cancelled. messages and tool_calls store the trace ID of their turn, so you can jump from a slow trace in your OTLP backend to the rows it produced, and back.
When the embedding model's name, its task-prefix fingerprint or the vector size Ollama reports no longer matches meta, the store deletes every row of chunk_vec, memory_vec and session_vec and keeps documents, chunks, memories and sessions. A database from an older release may have no prefix fingerprint. When its model and vector size match, the store records the current fingerprint and keeps these vectors. Keyword search keeps working while the indexer re-embeds after a later model or prefix change. The store reports the gap by counting chunks that lack a vector (NeedsReembed), so the count stays right if merud stops halfway through. The memory syncer re-embeds each memory that lacks a vector, and the summarizer does the same for each summary.
ncruces/go-sqlite3 with vec1 and FTS5. No cgo, no C compiler, and vectors live in the same file as everything else. One query can join vector hits, keyword hits and document metadata. vec1 ships with the driver, so Meru adds no extension of its own.chunk_vec and orders by vec1_l2_distance(vector, ?) / 2. The store keeps every vector at length 1, and for such vectors half the squared straight-line distance equals the cosine distance that embedding models are trained for. vec1 also offers an exact "flat" index, but writes slowed as it grew: replacing one 100-chunk file took 186 ms at 10,000 chunks, and indexing 100,000 chunks would take about ten minutes. Plain rows index 100,000 chunks in 6.1 s.| Operation | 10,000 chunks | 100,000 chunks |
|---|---|---|
| index every chunk | 0.59 s | 6.1 s |
| replace one file | 6.4 ms | 6.1 ms |
| vector search, top 50 | 13 ms | 147 ms |
| keyword search, top 50 | 9 ms | 90 ms |
meru.retrieval.duration will show when search needs to get faster. The first fixes are fewer dimensions, or computing distances in Go, not another database.sqlite-vec, because its Go bindings work only with the 2024 release of the driver (v0.17.1), 18 releases behind and without the security fixes since, and the driver already bundles vec1, which supplies the distance function the store needs. Also chromem-go (pure Go, but a second store we can't join with keyword search), LanceDB and DuckDB (both need cgo and do more than we need), Qdrant and Chroma (extra server processes).The indexer reads the folders you name into the store, keeps them current while merud runs, and reads nothing else on disk.
Only the folders under [index] folders in config.toml. The list ships empty, so a fresh Meru indexes nothing, and it reads your home folder only if you list ~. merud reads the list when it starts, so a hand edit to config.toml takes a restart. Adding or removing a folder in meru chat or the desktop app takes effect at once: merud writes the list, hands the indexer the new folders and restarts the watcher with a scan.
[index]
folders = ["~/notes", "~/Documents/papers"]
ignore = ["*.log", "drafts/"] # .gitignore-style, on top of the built-in list
max_file_mb = 5
chunk_tokens = 500
overlap_tokens = 50
watch = true
images = true # PNG, JPEG, GIF and WebP files too
Inside those folders the indexer checks each entry against these rules, in order, and skips it at the first one that matches:
| Order | Skipped as | What it catches |
|---|---|---|
| 1 | symlink | any symbolic link; the indexer never follows one |
| 2 | secret | .env*, *.pem, *.key, id_rsa*, *.kdbx, credentials*, .netrc and similar |
| 3 | hidden | a name that starts with . |
| 4 | build-folder | node_modules, .venv, venv, vendor, target, dist, build, __pycache__ |
| 5 | ignored | [index] ignore, then each folder's .gitignore and .meruignore, from the top folder down |
| 6 | media, binary, unsupported | by extension: audio, video, archives, programs, databases, HEIC and other images Ollama can't embed, any image when [index] images is off, and any type with no chunker, such as the old Office formats .doc and .xls |
| 7 | too-large | over max_file_mb, or over 20 MiB for an image |
| 8 | binary | a NUL byte in the first 8 KB (PDFs, images, and Word and Excel files excepted) |
.gitignore or .meruignore line can bring one back, because a key in the index would end up in a prompt.merud -v logs each skipped path with its reason.A .meruignore uses .gitignore syntax: one pattern per line, # for a comment, * for any run of characters within a name, **/ for any number of folders, a trailing / for folders only, a / at the start to anchor the pattern to the file's own folder, and ! to re-include. Git's rule holds across the ignore files: the last matching line wins, and a deeper folder's file beats a shallower one's. Meru reads .meruignore after .gitignore in the same folder, so it can skip more for Meru alone, or bring back with !name a file git ignores.
Images. With [index] images = true, the default, and an embedding model that takes images (embeddinggemma-2:440m does; config.EmbedModels marks it), the indexer reads PNG, JPEG, GIF and WebP files too. It checks the first bytes really are an image, sends the whole file to Ollama as {"image": base64}, and stores one document of kind image with one chunk and one vector, in the same tables as text. The chunk's text, such as "Image shot.png in /Users/you/Documents/img", names the file and its full folder path, and lets keyword search find a picture by its name; its vector, from the picture itself, lets a question find it by what it shows. Ollama scales every image to the same 268 tokens, so Meru sends the file as it is. HEIC, which iPhone photos and some Mac screenshots use, stays out: Ollama refuses it and Go can't decode it. The file tools (read_file, grep and the rest) still see an image as media, since they read text.
Word, Excel and delimited text. The indexer reads .docx, .xlsx, and .csv, .tsv and .tab files with readers of its own, built on the standard library. A Word or Excel file is a ZIP archive of XML parts; the reader keeps the parts in memory, reads each through a cap (64 MiB a part, 256 MiB a file, 10,000 entries), reads the XML one token at a time, and turns a parser panic into an error. A sheet stops at 100,000 rows or 1,024 columns, and a file at 2,000,000 cells. A cell formatted as a date reads as 2026-05-03, and a formula as the value Excel saved with it; Meru never evaluates one. A delimited file's delimiter, a comma, semicolon, tab or pipe, is the one that splits its first 20 lines into the same number of fields; a file that isn't UTF-8 reads as Windows-1252. A password-protected file, and the old .doc and .xls formats, stay out. A .txt file stays plain text. docs/design/word-excel-csv.md explains the feature end to end.
The indexer cuts each file into chunks along its own structure:
| File | Split by | Heading kept | Citation points to |
|---|---|---|---|
| Markdown | heading, then paragraphs | the heading path, such as Garden > Spring | lines |
| Go | top-level declaration, read with Go's own parser | the declaration's name | lines |
| other code, plain text | blank-line blocks | none | lines |
| HTML | <h1> to <h6>, then paragraphs; scripts, styles and <head> dropped | the heading path | none |
| page, then paragraphs; plain text, no layout | none | page | |
Word (.docx) | as Markdown: heading, then paragraphs; a table becomes one line per row, cells joined by | | the heading path | the heading |
| Excel sheet, CSV, TSV | rows, each labelled with its number and its column names, under a line that names the sheet, the file's path and its columns; the first 10,000 rows of a sheet | the sheet's name, or the file's name without its extension | rows |
| Image (PNG, JPEG, GIF, WebP) | not split: one chunk whose text names the file and its folder | the file name | the file |
chunk_tokens (500) tokens and repeats the last overlap_tokens (50) of the chunk before it, so a sentence cut at a boundary still appears whole in one chunk. Meru estimates a token as four characters, because Ollama doesn't expose the embedding model's tokenizer.Row 12: Date 2026-05-03; City Amsterdam; Amount EUR 64.50, so keyword and vector search both match "food tour in Amsterdam" to the row. Its first line names the sheet and the file's full path, as an image's chunk names its folder: a CSV of daily GitHub stars holds only dates and numbers, and only its path tied it to "the AI registry's star history". The header is the first of the top 20 rows whose cells span at least half the sheet and are mostly not numbers.title: Garden > Spring | text: … for embeddinggemma-2, so the third chunk of a long section still embeds as being about the garden in spring. A query takes the model's query prefix (see The engine).merud scans every folder and compares each file's mtime and SHA-256 hash with the store's copy. It re-chunks and re-embeds a file only when either differs. It hashes every file, because some sync tools and editors keep the mtime when the content changes.~/notes-old out of [index] folders and restart merud, or remove it in the desktop app's Settings, which rescans at once, and search stops finding its files. The test works on whole folder names, so ~/notes keeps nothing from ~/notes-old. An empty list empties the index.watch = true, merud asks the operating system to report changes in every folder the skip rules keep. It indexes a changed path once the path has been quiet for 500 ms, so an editor can finish a save that takes several writes. When the operating system refuses another watch (Linux's fs.inotify.max_user_watches, or the open-file limit on macOS), merud logs one warning and keeps the watches it has; the next startup scan catches the rest.meru index rescans every configured folder, meru index <path> rescans one folder or file inside them, and meru index -status prints counts.meru.db. Answers see today's inbox, and your mail never lands in the index.Retrieval-augmented generation (RAG) means searching your files first and handing the model what it found, so it answers from your notes instead of from memory. The search has to find the right passages, and each of the two usual methods misses a kind of question:
Meru runs both. Figure 2 in A question, end to end shows where the search sits in a turn: after the router picks a route that includes your files, and before merud builds the context.
Before any search, the indexer splits files into chunks, pieces cut along the file's own structure: Markdown by heading, code by declaration or blank-line block, PDFs by page as plain text with no layout. Getting your content in shows how.
With [index] retrieval = "auto", the default, a search runs before the answer on the search, tools and search+tools routes. tools searches because the router sends some questions about your files there. It also runs on a direct question that names an indexed folder or asks about past chats (see Routing). Its query is the question, with an earlier question appended on a follow-up. A turn searches file chunks, memories and past sessions. Each source runs its own searches: memories add a list ranked by recency, and past sessions search their summaries by meaning and by keyword and their messages by keyword. rrf merges the lists within each source, and each source has its own share of the context budget, so one busy source can't crowd out the others. SQLite does both searches; our code merges the results:
| Piece | Comes from |
|---|---|
| Keyword search, ranked by BM25 | FTS5 (ORDER BY rank, where rank is BM25) |
| Similarity search, ranked by distance | every row of chunk_vec, with vec1's distance function (ORDER BY vec1_l2_distance(vector, ?) / 2 LIMIT ?) |
| Merging the two lists | our Go code: reciprocal-rank fusion |
merud.The keyword query drops filler words such as "what" and "it", unless nothing else is left, then quotes each remaining word and joins them with OR, so text from the user can never reach FTS5 as query syntax. It keeps the first 32 distinct words, which is why the new question comes before the previous one.
The index holds images beside text (see What gets indexed), and embeddinggemma-2 puts both in one vector space, so a file search can find a picture by what it shows. It keeps at most two images among its ten results: an image's chunk text is only its name, and the answer model can't see the picture, so more would crowd out text it can use. Each image result's citation carries kind: "image" and reads [1] ~/Documents/img/shot.png (image).
retrieve.SearchImages searches images alone, for search_images and for a question with an attached image. Both store queries join documents and keep kind = 'image', in one query each:
taxi.png or a folder such as nyc-trip, which match the words of a question about a different picture from the same trip. On the owner's 25 test images, equal weight put the right image first for 19 of 75 questions, and a quarter weight for 27.Looking at one. A found image's text is only its name, so to read a receipt or a ticket the model calls view_image (see Approving a tool call). dispatch.Result carries the picture in Images, beside Text. dispatch logs Text alone, so the picture never reaches the transcript or meru.db, and the agent puts Images on the tool's message, where Ollama shows it to the model on its next round. The agent offers view_image only while the main model lists vision, and then the system prompt says so in one line, pictureNote: asked to itemize receipts it had listed a turn before, a model with the tool called nothing and said it couldn't read images, as an earlier answer in the chat had claimed. A model without vision never sees the tool or the line. When such a model's full answer cites an image or names a file ending in .png, .jpg, .jpeg, .gif or .webp, a notice under the answer says "<model> reads text only, so it can't look at these pictures", with the suggestion from Questions with images.
The desktop app shows an image source as a 40-pixel preview on its chip. The Bridge makes it, and only for an image merud cited in an answer or in a past chat the app opened, so the page can't ask it to read a file of its own choosing.
BM25 scores and vector distances use different scales, so adding them would let one list drown the other. Reciprocal-rank fusion (RRF) ignores the scores and uses each chunk's position in each list:
score(chunk) = Σ over lists 1 / (60 + rank of chunk in that list)
A chunk near the top of either list scores well, and one near the top of both scores best. The constant 60 is the usual choice; it keeps the gap between rank 1 and rank 2 small. Three chunks, worked through:
| Chunk | Vector rank | Keyword rank | Sum | Score |
|---|---|---|---|---|
| A | 1 | 3 | 1/61 + 1/63 | 0.03227 |
| B | 2 | 2 | 1/62 + 1/62 | 0.03226 |
| C | — | 1 | 1/61 | 0.01639 |
C tops the keyword list but appears in only one list, so it scores about half of what A and B score. A and B land within 0.00001 of each other: with k = 60, first place beats second by about 1.6%, so agreement between the lists decides the order more than any single rank does.
// rrf merges ranked lists of chunk IDs into one score per chunk.
func rrf(lists ...[]int64) map[int64]float64 {
const k = 60
scores := map[int64]float64{}
for _, list := range lists {
for rank, id := range list {
scores[id] += 1.0 / float64(k+rank+1)
}
}
return scores
}
Go's range counts from 0, which is why the code adds rank+1. SQLite could do the merge in one query with window functions and a full outer join. We merge in Go instead:
rrf is a pure function, so a table-driven test covers it without a database.meru.retrieval.duration (vector, fts, fusion).rrf with a third list ranked by recency.The extra query costs microseconds, because SQLite runs inside merud.
Schema detail. chunk_fts is an FTS5 external content table (content='chunks'). It indexes the text in chunks without storing a second copy, and its rowid equals the chunk ID. chunk_vec uses the same chunk ID as its key, so both lists name chunks the same way and the merge needs no lookup.
The list sizes are fixed constants in internal/retrieve: 50 hits from each search and 10 chunks after the merge. They aren't config keys. We'll tune them once we have measurements from real questions.
A coding agent finds code with ls, grep and a file reader, and no search before the answer. Meru can work that way too. The search_files built-in tool runs the same hybrid search for a query the model writes, and returns numbered excerpts, so search by meaning becomes one tool next to grep, list_folder and read_file. [index] retrieval picks who decides when to search:
[index]
retrieval = "auto" # the default; or "agentic"
auto | agentic | |
|---|---|---|
| Search before the answer | yes, on turns about your files (see below) | no |
| Earlier conversations in the prompt | yes | no |
| Profile and recalled memories | yes | yes |
| File tools offered | read_file, list_folder, grep and search_files, and search_images and view_image while images and vision allow them, on the routes that offer tools | the same |
| Note in the prompt, on turns about your files | the excerpts, with the rule on citing, and "read, list, grep or search again when the excerpts fall short" | "look first with search_files or grep, then read_file, stop after two or three rounds, cite the excerpts" |
agentic needs search_files in [builtin] tools; merud refuses to start without it. A built-in skill, file-research, carries the same advice for the fast model to pick. In both modes a search_files excerpt numbers on from the turn's other excerpts and joins the sources event (see Citations).
We measured both modes with meru check on the owner's 19 questions and real folders: 5,600 files, on the lite profile (MiniCPM5 2B), three runs of each, from the same copy of meru.db.
| Category (questions) | auto passed | agentic passed | auto median s | agentic median s |
|---|---|---|---|---|
| direct (3) | 9/9 | 9/9 | 1.5 | 1.8 |
| files: list, grep, read (3) | 9/9 | 9/9 | 8.3 | 5.6 |
| retrieval: by meaning (3) | 9/9 | 9/9 | 8.0 | 8.7 |
| web (2) | 5/6 | 2/6 | 24.0 | 18.1 |
| mcp (2) | 5/6 | 6/6 | 15.0 | 7.4 |
| command (1) | 3/3 | 3/3 | 25.5 | 19.0 |
| profile (1) | 3/3 | 3/3 | 11.5 | 1.3 |
| session: two turns (2) | 5/6 | 0/6 | 30.1 | 42.0 |
| datetime (2) | 6/6 | 6/6 | 4.9 | 5.2 |
| all (19) | 54/57 | 47/57 | 10.8 | 7.0 |
A whole run of the 19 questions took 292 s of turn time with auto and 271 s with agentic, on average.
What the numbers say:
search_files once and answered.agentic lost where the answer takes several steps. "So when did I visit Lisbon?" failed all three agentic runs. The answer sits in travel PDFs. The up-front search put them in the prompt, and auto answered in one round. With the tools, the 2B model kept searching and reading. Twice it ended its turn by writing a tool call as plain text, and once it never called search_files and grepped instead. The next question in that session read the broken turn in its history and failed too.agentic was faster on turns that don't need your files. "Which Obsidian vaults do I have?" took 1.2 s against 14 s, and "what is my name?" 1.3 s against 11.5 s. With no excerpts, the prompt stays the same from turn to turn, and Ollama reuses its work on it. The up-front excerpts change with each question, so auto reprocesses everything after them.agentic cost more prompt tokens on file questions, 1.2 to 3 times as many, because each tool round sends the prompt again.So auto stays the default. It already holds both approaches: the excerpts in the prompt, and search_files for a second look. We didn't measure the full profile: the test machine was already 16 GB into swap, and a 23 GB model would have measured the disk. A larger model may follow the explore loop better; rerun meru check with each setting before changing the default for full.
Dropping the vector index would take more than this mode. Recalled memories, earlier conversations and search_files itself all search it, and so do the v0.4 "Done when" tests for recall. The numbers give no reason to drop it: the one tool that searched by meaning was the one that answered the questions agentic passed.
Two changes in auto mode followed from these numbers. agentic won its time on turns that need no files, and the web questions pointed at the note on the file tools.
tools turn skips the search when the question points at a connected tool. The signs that add tools to a route decide it (see Routing): the question names a tool server, says "remember", asks for the web, gives a URL, or names what a server's tools act on. It skips it too when a picked skill brings web_search and no file tool, as web-research does: "can you search for things from the last 2 days", a follow-up in a chat about a rocket launch, named no web phrase, and the turn put nine unrelated excerpts and 43,000 tokens in the prompt (#174). search and search+tools always search: the router, or the folder rule, saw files in the question. The turn still offers the file tools, so the model can look when it has to. Before this, "search the web for the latest Go release" put ten excerpts from your folders in the prompt, and since web_search numbered its results from [1] too, the Sources list under the answer could name one of your files. Web results now take the numbers after the turn's excerpts (see Citations).We measured both with meru check on a made-up setup, so that no personal data entered the test: eight Markdown notes in one folder, the test MCP server (cmd/fakemcp) connected as almanac, and 18 questions shaped like the owner's. lite profile, auto mode, three runs before the change and three after, each from an empty meru.db.
| Category (questions) | Before passed | After passed | Before mean s | After mean s | File sources per turn, before → after |
|---|---|---|---|---|---|
| direct (3) | 9/9 | 9/9 | 1.6 | 1.3 | 0 → 0 |
| files: list, grep, read (3) | 9/9 | 9/9 | 3.2 | 3.1 | 8 → 8 |
| retrieval: by meaning (3) | 9/9 | 9/9 | 3.6 | 3.2 | 8 → 8 |
| web (2) | 2/6 | 5/6 | 11.6 | 9.3 | 8 → 0 |
mcp: almanac by name (2) | 6/6 | 6/6 | 4.5 | 1.5 | 8 → 0 |
| memory: "remember that…" (1) | 2/3 | 1/3 | 3.7 | 3.7 | 8 → 8 |
| session: two turns (2) | 6/6 | 5/6 | 6.6 | 4.6 | 8 → 6.7 |
| datetime (2) | 6/6 | 6/6 | 6.7 | 6.2 | 4 → 4 |
| all (18) | 49/54 | 50/54 |
A run's turn time fell from 87 s to 70 s. The eight folder files make every search return all of them, so "file sources" counts eight wherever a search ran. What the numbers say:
almanac questions fell from 4.5 s to 1.5 s, and every web and almanac turn went from eight file sources to none.[1] and gave no link. After, all three gave the link.search+tools in every run, which the rule leaves alone; in the failing runs, after the first run had saved the fact, the model answered that it already knew. The failed session turn routed direct, which the change doesn't touch either.merud numbers the chunks it found and puts them in the prompt under "From your files", with a rule that tells the model to cite each excerpt it uses as [1], [2] and so on, and never to invent one. When a search finds nothing, the prompt says so instead, and the model answers without citing files.
The system prompt names the folders in [index] folders on every turn and says that Meru searches them before it answers. The note that the model may read, list, grep and search the folders itself joins only turns about your files. With no folders set, it tells the model that Meru hasn't indexed anything yet and where you add folders. Without this note a small model answers "I don't have access to your files" while it reads excerpts from them, and can't say what Meru indexes.
Before the first token, merud sends the client a sources event that lists each excerpt with its number, path (as ~/…), heading, and line range, PDF page or rows. Rows of a sheet have kind = "table", so a client prints "rows 12–41". When search_files returns excerpts later in the turn, they take the next numbers, ride on the call's tool_result event, and merud sends a new sources event that holds every source so far. Clients keep the last one. web_search and web_fetch do the same: each result, and each page read, takes the next number and joins the list as a web source, with kind = "web", its URL in url and in path, and its title as the heading. A number names one thing across the turn, a file excerpt or a page, never both. Meru.app shows a web source as a chip with a globe and the site's name that opens the page; meru and meru chat print its title and URL as a link. A chip for rows of a workbook names the sheet too, as budget.xlsx · Invoices. A reopened chat lists only the files its turns read, since the transcript keeps the web results as notes, not as numbered sources. Once the answer ends, one-shot meru prints a Sources: list and meru chat shows the same list under the answer. Both list only the sources the answer cites, and an answer that cites none gets no list: the model decides when a source matters. An earlier rule listed every excerpt when the answer cited none, in case a small model forgot to cite; in use it printed ten unrelated files under general answers and under an answer built from an Obsidian search.
The garden project sows tomatoes on 12 April [1].
Sources:
[1] ~/notes/garden.md, "Planting", lines 3–5
With a tiny index, every chunk lands in the top 10. A minimum fused score, or keeping fewer than 10 chunks, would shorten the prompt; choosing either waits for measurements (see Open questions).
Meru remembers facts about you between sessions: your job, how you like answers written, which projects are due. Each memory is a small Markdown file you can read, edit or delete by hand. The files hold the truth, as principle 2 requires. The database indexes them so Meru can search them, and rebuilds from them if you delete it.
Meru writes one file per memory and keeps one folder per kind:
~/.meru/memory/
me/ who you are: role, family, where you live
preferences/ how you like things done
projects/ ongoing work, goals, deadlines
people/ people you mention and how they relate to you
reference/ where things live: accounts, URLs, tools
other/ anything worth keeping that fits no folder above
Each file opens with YAML frontmatter, a block of key: value lines between --- markers, and holds one fact below it:
---
created: 2026-09-23
source: session 2026-09-23T101502-7f3a
---
Prefers short replies, with the answer in the first sentence.
kind: field that could disagree with its path, and you can browse by kind in a file manager or with ls.meru memory forget does it.other/ holds anything that fits no other folder. If it fills up with one kind of thing, create a new folder for that kind; Meru picks it up with no code change. A kind's folder name uses letters, digits, - and _; Meru skips any other folder. merud creates the six default folders when it opens the memory folder.source above names the session transcript shown in Storage, so you can open it and read the exchange that produced the fact.~/.meru/memory/.Meru keeps no index file. The database already indexes the folders and meru memory list shows them, so a second list on disk would only drift out of step with the files.
merud asks the fast model for a one- or two-sentence summary and appends it to the transcript as a summary line. The indexer embeds those summaries, so "what did we decide about the garden beds last week?" finds the right session. On the routes that search files, the prompt gets up to three past sessions under "From earlier conversations", each with its date, summary and best-matching message. Its header tells the model these are its own past chats with you, only the best matches, and never to say it has no access to past chats.read_file, list_folder and grep also read ~/.meru/sessions, one JSONL file per chat, and a line in the system prompt says so, while the file tools are on. The line also shows a meta line, which holds a chat's folder and tags, and how to grep for a tag, and tells the model to search itself rather than offer to: without it, the model said it had no way to find chats by tag. The indexer skips .jsonl files, and the file tools read them in that folder alone: a JSON Lines file in an [index] folder stays out of search and out of the tools. grep with no path leaves the chats out, since a chat holds the start of each file its tools read; the model passes the sessions folder as the path. The indexer never indexes the transcripts: search and recall keep to the summaries and messages in meru.db. A direct question that names a chat or conversation with a word that points back in time, such as "previous" or "last", or a tag or folder, or says "we talked" or "we discussed", moves to the search route, which offers the file tools and the recalled sessions.~/.meru/memory/ in step with the store: each file becomes one row with one vector, from its first 4 KiB, and a keyword entry, with no chunking. It picks up hand edits through the same mtime and content-hash check it runs on your notes.rrf. The top results go into the context, up to the memory budget. Recall runs on every route, including turns that only call tools, because a preference such as "always ask before sending mail" has to reach the model on the turns that send mail. Before the answer, merud sends a memories event that lists what recall put in the prompt, so the desktop app can show each memory under Remembered, with a button that forgets it.remember tool with a folder and the text. The call goes through dispatch like any other tool, so it lands in tool_calls and the transcript. Memories save without asking in a chat that has read nothing from outside the machine. In a chat that read mail, a web page or another server's answer, remember asks first, so words in that content can't plant a memory that rides into every later chat (see Approving a tool call). Add remember to builtin.confirm in config.toml to approve each one.meru memory list | add | forget, and the desktop app's About you, work on the files through merud, which owns the memory folder.If Meru believes something wrong about you, you can find the file and fix or delete it. A vector blob you can't read would leave you no way to audit or correct it.
A skill is a markdown file of instructions for one kind of task, at ~/.meru/skills/<name>/SKILL.md. Like a memory file, it opens with YAML frontmatter:
---
name: meeting-notes
description: Turn a meeting transcript into decisions and action items. Use when
asked to write up a meeting, list what was agreed, or who owns what.
---
<the instructions, loaded only when the skill is chosen>
The system prompt carries only each skill's name and description. From v0.4, a short call to the fast model picks the skills a turn needs, and merud loads only their bodies, so each new skill adds two lines to the prompt until that call chooses it.
A skill may also list the tools its steps use, under allowed-tools, the key Claude's skills use, as in allowed-tools: web_search, web_fetch. When the pick chooses a skill, the turn gains the tools it names that config allows: a built-in tool in [builtin] tools (web_search also needs a SearXNG address), or an MCP or A2A tool on its allowlist. A skill never turns on a tool config keeps off, and every call still goes through dispatch. When config allows none of a skill's tools, the turn leaves that skill's instructions out: telling a model to search the web with no search tool made it call the one tool it had over and over. A name Meru doesn't know as a tool, such as Claude's Read, counts for nothing, so a skill copied from Claude doesn't lose its body. The key takes a comma list, a [...] list or a YAML list of - name lines.
The list of skills in every prompt says a skill is a set of instructions, not a tool. It names a skill only when the turn offers at least one of the tools its allowed-tools names, or when it names none, and gives each skill with tools a line such as "To use it, call web_search or web_fetch." that names the tools the turn offers. A picked skill whose tools the turn doesn't offer, as on the Just talk scope, leaves its instructions out too. In a real session the list named web-research on a direct turn that offered no web tool; the model called web-research as a tool, and then told the user it couldn't search the web. Since every route in Auto offers the same web tools, the list still stays the same from turn to turn there.
A model may still call a skill as a tool. Such a call goes to dispatch, which denies it as it denies any tool no backend offers, and the call counts in meru.model.malformed_calls. In place of the usual refusal the model reads a hint whenever config allows the skill's tools. When the round offers them, the hint is "web-research is a skill, not a tool. Call web_search or web_fetch.", and the model can call the tool in its next round. When config allows them but the round doesn't offer them, it says the skill works through those tools and that this answer doesn't offer them, so the model answers without them.
A skill's name is lowercase letters and digits in words joined by -, such as meeting-notes, and must match its folder's name. A SKILL.md may be up to 256 KiB. A skill that breaks a rule is skipped with a warning that says why, and the other skills still load.
Skills are plain files, so any other agent that reads this format can use the same directory.
To turn a skill off, name it in [skills] disabled:
[skills]
disabled = ["explainer"] # the default is [], every skill on
merud doesn't load a disabled skill, so the model never sees it. For a built-in skill, merud also doesn't install it: delete its folder and disable it, and it stays gone. A name that matches no skill isn't an error, since you may add that skill later; merud logs it at info and moves on. A skill folder you add loads with no change to config.
Meru ships with five skills. writing and explainer come from the owner's my-ai-assets repo; web-research, file-research and mail-research are Meru's own:
| Skill | What it does |
|---|---|
writing | Plain-English rules for any prose Meru writes: emails, summaries, reports |
explainer | Builds a self-contained HTML page that teaches a topic, with diagrams |
web-research | For how to use a program or command, and for questions that need current facts: search the user's own words first, with a name in double quotes; never swap in a product or company the model knows for the one named; search again when the results are about something else; read the one or two best pages with web_fetch and a prompt, prefer primary sources, check dates against today, quote versions from the page, cite URLs, and say when sources disagree. Brings web_search and web_fetch |
file-research | For questions about the user's own files and pictures, and not for how to use a program: search_files for a topic in any words, grep for an exact name or phrase, list_folder to see a folder, read_file for the whole text, search_images for pictures and view_image to look at one; try other words once, stop after two or three rounds, cite the numbered excerpts |
mail-research | For the user's email and calendar: receipts, bookings, orders, invoices, confirmations, appointments and replies. Write Gmail queries, such as after:2026/11/01, newer_than:30d, from:, has:attachment, filename:pdf and {receipt invoice folio}, never web operators such as site:; for last, latest or recent, start with newer_than:60d, newest first; search for what the email is (a receipt, a folio, an invoice, "your stay"), since the place name may be missing: a hotel near a city sits in another town; read the subject and sender of every result, and open a receipt's attachment, where the amounts often are; call get_events for an event's dates first; quote amounts, dates and names as written. Brings the google server's mail search and read tools, its attachment tool and get_events |
The fast model picks from the descriptions alone, so their words decide which skill loads. make pick-eval asks the pick 21 labelled questions three times each: how to use a program, current facts, the user's files, and plain chat. A pick counts as right when it names the wanted skill and no research skill the question doesn't want. On the lite fast model (MiniCPM5 2B), the old descriptions got 50 of 63 right and chose file-research three times for the btop question. Naming programs and commands in web-research, and ruling them out in file-research, got 52 of 63, with no stray file-research pick. A line in the pick prompt that said to choose file-research only for the user's own files did worse, 42 of 63: naming the skill drew the model to it.
mail-research added four mail questions, such as "what did the hotel charge me for my stay last week? check my email", for 29 questions and 87 picks. The pick got 9 of the 12 mail picks right, and 69 of 87 (79%) in all. On the 25 questions from before it got 60 of 75, the same as without it: “when is the next Ubuntu LTS release due?” stopped picking file-research, and “itemize the receipts in my trips folder” now picks mail-research too, which the eval counts as wrong.
The pick still missed trip questions: “what did I spend on my last trip to nyc” got no skill three times out of three, so the turn wrote Gmail queries that named the city and missed a receipt from a hotel just outside it. A question that trips the records rule (a word such as trip, hotel, receipt or spent, while a server is connected) now loads mail-research itself when the pick left it out and its mail tools are on. Like the rule it rides on, it is a word test with no model call.
embed package compiles files into the program, and the repo keeps them under internal/skills/builtin/. On first run, merud copies each one to ~/.meru/skills/<name>/ unless that folder already exists or [skills] disabled names it. It checks again on each start, so a built-in that a newer Meru adds, such as mail-research, lands on an existing install.merud never overwrites a skill you've edited, or one a newer Meru changed. To get the shipped version back, run meru skills reset <name>; a copy of web-research from before allowed-tools needs it to bring its tools, copies of web-research and file-research from before the sharper descriptions need it to get them, and a copy of web-research from before the rule on names needs it to get that rule.SKILL.md under ~/.meru/skills/ counts, whether you wrote it or copied it from elsewhere.[skills] disabled names the skills merud skips, built-in or yours (see Skills).write_file tool (v0.4) writes only inside ~/meru-output/ (configurable). It can't touch any other path, and it goes through dispatch like every tool. A path that already names the folder, such as ~/meru-output/uploads/page.html, its absolute form, or meru-output/uploads/page.html, means uploads/page.html: a model that read a file there passes its path back, and taken as relative it once wrote a second copy in ~/meru-output/meru-output/ while the user looked at the first. The result says whether it wrote a new file or replaced one, and gives a Markdown link with a file:// URL for the model to pass on, which both clients open with a click. Every turn's note on your folders also asks the model to give a file on this computer as such a link. Meru doesn't rely on the model to copy it: when an answer leaves out a file the turn saved, merud adds a line, "Saved: [report.html](file://…)", under the answer, and the transcript keeps it, so a later question sees the true path. A clicked file link to nothing says the file isn't on this computer.write_file saves an .html or .htm file, it reads each <img src="…"> and CSS url(…) that names a picture (.jpg, .jpeg, .png, .gif, .webp or .svg) inside the output folder, and puts the picture itself into the page as a data: URL, so the page shows it on its own, on a phone too. The path may be relative to the page, start with ~/, be absolute or be a file:// URL. A web address, a data: URL and a path outside the folder, or one that climbs out with .., stay as they are. merud reads each picture through the os.Root on the output folder, and reads a picture the page names twice only once. A picture over 16 MB stays out, and a page that its pictures would take past 40 MB fails the call, which then writes nothing. The result says "Put 2 pictures into the page, so it shows the pictures on its own, on a phone too:", names each with its size, and lists any it left out with the reason, such as no such file or outside the folder. edit_file does the same for the pictures an edit names, and edits a page up to 40 MB, where other files keep the 1 MiB limit. The tool's description tells the model that it can't make or edit a picture's pixels, and to use only pictures the user gave or named, never ID cards, certificates or other documents. A real chat showed the need: it downloaded a family photo for a greeting card, wrote a page with no picture in it, and said the photo was "embedded (base64)". A model writes text and has no way to write a photo's bytes; now it writes the photo's path and merud does the rest.full profile. The lite model can run them, but a 2B model writes weaker explainers and reads pages less well.We write the agent loop ourselves; we looked at Eino and ADK Go (Google's Agent Development Kit) and chose not to use a framework. The loop is small, and every rule Meru enforces lives inside it: the allowlist, the audit log, the context budget and confirmation prompts. We want that code in our own repo, where we can read it. The only third-party code in the loop is the official MCP Go SDK and the A2A Go SDK.
A turn has five steps. Figure 2 in A question, end to end shows them in order.
fast model picks one of four routes: answer directly, search your files first (RAG, retrieval-augmented generation), call tools, or search and call tools. It picks by classification, reading one decoded token's probabilities (see Routing). On the search routes, merud then searches your files for the question, with an earlier question appended on a follow-up. No model rewrites the query. The tools route searches too: the router sends some questions about your files there, and an answer from the files beats one from the model alone. Rules then adjust the route (see Routing): a direct question that names an indexed folder or asks about past chats becomes search, a question that names a connected tool server gets tools, and so does a question that says "remember", names Apple Notes, asks for the web, gives a URL, asks about the user's own records while a server is connected ("trip", "hotel", "receipt", "spent", "booked" and the like, so "what did I spend on my last trip" gets mail as well as the files), or names what a connected server's tools act on ("email" for Gmail's tools). A reply to a turn that used a server's tools keeps them too, whatever its words: "yes, make the card with the first photo" after a turn that read mail once routed to the file search alone, and the model said it couldn't fetch the attachment. The same signs skip the search on a tools turn: a web, mail or notes-app question gets no excerpts, which crowd the answer and cost time, and the file tools stay on offer. search and search+tools always search. From v0.4, a separate short call picks the skills to load, beside the router. A picked skill brings the tools its allowed-tools key names (see Skills): when the route lacks one that config allows, direct becomes tools and search becomes search+tools. The router alone can't catch this: "help me understand btop with some simple commands" gave direct 0.761 and tools 0.022, while the skill pick chose web-research, whose first step is web_search. Every route now offers the web tools while web_search is on, so web-research widens a route only when web_search is off and web_fetch isn't. A skill that adds only web tools leaves a direct turn unsearched; one that adds the file tools makes it a file turn. Last, some questions go to the web before the model's first round (see Web first): one that asks for the web or gives a URL, and, on a turn that searched your files, one that names a thing the files don't cover. merud runs web_search or web_fetch itself, through dispatch, and the route gains the tools when it lacked them. A question about Meru itself runs about_meru the same way, and skips the search of the files unless it names an indexed folder (see Questions about Meru itself).tools and search+tools routes, the allowed tools' schemas, each within its own token budget. Every turn's prompt also carries the rule that the model never claims an action no tool took, a line that names Meru and the answer model, and a line on what Meru's own tools can change (see Claims no tool backs). While config allows view_image and the main model lists vision, it carries a line that says the model can look at pictures with view_image. While the file tools are on, it carries a line that says where the past chats are, too. On search the model gets the file tools' schemas (read_file, list_folder, grep and search_files, and search_images and view_image while images and vision allow them) and those of the local commands that don't ask. Every route gets the schemas of datetime and about_meru, and of web_search and web_fetch while web_search is on. On an Auto turn the route's list decides what the model sees, not what runs: a call to an allowed tool the round didn't offer still goes through dispatch and runs, and the turn counts it as a malformed call (see Model sets). A route offers fewer tools to keep the prompt short, and a model that rightly reaches for another allowed tool shouldn't fail for it. On a turn whose scope the user picked, the list is a fence: the agent hands dispatch the round's offer as Call.Offered, and dispatch denies any other tool, with a line telling the model to use the tools it was given. The call still gets its tool_call and tool_result lines and its tool_calls row, with the outcome denied. A turn about your files (every turn that searches first, or would in agentic mode) also gets a note on the file tools: it may read whole files, list folders, grep and search again when the excerpts fall short. A turn that offers web_search, on any route, adds a line to the tools note: "When you aren't sure of a fact, such as a song, a film, a book, a person, a product, a place or anything that may have changed, call web_search before you answer, and cite the pages you use. Never tell the user you can't search the web." The skills list then names only the skills whose tools the turn offers, or that name no tools, so it never points the model at a tool it lacks. Both depend only on the tools offered, and in Auto every route offers the same web tools, so both keep their place among the parts that stay the same. A turn that offers both web_search and a file tool adds a second line: when the files don't answer, call web_search before answering from memory, and never make up a command's flags or a version number. On a turn that offers web_search, a search that finds nothing points the model at web_search for how to use a program and for facts that change. A turn whose tools reach two or more of the user's own data sources ends the tools note with a sources note. The sources are the file tools, the Apple Notes tools and each MCP server, such as google or obsidian; web tools, commands and A2A agents hold no record of the user's life and don't count. The note names each place, such as "the user's files, the google tools and the obsidian tools", with the servers sorted. It tells the model to check each place that could hold the answer to a question about the user's own life, such as a trip, a purchase, a meeting or a message, before it answers or says the answer isn't there; and, when the question says last, latest or recent, to search by date, newest first, and answer from the newest match. It depends only on the tools offered, so it keeps its place among the parts that stay the same. A real turn drove it: asked what a recent hotel stay cost, the model searched the user's old expense folders, answered from a stay ten months back, and never looked at mail, where last week's receipt sat. What the web-first step found goes last, among the parts each question changes, under "From the web", in at most 8,000 characters; a turn's web notes in the history take at most 1,500 of its 8,000. The time of day follows it, to the minute with the zone and its offset from UTC, such as "The time now is 20:02 EDT (UTC-04:00)." It changes every minute, so nothing may follow it. Today's date stays among the shared parts, with a pointer to datetime for the time in another place, a weekday or days between dates. The prompt once left the time to the tool; asked "what's the date and time right now", a model called no tool, read the date from the prompt and made up the time. The line costs about 18 tokens, and a follow-up in a later minute reprocesses it, the history and the question. That note on the file tools sits after the parts every turn shares, so other turns share the whole opening with it and keep a shorter prompt. Where the tool schemas land depends on the model's chat format: Qwen's puts them before the system prompt, so they stay in the shared opening, and Gemma 4's puts them after it, so a new question reads them again (see Models we tried). On the tools and search+tools routes, the loop first asks each connected MCP server for its tools again and gives each server that isn't connected one try, then lists the tools (see MCP).main. A turn that gets here while merud still loads the answer model at startup waits for that load (see Model tiers). Stream text to the client as it arrives. Ollama sends each tool call whole, in a chunk of its own, and the loop collects them. It tells the client about each call with a tool_call event. Each call carries num_predict = [agent] max_output_tokens (default 8,192). Ollama counts a thinking model's hidden reasoning against it, so a model that would think for minutes stops with done_reason = "length". Ollama offers no separate budget for thinking: think only turns it on or off.dispatch, in this order:
denied, and on a turn whose scope the user picked, so is a tool the round didn't offer. It doesn't run, but it still gets a tool_call line, a tool_result line and a tool_calls row, so a model that keeps reaching for forbidden tools shows up in the log. A call named after a skill, such as web-research, gets a result that names the tools to call instead (see Skills).tool_call line goes in before the call runs. If it can't be written, the call doesn't run.configure, web_fetch on a URL no search result or question gave, and an MCP tool in its server's always_confirm list). If you say no, or nobody can be asked, the outcome is declined.ok, error, timeout or cancelled. In an MCP or A2A result, dispatch replaces each run of 2,000 or more base64 characters, on one line or wrapped at one width, with a note that gives its length. A model can't read base64: in a real turn one PDF came back as 109,068 characters of it. A Gmail attachment ID, about 400 characters, stays, because the model passes it back. When the call ends ok and its result names a mail attachment the call saved, dispatch then adds the file's path and text to the result (see Adding an MCP server).dispatch removes secret values from the arguments, the result and any error text, then writes the tool_result line, the tool_calls row, the metrics and the meru.dispatch span. The model reads up to 16,000 characters of the result, with a note when dispatch cut it; the transcript and the row keep 4,000 of the same text, attachment included. In an incognito chat the row keeps neither the arguments nor the result (see Incognito chats).No other code path reaches a server, agent, built-in tool or local command. The calls of one round run at the same time (errgroup, Go's helper for running calls together and collecting their errors), and each sends its tool_result event to the client as it ends. A denied or declined call still reaches the model as a result, so it can answer without the tool or ask you what to do.
[agent] max_rounds model calls (default 8). The last allowed round offers no tools, so the model has to answer with what it has. A call with the same name and arguments (compared as canonical JSON) as one the turn already ran doesn't run again: the model gets the earlier result with a note that it repeated itself. A repeat never reaches dispatch, so it is no tool call: no tool_call event, transcript line or tool_calls row, only a debug log line and the turn span's meru.turn.repeated_calls. After the second repeat, later rounds offer no tools. A 2B model offered only datetime once called it with no arguments in all eight rounds.
Each round sends every earlier call and result again, so a turn that reads many pages can outgrow the answer model's context window (see Context length under Model sets). Ollama then stops the answer with length after a few hundred words. Before each new round, merud estimates the prompt: the tokens Ollama counted for the round that just ran, plus the new messages' characters divided by three. Only an engine that reports no count gets every character divided by three, which runs far high on tool schemas: in one turn it passed the limit while Ollama counted 18,000 tokens, and the turn lost its tools after one search. When the estimate passes 80% of the window, it shortens this turn's oldest tool results, oldest first, to their first 400 characters and a note that tells the model to call the tool again if it needs the whole result. The 20% left over is room for the answer. A shortened call no longer counts toward repeats, so calling it again runs it. The newest round's results stay whole, since the model hasn't read them, and so do the system prompt, the history and the question, which the context budget sizes (agent/budget.go). When shortening isn't enough, later rounds offer no tools, so the model answers from what it has. A model that calls a tool anyway gets one more round, with a user message that says tools are off and asks for the answer now; this shares the one retry a turn has with the empty-reply retry below. In a real turn the model wrote "I'll pull the full text of the top 4 articles" with five calls that couldn't run, and the user read that plan as the answer. The turn then ends window_full, and the answer closes with a note that the prompt filled the context window, so the answer uses only what it read, and that Continue picks it up. The prompt Meru builds before any tool runs is large: with the full model set, the system prompt, skills, excerpts and about 15,000 tokens of tool schemas came to 24,485 tokens, which leaves a 32,768-token window little room for results; the window merud sizes for the answer model leaves it more. The transcript keeps every result whole. The turn span records meru.turn.shortened_results and meru.turn.window_full. With context_length = 0 Meru doesn't know the window and shortens nothing. In a real turn that read about twenty pages, the prompts of its rounds added up to about 169,000 tokens against a 32,768-token window, and the answer stopped after 650 tokens.
A round can end with no text and no tool call, when a thinking model spends it all on hidden reasoning. When the turn has a round left and the round didn't stop at max_output_tokens, merud asks once more: the same messages plus a user message telling the model to answer now in plain text from the tool results, with no tools offered. The empty round's thinking stays out, and the nudge lives only in that call, never in the transcript. A turn retries once; a second empty reply ends it gave_up, or capped when the turn has used every round. The turn span records the retry as meru.turn.empty_retry. In a real turn a thinking model got eight good web_search results, then wrote 205 tokens of thinking and nothing else, and the user read the sorry with seven rounds left.
A round with tools on offer can end on a plan with no call, such as "Let me check the 2024 sheet." When the turn has a round left, merud adds the plan and a user message, "You said what you would do next but didn't do it. Do it now: call the tool, or answer from what you have.", and runs the next round with the same tools. The nudge stays in the turn and never reaches the transcript, and a turn gets one. A real session's last round wrote "Let me find the specific date with 20 stars." and stopped, and merud logged it as a full answer.
A round can also fail part way, when Ollama can't parse what the model wrote. Ollama then sends an {"error": ...} line in the stream after its 200 OK, and the engine returns ErrModelOutput (see Engine layer). When the turn has a round and time left, merud runs the round once more with the same tools (none, when the retry is the turn's last round), plus a user message: "Your last tool call didn't parse, so it didn't run. Call the tool again with valid arguments, or answer in plain text." Text the failed round streamed stays on screen, and a blank line separates it from the retry's text. The nudge lives only in that call, never in the transcript. This retry counts apart from the empty-reply one, since each fixes a different slip; max_rounds and turn_timeout bound both. A second failure, or a first one with no round left, ends the turn bad_output. Ollama's error text goes to merud.log at warn with the model's name, never to the chat. The turn span records the retry as meru.turn.output_retry. In a real turn qwen3.6:35b on Ollama 0.34 wrote a malformed tool call, and the user read XML syntax error on line 8: element <function> closed by </parameter> as the answer.
A turn has [agent] turn_timeout (default "5m") from question to answer, waits for your approvals included. When the time runs out, merud cancels the turn's context, which stops the Ollama request and any tool calls. A turn that ends without a full answer still answers, with an outcome of its own:
| Outcome | When | What you read |
|---|---|---|
timeout | turn_timeout ran out | the text so far and a note that it stopped, or a sorry |
cut_off | the last call hit max_output_tokens | the text so far and a note that it stopped, or a sorry |
window_full | the tool results filled the context window, so later rounds offered no tools (step 5) | the answer from what it read, then a note naming the window's size and pointing at Continue |
gave_up | the rounds ended with no text, even after the one retry, with rounds still left | "Sorry, I couldn't answer that. Try asking again, or rephrase the question." |
capped | the turn used every round max_rounds allows and wrote nothing, or only a plan for its next step, such as "Let me find the date." | with nothing written: "Meru used all 8 rounds of tool calls this question allows and didn't reach an answer. It tried: …", naming each tool once with a count and its failures, and pointing at Continue; with a plan: the plan, then a note that says the same |
bad_output | Ollama couldn't parse the model's output, even after the one retry | any text so far, then "The model wrote a tool call that Ollama couldn't read, twice. Try asking again, or rephrase the question." (without "twice" when no round was left to retry) |
no_vision | the question carried images and the main model lacks the vision capability | when the index holds images like the first one: "Here are the images in your folders most like the one you attached:", the list, and a line that the model can't look at pictures. Otherwise: "<model> can't look at images, so Meru didn't send it this question." Both end with the suggestion described in Questions with images. |
The words go out as ordinary token events, so both clients show them as the answer. The outcome goes on the meru.turn span, the turn log line and meru.turn.duration, in the assistant line's outcome field in the transcript, and in the done event's outcome field, empty for a full answer.
An answer that ends cut_off, window_full, timeout or capped stopped with work worth keeping: the pages it read and the calls it made. Asking again would do that work over, so both clients offer Continue under the chat's newest answer when it stopped short: a button in Meru.app and /continue in meru chat. Either sends an ask with continue: true and the chat's session, and no text of its own.
merud reads the session's last turn from its transcript, which already holds the question, every tool call with its arguments and result, and the answer so far. It hands the model, in place of a question, a summary of that turn:
capped it says the turn ran out of tool rounds, so the model chooses its calls with care. A Continue turn has max_rounds of its own.The answer so far reaches the model through the history, as every earlier answer does. The turn routes, searches and recalls memories on the last question, and skips the web-first step, since the summary holds what the web gave. The URL guard knows the URLs of the last question as before. The transcript's user line reads "Continue", what the user pressed, and a later turn's history shows the same. merud refuses Continue on a chat whose last answer is whole: "the last answer in this chat is complete, so there is nothing to continue." meru run --json starts a session per question, so it has nothing to continue and doesn't offer it.
dispatch sees the tools through one interface, Backend, with four implementations in a fixed order: the built-in tools, the local commands, the MCP client pool, then the A2A client. When two backends offer the same name, the first keeps it, so no MCP server can shadow configure or a cmd. tool.
A context.Context, Go's value for carrying a cancel signal and a deadline, runs through the whole turn. If the client disconnects or you press Ctrl-C, merud cancels the turn, with no sorry: generation stops, merud drops in-flight tool calls, and their tool_calls rows record the cancellation.
A question can carry up to five images, attached in the desktop app (see The desktop app) or from a terminal (below). merud reads each one from the uploads folder before the turn starts, then asks OllamaEngine.Capabilities whether the main model lists vision. When it doesn't, the turn calls no model and answers with the no_vision message above. The message ends with a suggestion drawn from your own [[models.sets]]: the first set, in config order, whose main model lists both vision and tools and that Ollama has pulled, as in "qwen3.6:35b can: switch to it with /model qwen-4bit in meru chat, or Use for answers in Settings, Models." With no such set, it says to pick a model that can see pictures with /model or in Settings, Models. The names come from config, never from code, since the models with vision change with each release.
Images like it. When the index reads images (see What gets indexed), merud first embeds the question's first image and finds the eight indexed images nearest to it, before the vision check and with no chat model call (the embedding is the only model call). The search is the turn's search: it goes out as the sources event, numbered from [1], and the turn searches no text, so the answer's numbers point at one list. Without vision, the answer is that list. With vision, the list joins the prompt, and the model, which sees the attached image and the paths of the found ones, can open any of them with view_image and say which fit. A failed or empty search leaves the turn as it was. When the model has vision:
fast model reads text alone, so its guess would ignore what the question is about. The turn takes the route its scope gives, as a scoped turn does, and direct in Auto, with the tools direct offers. A scope still holds: My files searches first, and Mail and calendar and Web offer their tools, with the images on the question all the same. Every scope, Just talk included, gets the list of similar images in the prompt and the sources event when the search found some. Skills are still picked from the question's text.images field, never their bytes, and a later turn's history carries a text note per image, [image: receipt.jpg], after that question. Each image costs the model hundreds of tokens and seconds of work, and the answer that looked at it sits in the history already, so sending it again would spend the context for little.meru.turn span gets meru.turn.images, the turn's info line an images count, and a debug line the count and total bytes. No span or log line holds an image.The terminal clients send images too. meru -image shot.png "..." and /attach <path> in meru chat first ask merud to copy the file into the uploads folder with attach_file, then name the copy in the question, as the desktop app's attach button does.
A model can say it did something that no tool did. In a real session a user asked Meru to save a Go program, and write_file saved it under ~/meru-output/hello-go/. The user then asked Meru to move that folder to another folder. The router picked search, which offers only the file tools; the model called no tool and answered "Done. It's now at …/repos/hello-go/". Meru has no tool that moves a file, and nothing moved. The user learned it only on finding the folder missing.
Two parts guard against this. The first is in the prompt. Every turn carries this rule after the one on who "I" is:
Never say you did something, such as saved, moved, sent, deleted, changed or scheduled, unless a tool call in this turn did it and succeeded. Never say you called, ran or used a tool or command unless you called it in this conversation. Never make up what a tool would give you, such as a time, a file's contents or a search result: call the tool, or say you don't know. When none of your tools can do what the user asks, say so first, then offer what you can do.
The middle two sentences came from a second session. Asked "whats the date and time right now" on the tools route, a model called no tool and answered with the right date and a made-up time. Asked "did you run date or how did you get this time", it answered "I called the datetime tool", and no call backed that.
and, after the note on your folders, a line built from the tools config allows:
You can write files only inside ~/meru-output, with write_file. Meru's own tools can't move, rename or delete files, or run programs other than cmd.git-log.
The folder comes from [skills] output_dir, and the line says "You can't write files" when write_file is off. The cmd. names are the [[commands]] entries, sorted. The line lists what config allows, not what one route offers, so it stays the same from turn to turn and Ollama reuses its work on it. It speaks only of Meru's own tools: an MCP tool such as a mail server's send tool says what it changes in its own description.
When write_file is on, the line goes on:
You can't create or edit a picture's pixels. To make a card, a poster or a collage, write an HTML page with write_file and name the user's photos in <img src="..."> by their paths in the output folder, such as a downloaded attachment's; write_file puts the photos into the page.
A real chat asked for a greeting card from a family photo. The model offered photo edits it can't make, then wrote a page with no photo in it.
A model can also make up who it is. Right after the honesty rule, every turn names Meru and the answer model:
Your name is Meru, and the model qwen3.6:35b writes your answers, through Ollama on this computer. Never give yourself another name, and never name another model as yours.
For an answer model on an endpoint, the line names the endpoint's model and "the model server Meru calls @name on this computer" instead of Ollama.
The line came from a real session. Asked "who are you" on the search+tools route, qwen3.6:35b called no tool and answered "I'm Meru", then "My name is Jina. I use a Mistral model." Neither name appears anywhere in Meru. The prompt already told the model to call about_meru for questions about itself, and it didn't. With the name in the prompt, it needs no call. The model changes only on a model switch, which loads another model with an empty cache, so the line keeps its place among the parts that stay the same.
The second part checks the answer. A turn that ended without a full answer, bad_output among them, gets no check, since it ends in Meru's own message. When a turn ends with a full answer and no tool call the model made ended ok (the calls merud makes itself for Web first don't count), merud reads the answer sentence by sentence, leaving out code blocks, and looks for a claim of a finished action. The table gives the main shapes; honest.go holds the full word lists:
| Rule | Matches |
|---|---|
| a sentence that opens with "Done" and a stop | "Done.", "All done!" |
| it, they, or a file, folder, note, email or event "is now at/in" | "It's now at ~/Projects/garden" |
| "has/have been" and an action | "The file has been saved to ~/Projects" |
| "I", "I've" or "I have", with one word allowed between, and moved, saved, sent, deleted, removed, renamed, copied or scheduled | "I've moved the folder", "I just sent the email" |
| a sentence that opens with saved, written or stored, after an optional "yes" or "ok", then at, to, in, as or under | "Yes — saved at ~/meru-output/links.html" |
| the same with created, updated, wrote, written, rewrote, rebuilt, restored, stripped, cleaned, fixed, corrected, edited, changed, replaced or added, when the sentence names a file, folder, note, email, event, reminder, calendar, page, document, report, draft, spreadsheet or a path | "I've created the file ~/notes/plan.md" |
| a sentence that opens with one of those verbs, or added, changed, edited or replaced, then "the", "your", "a", "an", "it" or "them", when it names such a thing | "Updated the HTML dashboard with a new column" |
A sentence that ends in "?", or that holds words such as "if", "want me", "I can", "I'll", "let me", "shall I", "would you", "not", "never", "unable" or any "n't", counts as a question, an offer or a denial, and never as a claim. Case doesn't matter, and every pattern matches whole words.
When a claim turns up, merud sends a notice event after the last token and before done, with the text "Meru didn't run any tool for this answer, so nothing changed on your computer." meru prints it on stderr as a dim note: line after the answer; meru chat draws it in amber under the answer. The assistant line keeps it in a notice field, and the session's history hands it to the model in square brackets after that answer, so the next turn doesn't build on the claim. The turn span gets meru.turn.unbacked_claim = true and the turn log line unbacked_claim=true; neither carries the text.
The check reads plain English patterns, so it is easy to test and to explain, and it gets some cases wrong. It misses a claim in words no rule lists, such as "your folder lives in ~/Projects now", and any claim in another language. It flags a "Done." at the top of a poem you asked for, where the note is true but not needed. A successful call that could change something, such as write_file, an MCP tool or a command, silences it, because it can't tell which call backs which claim. A built-in that only reads (read_file, list_folder, grep, search_files, search_images, view_image, analyze_table, web_search, datetime, about_meru and the Apple Notes tools) doesn't: a real turn ran grep three times, wrote nothing, and answered "I've fixed all instances in the HTML file".
A second check runs on every full answer, whatever its tool calls, and looks for a sentence that says Meru called, ran or used a tool or a program:
| Rule | Matches |
|---|---|
| "I", "I've" or "I have", with one word allowed between, and called, ran, run, used, invoked, executed, queried, checked or asked, when the sentence says tool or command or names an allowed tool in backquotes | "I called the datetime tool", "I've used the grep tool" |
| the same with ran, run or executed and a common program: date, ls, grep, find, cat, curl, python, bash, zsh, sh, git, uname, pwd or which | "I ran date" |
| using, via, through, with or from, then a name and tool or command, in a sentence with "I" | "I found it using the grep tool" |
| tool or command, then returned, says, said, shows, showed, reported, gave or replied; or "according to the … tool" | "The datetime tool returned 15:25" |
The same questions, offers and denials don't count. A claim names the allowed tools whose names appear in it, compared by the last dot-separated part, so notes.search and search match; it also names a word in backquotes when the sentence says tool or command, and the program of the second rule. It is backed when one of the tools it names has a tool_call line in this turn or in the turns the history holds ([agent] history_turns), so "how did you get this?" can answer about an earlier turn. A claim that names no tool is backed when any tool ran in those turns. merud reads the transcript only when the answer holds a claim. An unbacked claim sends the same notice event, with the text "Meru didn't run datetime for this answer, though the answer says it did.", or "any tool" when the claim names none. On a turn that called no tool and also claims an action, the first notice already says no tool ran, and the second doesn't repeat it. The span and log line mark it as unbacked_claim, as above.
This check misses a claim in words no rule lists, such as "I got it by calling the datetime tool", and flags "here is the command I used" in a how-to answer, where Meru ran no command either.
A third check, also on every full answer, looks at the files the answer links. Asked for "a link to the html you generated", qwen3.6:35b called web_search twice, no write_file, and answered "Here it is:" with a link to ~/meru-output/jordan_reyes_dashboard.html. No file was there, and the answer claimed nothing in words either check reads. So merud takes every file:// URL in the answer, outside code blocks, and asks the file system for its path. When a path doesn't exist, the same notice event says "The answer links ~/meru-output/jordan_reyes_dashboard.html, which doesn't exist on this computer.", with the full path, after any notice the other checks sent. The span and log line mark it as unbacked_claim. A path the check can't read for another reason, such as a folder you can't open, counts as there. It misses a missing file named as a plain path, such as "saved to ~/meru-output/plan.html", which the first check reads instead when no tool ran.
A fourth check looks at the money amounts in a full answer. Asked what a hotel stay cost, a model read the receipt and then wrote a total the receipt didn't hold. The check runs on a turn where at least one tool call returned a successful result, or whose route was search, tools or search+tools even with no call, and where the model saw no picture. A turn on a search+tools route once called no tool and described a hotel receipt, with its amounts and card number, that it had never read; a direct turn, such as a question about prices in general, stays out. The picture rule: no view_image result and no attached image, since amounts in a picture reach the model as pixels and the check can't tell read from made up. merud finds each amount in the answer, outside code blocks and inline code: a currency sign or code before a number, such as $95.18 or EUR 1,042.25, or a code after it, such as 27.00 EUR. It then looks for that value among every number in what the turn read: this turn's successful tool results, the question, the recalled memories, the file excerpts and web section in the prompt, and the user's earlier messages. Earlier answers don't count, so a figure the model moved from one trip to another doesn't pass. It compares values in hundredths, so $572 matches 572.00 and EUR 27.00 matches €27. When amounts turn up nowhere, the same notice event says "This amount isn't in what Meru read this turn, so the model worked it out: $95.18. Check before you rely on it.", or "These amounts aren't" for more than one, naming up to five and then "and 3 more". The check makes no model call and keeps at most 2 MiB of what the turn read. It misses an amount written in words, such as "ninety dollars", and passes a made-up amount that happens to equal any number the turn read, such as a room number.
A fifth check looks for an answer that says Meru made or changed a file. The first check stays quiet once a call that could change something succeeded, and a real turn showed the gap: it downloaded a family photo, which succeeded, wrote nothing, and answered "I've downloaded your photo and rebuilt the card with it". So on a turn with no successful write_file or edit_file call, whatever else succeeded, merud reads the answer's sentences, leaving out code blocks, for one of two shapes. The first is "I", "I've" or "I have", with one word allowed between, and built, rebuilt, created, made, generated, designed, updated, wrote, embedded, included, added, put, saved, replaced, edited, changed or fixed, here or after an "and" later in the sentence. The second is "the card, page, file, image, picture, photo or document now uses, has, holds, includes, shows or contains". The sentence must also name a file, a page, a card, a picture, a document or a ~/ path. The same questions, offers and denials don't count. A match sends the notice "The answer says Meru made or changed a file, but this turn wrote or edited no file. Ask again to have it saved.", unless the first check already warned. The span and log line mark it as unbacked_claim. It misses a claim in words neither shape lists, such as "your card is ready", and flags "I made a list of the files in that folder" on a turn that only searched.
A sixth check looks for a tool call that failed and that the answer goes without. A real turn called a server's list tool without the account ID the tool needs, got the server's refusal, never called again, and answered "nothing today" from a file three weeks old. Two things now help. dispatch ends a failed call's text, when the server says arguments are missing (missing properties: ["account_number"]), with "Call it again with account_number. If you don't know the value, another of your tools may give it first", so the model can fix the call on its next round. And after a whole answer, merud looks for a call that ended error or timeout with no later successful call to the same tool. Unless the answer says something didn't work, with a word such as "failed", "couldn't" or "unable" outside its code blocks, the notice event says "<tool> failed, so this answer goes without what it would have read. Check the answer before you rely on it.", or names each tool when more than one failed. A call the user declined, or one the allow lists refused, doesn't count. It misses an answer that owns up in other words, such as "I have no data on that".
A seventh check looks at the web links in a full answer, under the same rule as the amounts: a turn where a tool returned a result, or whose route wasn't direct. Asked for a ghazal on a poetry site, a model called no tool and gave a link built from the poem's words. It had the site's shape and opened the site's list of ghazals, not the poem; three more made-up links followed, and one went into a page of links the model saved. So merud takes every http and https link in the answer, code blocks included, since a page written to a file carries its links too, and looks for it among the links the chat already read: this turn's tool results, question, memories, excerpts and web section, every earlier tool_result line and every message of yours in the transcript. Earlier answers don't count, so a link the model made up once stays made up. It compares links with the scheme and host in lower case and the fragment and a trailing slash dropped. When links turn up nowhere, the notice event says "No search, page or message in this chat gave <link>, so the model may have made it up. Check it before you use it.", naming up to three and then "and 2 more links". It passes a made-up link that matches one the chat read, and flags a real link the model knew without a search.
An eighth check catches a model that copies Meru's own notes. The history carries a record of each turn's tool calls after its answer, headed "(Meru's record of the tools this turn ran …)", and a real turn wrote one into its answer as "[Meru's record of the tools this turn ran …]", listing a read_file and an edit_file it never called, after it said it had fixed a page it never touched. merud cuts such a copy, in either bracket, from the end of an answer that made no call, as it cuts a copied cap note, and since the client already showed it, the notice event adds "The answer copied Meru's record of tool calls, and Meru cut it: this turn ran none of the calls it listed."
A small model asked to write its route as JSON (JavaScript Object Notation) fails in three ways: it writes broken JSON, invents a fifth route, or answers wrong with no sign that it was unsure. So the router doesn't ask for text. It treats the route as a classification and reads the answer from the model's probabilities:
[index] folders and says that questions about projects kept there, by name, are B. Without that line the model can't tell that "meru" in "what database does meru use" is your own project. Option C names what you have connected, and says that questions about these, by name, are C, or D when they also need your notes. Each MCP server and A2A agent that allows a tool shows as its name with up to five nouns from its allowed tool names, such as google (gmail, message, thread, event, drive); each [[commands]] entry shows by name, such as git-log; and web search shows as web search. merud builds the list from config at startup and again on each reload, not per turn. The folders come from the list the indexer holds, which the desktop app can change while merud runs. The session history and the question come last, and the prompt ends with Answer: . The fixed part, folders and connected tools included, stays the same from turn to turn, so Ollama reuses its work on it from the previous turn.merud asks Ollama's /api/chat for one token with log probabilities (num_predict = 1, logprobs = true, top_logprobs = 20) and with thinking off (think = false). A thinking model such as MiniCPM5 otherwise spends its one token starting its hidden reasoning, and no letter comes back.A question sent with a scope other than auto, from the desktop app's "Where Meru looks" switch, skips the router: the scope sets the route and the tools (see The desktop app).
The model decodes one token, so routing costs a prompt evaluation and nothing more, and it can't name a route that doesn't exist. When the confidence falls below min_confidence, or fewer than two letters appear at all, the router takes the fallback route, search+tools. That's the one route that can't fail a turn for lack of context: an unsure router spends tokens rather than guesses.
[router]
top_logprobs = 20 # Ollama's cap
temperature = 1.25 # fitted by `make router-eval`
min_confidence = 0.45 # below this, take the fallback
fallback = "search+tools"
decision = "top" # or "marginal"
search_threshold = 0.30 # "marginal" only
tools_threshold = 0.25 # "marginal" only
decision picks how the four probabilities become a route. The default, top, takes the most likely letter as described above. marginal asks two yes/no questions instead. B and D both search, so P(B) + P(D) is the chance the turn needs a search; C and D both call tools, so P(C) + P(D) is the chance it needs tools. Each sum that reaches its threshold adds its half, and a turn with two yeses gets search+tools. marginal needs no confidence floor, so it takes the fallback only when fewer than two letters appear. Take "what was the last email I sent?" at search 0.473, tools 0.260, search+tools 0.218: top picked search and offered no mail tools, though the two tool letters held 0.478. marginal picks search+tools. With the prompt naming the connected tools, marginal at 0.30 and 0.25 missed a needed search or tool on 3 of 46 held-out turns against 7 for top, and matched the label on 36 against 34. Both offered unneeded tools on 3 turns; marginal added an unneeded search on 6 against 5. The default stays top until labelled turns from real transcripts confirm the gain. docs/fast-router.md has the numbers.
The router lives in internal/router as one function, Decide, which returns the route, its confidence, the full distribution and an outcome (ok, low_confidence or degraded). A model that answers unclearly isn't an error; Decide returns the fallback and says why.
Ahead of the rules below, one takes a search away. When the question opens with a writing verb (rewrite, rephrase, reword, paraphrase, proofread, shorten, simplify, translate, polish, edit, improve or fix) and a line break, a colon or a double quote follows it, the question gives the text to change, and a search route becomes direct. The first two rules below then leave the turn direct. The router sent rewrite "Meru streamlines my workflow by handling my tasks efficiently." to search at 0.518 against 0.425, most likely because the text says "my workflow" and "my tasks", and the search added ten excerpts and 7,000 tokens to the prompt. Two changes to the prompt that fixed that question lowered the labelled set's score, the wording of option A from 0.890 to 0.805 on the fit set and a new example to 0.839, so the fix is a rule that leaves the router alone. "rewrite my resume from my documents" gives no text and keeps the router's route. A question that quotes a file name, such as edit "plan.md" in my notes, goes direct by mistake (writingOnText).
A second rule sends a short message of thanks or greeting direct from any route. The message has no question mark and ten words at most. Every word is on a short list of thanks, praise and greeting words or of filler such as "you", "did" and "is", and at least one is thanks, praise or a greeting, such as "great job Meru! Yay!!!" or "thanks, that worked". A typo of a thanks word counts when it keeps the first letter and sits one edit away, or two for a word of six letters or more, so "you did a greewat job meru" counts and "create a job" doesn't. No rule below widens it, so with answers = "routed" the fast model replies. The router scored "great job Meru! Yay!!!" at 0.391 for search+tools against 0.357 for direct, under min_confidence, so the turn took the fallback: a search and every tool's schema made a 39,844-token prompt that the main model read for 52 seconds before a 57-token thank-you. "yes" and "ok" aren't on the list, since they often answer a question Meru asked, and one word off the list, as in "thanks, now read the other one", leaves the message to the router (thanksOnly).
Five rules override the router, in this order. The first: when it picks direct and the question names an indexed folder as a whole word, such as "meru" for ~/repos/meru, the agent loop changes the route to search. Even with the folders in the prompt, the router sent "what database does Meru use to store its index?" to direct at 0.621, and the model made up an answer. A wrong guess costs one search of about 50 ms, and the model uses only the excerpts that help. The turn's route event, log line and span show search; the meru.route span and metric still record what the router chose. The rule matches the last part of each folder path, in any case, and skips names under three letters. "hey meru, what's the capital of France" searches too, because the assistant shares its name with the folder.
The first rule also moves a direct question about past chats to search: one that names a chat, conversation or session along with "previous", "earlier", "past", "last", "before", "ago", "yesterday", "prior", "old", "older", "history", "folder", "tag", "tags" or "tagged", or says "we" with "talked", "discussed" or "chatted". The router sent "check my previous conversations with you, what were they all about" to direct, which offers neither the recalled sessions nor the file tools, and the model said it had no access to past conversations. search offers both (see Facts and episodes).
The second: when the question names a connected MCP server or A2A agent as a whole word, and the route is direct or search, the agent loop adds the rest. direct becomes tools, and search becomes search+tools. The names come from the tools dispatch offers, such as "obsidian" from obsidian.obsidian_simple_search and "research" from a2a.research.summarize, and the loop reads them on each turn, because configure can add a server while merud runs. Built-in tools don't count: their owner is meru, the assistant's own name, which would match most questions. The router sent "Search my Obsidian vault for notes mentioning 'AI'" to search at 0.65; with no tools offered, the model said it couldn't search the vault. With the rule it listed the vaults, searched one and answered. A wrong guess costs a prompt that holds the tool schemas.
The third: when the question holds "remember" as a whole word and the route is direct or search, the loop adds the rest, so the model can call remember. "Remember that I work on the registry team" reads like chit-chat to the router, and a direct turn would answer "noted" and save nothing. The same rule covers Apple Notes: a question that says "Apple Notes" or "Notes app" gets tools while the Apple Notes tools are on. "My notes" alone doesn't count, since it may mean the notes in your folders or an Obsidian vault. The router's prompt doesn't name these tools: adding "web pages" and "remember" to it once cut its accuracy on the labelled fit set from 0.907 to 0.850.
The fourth: when the question asks for the web and web_search exists, or gives an http or https URL and web_fetch exists, and the route is direct or search, the loop adds the rest. A question asks for the web when it holds one of these phrases as whole words, in any case: "web", "internet", "online", "the net", "web search", "websearch", "internet search", "search the web", "search the internet", "search the net", "search online", "look up", "look it up" (or "this", "that", "them"), "google it" (or "this", "that", "for"), "do research", "do some research", "deep research", and "research about" (or "this", "it", "that"). "research" alone isn't on the list, since "summarise my research folder" is about your files, and neither is "google" alone, the name of the server behind Gmail. The router sent "Search the web: what is SearXNG?" to direct, and the model, with no tools, wrote a tool call as plain text. Such a question also goes to the web first (see Web first). Since every route now offers the web tools while web_search is on, a factual question the router sends direct without asking for the web can still look things up; the router itself didn't change.
The fifth: when a word in the question matches something a connected server's tools act on, the loop adds tools. The nouns come from the tool names, singular and lower case, minus common verbs and words such as "file": gmail, message, calendar, event, drive, note. A word matches when it equals a noun or ends in the same four or more letters, so "email" matches gmail. The router sent "what was the last email I sent?" to search, which offers no server's tools, and the model grepped the user's files.
Naming the connected tools in the prompt took over much of the fifth rule's work. On the labelled set, with the catalog's google and obsidian servers, a git-log command and web search connected, the router now sends "what was the last email I sent?", "how many unread emails do I have" and "what does the onboarding doc in drive say about laptops" to tools by itself. The fifth rule still rescues one question there, "reply to the last email from my landlord saying thanks", and the second rule still catches "search my obsidian vault for notes about sourdough", which the router sends to search. All five rules stay.
make router-eval scores the router against the local Ollama on a labelled set of 167 questions, 49 of them held out, and fits the temperature. It also compares the two decision rules on the same answers. The figures here come from the set when it held 153 questions, before nine questions about pictures joined it. With the connected list, top got 131 of the 153 right against 126 without it, and missed a needed search or tool on 15 against 20; it offered unneeded tools on 5 against 2. The list adds about 48 tokens to the prompt. At 1.25 the probabilities sit close to calibrated, so min_confidence = 0.45 means what it says. Refit after any change to the prompt, the examples or the fast model.
The full design, with the prompt contract, tests and calibration results, is in docs/fast-router.md.
An MCP server is a program that offers tools, such as "search my notes" or "list my events", in a form any MCP client can call. Meru is an MCP client; it hosts no servers. config.toml lists the servers, and Meru merges their tools into one set of names, prefixed per server: the model sees obsidian_simple_search from the obsidian server as obsidian.obsidian_simple_search. It supports the two transports in the current MCP spec, both provided by the official Go SDK:
merud starts the server as a child process and talks to it over stdin and stdout. Most local servers work this way.merud connects to a server that is already running, at a URL. It replaced the older HTTP+SSE (Server-Sent Events) transport in the 2025 spec, so Meru doesn't support SSE.Meru can use any MCP server you already run, with no new code.
merud doesn't supervise the servers you add by hand. This section describes the [[mcp.servers]] entries: servers you add and run yourself. For them the operating system already ships a process supervisor, and merud adds none. The connectors are the one exception: servers that Meru installs from a manifest with a pinned version, which a supervisor inside merud starts, checks and restarts (see Connectors and the supervisor; built for Obsidian over stdio and Google over HTTP). The pool reaches a connector through its supervisor, and nothing below changes for a hand-added server:
| Transport | What merud does | What it never does |
|---|---|---|
| stdio | starts the server as a child, because the transport is the child's stdin and stdout | restart it on its own, watch its health, back off and retry |
| Streamable HTTP | connects to a URL | start it, restart it, health-check it, wait for it |
Starting a stdio child isn't supervision: until the child exists there is no server to talk to. An HTTP server is somebody else's process with its own lifetime. You start it with launchd, systemd or by hand, the way you start Ollama.
Connecting: once at startup, once more per turn. merud tries each configured server once when it starts: connect, initialize, tools/list. A failure is recorded with its reason, and the server stays listed as not connected. A server that isn't connected has no tool list, so its tools aren't offered. At the start of each turn on a tools route, before it lists them, merud tries each server that isn't connected once more, inside that turn: 5 seconds for an HTTP server, 30 seconds for a stdio child, which may still be downloading. If the try fails, the turn carries on without that server. A stdio child that crashed counts as not connected and follows the same rule. For stdio, "try" means start the child and run the handshake; for HTTP, connect to the URL.
Listing again: once per turn. The same turn sends tools/list to each server that is connected, with 2 seconds to answer, and keeps the answer, so the tool list follows the server. An HTTP server needs this: merud holds no stream open to it, so when you restart it nothing tells merud, and the old session looks alive until merud sends something. Before this rule, merud kept a restarted workspace-mcp's old list of 16 tools after the server came back with 33, and an allowed tool stayed missing until merud restarted. If the listing fails, because the server answers "session not found" or nothing listens at its address, merud marks the server not connected and makes the one connect try above, which lists the tools afresh. A listing that runs out of time keeps the old list and the session, since a slow answer doesn't prove the session is gone. A stdio server can't restart behind merud's back, since merud owns the process; listing it again costs one round trip over a pipe, and one rule for both transports keeps the code short. On an Apple M4 Max, BenchmarkRefresh in internal/mcp measures the extra listing at 0.28 ms per turn for an HTTP server on loopback and 0.2 ms for a stdio child, each offering 8 tools. At that cost merud lists every turn and keeps no timer or cache age. It doesn't act on the notifications/tools/list_changed message: an HTTP server sends it on the stream merud keeps closed, and the listing each turn catches the same change, for either transport, before the model sees the tools.
| What happens | |
|---|---|
merud starts | one try per server |
| a turn on a tools route | tools/list to each connected server; one try per server that isn't connected, or whose listing failed, before the tool list |
| a turn that offers no tools, or no turn at all | nothing |
| a call whose session is gone | fails, marks the server not connected, and isn't sent again; the next turn tries the server |
merud never sends a failed call again on its own: the server may have run the tool before the session broke, and a tool such as send_gmail_message would then run twice. The model sees the error and can ask again on the next turn.
For a hand-added server there is no loop, timer, goroutine or backoff, and nothing runs while nobody asks: a server that fails and is never needed again is never touched again. The connector supervisor has a timer and a backoff, for connectors only, and Refresh leaves a connector to it. The one goroutine per session waits for the session to end so that /mcp reports a dead server at once; it marks the server not connected and never reconnects. So you can start workspace-mcp after merud, or restart it with new tools, and your next question sees it with no restart of merud.
[[mcp.servers]]
name = "obsidian"
command = "uvx" # stdio: merud starts this process
args = ["mcp-obsidian"]
env = { OBSIDIAN_API_KEY = "secret:obsidian_api_key", OBSIDIAN_PORT = "27124" } # stdio only
allow = ["obsidian_simple_search", "obsidian_get_file_contents", "obsidian_append_content"] # tool-level allowlist
confirm = ["obsidian_append_content"] # allowed tools that still need a yes per call
always_confirm = [] # ask every call, with no approval for the session
timeout = "60s" # longest one call may take; the default
[[mcp.servers]]
name = "google"
url = "http://127.0.0.1:8000/mcp" # Streamable HTTP: you start the server
headers = { Authorization = "secret:google_token" } # value from secrets.toml
allow = ["search_gmail_messages", "send_gmail_message"]
confirm = ["send_gmail_message"]
remote = false # true only if the URL isn't loopback
| Key | Meaning |
|---|---|
command, args | stdio transport: merud starts this process. An entry has either command or url. |
url | Streamable HTTP transport: you run the server, and merud connects to it here. |
env, headers | extra environment for a stdio server, or HTTP headers for a URL. env goes only with command: merud refuses a url entry with env at startup or reload, with a message that points at headers. A value may name a secret as secret:<name> (see First run and setup). |
allow | the tools the model may call. Anything missing stays hidden. |
confirm | allowed tools that still need a yes from you on every call. |
remote | merud refuses a non-loopback URL unless this is true, the same rule A2A agents follow. It covers only whether merud may connect to a URL on another machine, and says nothing about what the server itself reaches: google has remote = false and talks to Google all day. Before the rename it was called network, and a config that still says network fails to load with "network was renamed remote". |
timeout | the longest one call may take; 60 seconds unless set. |
merud reads the servers when it starts, and again on a reload: after configure adds a server, and when a client sends the mcp_reload op, as meru mcp add does. A reload reads config.toml and secrets.toml, builds a new pool from the servers config lists now, swaps it in, and closes the old one, which stops its child processes. So a server you add, change or remove takes effect without a restart. A config that doesn't load, or a bad server entry, fails the reload with an error that names the problem, and the old pool keeps running.
merud can also probe a server that isn't in config yet (the mcp_probe op): start it, list every tool with its readOnlyHint and destructiveHint, and stop it (see First run and setup). A probe needs no allow list, since it calls no tool, and the model never sees what it finds. It is a user command, like the memory ops, so it doesn't go through dispatch.
Signing in with OAuth. A remote server that wants a user's sign-in, such as GitHub's (https://api.githubcopilot.com/mcp/) or Slack's (https://mcp.slack.com/mcp), takes auth = "oauth" and, for a server with no dynamic client registration, an [mcp.servers.oauth] table:
[[mcp.servers]]
name = "github"
url = "https://api.githubcopilot.com/mcp/"
remote = true # oauth needs a url and remote = true
auth = "oauth"
allow = ["get_me", "search_issues"]
[mcp.servers.oauth]
client_id = "Ov23li..." # from the app you registered; not a secret
client_secret = "secret:github_client_secret" # the value lives in secrets.toml
issuer = "https://github.com/login/oauth" # the one authorization server this client may use
scopes = ["repo", "read:user"] # what Meru asks for; empty takes the server's list
redirect = "" # a fixed callback, such as Slack's "http://localhost:3118/callback"
With no client_id, Meru registers itself with the server as a public client (RFC 7591). merud checks the entry when it loads: auth must be "" or "oauth", an oauth table needs auth = "oauth", client_secret needs client_id and a secret: reference, issuer must be https, redirect must be http on 127.0.0.1, ::1 or localhost with a port and a path, each scope must be one word, and the entry can't also set an Authorization header.
A server with no saved sign-in shows the state sign_in and offers no tools. The user starts a sign-in from either client or with meru mcp login <name>; each sends the mcp_sign_in op. merud listens for the reply on loopback only (a port the system picks, or the one redirect fixes, on 127.0.0.1, and ::1 too for localhost), runs PKCE with S256 through the MCP Go SDK, and answers with the sign-in link, which the client opens in the browser. The callback takes one GET and shows a fixed page; the SDK checks state. merud keeps the token in ~/.meru/oauth/<server>.json, owner-only (0600), and never writes a token, code, state or link to a log, a span or an error. A refreshed token is saved again; a refresh the server refuses puts the server back to sign_in. The OAuth requests go over https only, with no redirects and no proxy, and reach a private address only when the server's own URL is private. Removing a server's entry deletes its saved sign-in at the next reload.
On a turn that offers tools, merud sends a sign_in_needed event naming each server that waits for a sign-in, before the answer. The desktop app shows a Sign in button above the answer and on the server's Settings card, meru chat shows a line that names /signin <name>, and one question with meru prints meru mcp login <name> on stderr. While a sign-in waits for the browser, a client asks mcp_status every two seconds; merud gives up after ten minutes.
Status. meru mcp (or meru mcp status) and /mcp in meru chat show one row per configured server:
$ meru mcp
SERVER TRANSPORT STATE TOOLS ALLOWED CONFIRM
google http connected 124 8 2 127.0.0.1:8000/mcp
notes stdio not connected — 5 1 exec: "uvx": executable file not found in $PATH
obsidian stdio ok 3 3 0 Obsidian is ready. It starts when a question needs it.
CONNECTOR STATE
obsidian ok Obsidian is ready. It starts when a question needs it.
| Column | Meaning |
|---|---|
SERVER | the name from config, or a connector's ID |
TRANSPORT | stdio or http |
STATE | connected or not connected for a server added by hand, or sign_in for an auth = "oauth" server that waits for the user to sign in; config has no key that turns one off. A connector shows its own state (see The supervisor) |
TOOLS | how many tools the server offers, from its tools/list; — when not connected, since there is no list to count |
ALLOWED | how many tools config allows |
CONFIRM | how many allowed tools ask first, from confirm and always_confirm |
| last field | the URL of an HTTP server, or why the server isn't connected; a connector's sentence |
Under the table, meru mcp lists every connector merud knows, the ones that are off or set up by hand included, from the connectors op. A connector that needs a field ends its line with the command that asks for it: "Run meru mcp fix obsidian to set vault_path."
The data comes from the mcp_status op, which merud answers from config and the pool's own record of each server. It sends nothing to any server, so the view is instant and works while a server is down. TOOLS and the warnings in meru tools come from the last listing, which each turn on a tools route renews, so after you restart a server they catch up on your next such question. ALLOWED and CONFIRM come from config and show either way, which tells you what you would get. meru mcp --json prints the same for scripts, as {"servers": [...], "connectors": [...]}. Tool names stay out of this view: meru tools lists each server, whether merud reached it, the tools the model may use and which of them ask first, and warns about each allow entry the server doesn't offer, most often a typo.
Tools are deny-by-default. A server that offers 40 tools gives the model none until you allow specific ones.
always_confirm asks before every call and offers only "approve once" and "deny", like the built-in configure. It is for a tool that sends something, such as mail, or runs commands, where a session approval would let the model act unseen for the rest of the session. The catalog's send_gmail_message comes this way, and Settings' Always ask writes the list.allow and confirm name each tool; merud refuses * or any other pattern. A wildcard would admit tools a server adds in a later release, which nobody has read.timeout, 60 seconds unless set. When it passes, or you cancel the turn, Meru tells the server to cancel the call.PATH, HOME and the few variables Windows programs need, plus the entry's own env. The rest of merud's environment stays out, because it may hold another tool's API key.Meru doesn't confine MCP servers. Each one runs as an ordinary process with your user's permissions, and can read files or reach the network by itself. Adding a server to config means trusting it. Meru's allowlist picks which tools the model may call; what each call does is up to the server.
Meru uses no MCP shell server. It runs the programs you declare in [[commands]] itself (see Local commands), because a shell server confines nothing Meru doesn't, adds a runtime and a process to supervise, and keeps the real policy, which program with which arguments, where dispatch can't see or log it.
Today you install, start and repair every server Meru uses: SearXNG for web search, the Obsidian and Google MCP servers, and Ollama. When one is down, Meru says little. A connector is one of those programs that Meru will install, configure, start, check and restart for you, at a version pinned in Meru's own release. Issue #87 holds the plan, which lands in seven steps.
What exists now (steps 1 to 6): the manifests, the checks on them, the [connectors.<id>] config table, a policy test that refuses unpinned versions, the code that downloads the pinned runtimes and installs each connector into ~/.meru/runtime, the supervisor, which runs Obsidian over stdio and Google over HTTP with its sign-in, the SearXNG container, the watch on Ollama, and Adopt, which moves a hand-added obsidian or google entry over to its connector when you ask. A connector that Meru starts stays off until its table says enabled = true, and an [[mcp.servers]] entry with the same name wins over it, so a working setup behaves as before until you adopt it. Step 6 added the settings forms and Fix in both clients and on the command line (see Setting up a connector), and made the Mac installer and meru setup hand connectors to merud (see The hand-off). Step 7, the release notes and the install skill's last changes, is planned.
Each connector has one TOML file, internal/connectors/manifests/<id>.toml, compiled into merud. Five ship:
| ID | Kind | Install | What it is |
|---|---|---|---|
searxng | container | an image, by digest | the search engine behind web_search |
obsidian | stdio | the npm package obsidian-mcp | notes in an Obsidian vault folder |
google | http | the Python package workspace-mcp | Gmail, Calendar, Drive and Docs |
ollama | dependency | none | the model runtime; status only |
whisper | service | a download and one model file, each by SHA-256 | whisper.cpp's server, for speech to text |
A manifest names:
id, name, kind (stdio, http, container, service or dependency), required, default_on and idle_timeout. A service is a downloaded program that merud starts on loopback and sends plain HTTP requests, not MCP; the Service supervisor runs it;[install]: type (npm, pip, binary, container or none), and the package and exact version, or a container image with its digest, or a url_<os>_<arch> and sha256_<os>_<arch> per platform for a download. A binary install may add [[install.files]], extra downloads such as a model, each a plain file name, an https url and a sha256, saved in the install folder. A file downloads only when a {file.<id>} placeholder picks it;[launch]: the command, args and env that start it, the loopback url and port it answers on, auth (none or oauth), and a container's volumes. For an npm or pip connector, command is the bare name of a program the package installs, such as obsidian-mcp, and Meru finds it in the install folder (see The runtime folder); for a binary it is a path under {pkg}, and {binary} names this platform's download, the last part of its URL, so one command serves every platform's file. {pkg} stands for the install folder, {meru_dir} for ~/.meru, and {field.<id>} for a value the user gave. A service may also use {file.<id>}, the path of the [[install.files]] entry that the choice field <id> names, and {token}, a random value merud makes for each start, in its args and in base_path, which goes in front of every path merud asks it for;[[field]]: what to ask the user, each with an id, a type (text, folder, secret, email, choice or oauth), a label, help, required, and an optional pattern, default and choices. Every client will draw the same form from these;[health]: how to tell it works. An MCP server gets a cheap tool call (tool, args); a container, a service or a dependency gets an HTTP GET (path). expect is nonempty, contains:<text> or json_key:<key>;[mcp]: allow, confirm and always_confirm, with the same meaning as in an [[mcp.servers]] entry.connectors.Load parses every manifest when asked, and refuses the set when one breaks a rule:
id or name, an ID used twice, or a field ID used twice;latest, an empty version, a range (^, ~, >, <, *, x), a bare major such as 2, or a tag;@sha256:<digest>, or tagged latest;pattern that doesn't compile;url isn't loopback;[[install.files]] entry on an install that isn't binary, or with a name that holds a folder or repeats another, a URL that isn't https, or no SHA-256;{file.<id>} whose field isn't a choice, or has a choice that names no file, and a {file.<id>} or {token} outside a service;command that holds a folder, or a binary command outside {pkg};confirm tool that allow doesn't list.whisper is the speech-to-text connector (see Speech to text).
Each connector runs one version, chosen and tested for a Meru release. A pin moves only in a new Meru release, and the release notes list it under "Connector versions". A policy test (internal/policy/pins_test.go) fails on latest, @latest, :latest, a version range, a package runner such as uvx or npx without an exact version, a container image without a digest, and a file fetched from a branch. It reads the manifests, the installer, the catalog, cmd/meru, scripts/, deploy/ and the code blocks in docs/. Meru's own releases/latest link passes: it fetches Meru, not a dependency. The places that break the rule today sit on a short list in the test, each with a reason; the list can only shrink. Step 6 took the installer's searxng:latest off it: merud runs the pinned image now. Step 4 took off meru setup's SearXNG recipe and the docs that repeated it, which fetched files from SearXNG's main branch. Step 5 took off the Google start commands in the catalog, the installer and the docs: each now runs uvx workspace-mcp==1.30.0, the Google connector's pin, so a server you run by hand and the one Meru runs are the same release.
The values a user gives go in config.toml, one table per connector:
[connectors.obsidian]
enabled = true
vault_path = "~/Notes/vault"
enabled is true or false, and a field's value is a string. An MCP connector's table may also hold allow, confirm and always_confirm, each a list of tool names, which then take the place of the manifest's lists; Adopt writes them when the old entry's lists differ from the manifest's. They follow an [[mcp.servers]] entry's rules: one tool per name, no wildcard, and each confirm tool also in allow. config.Load checks the shape only: an ID and its keys are lower-case letters, digits and _, and only those three keys hold lists. It doesn't know the connectors, because the clients import config and must not reach internal/connectors. merud checks each connector's table against its manifest, and a key or value that doesn't fit leaves the connector at needs config, with the field to fix. A tool the server doesn't offer shows as a warning in meru tools, as for a hand-added server, since only the running server knows its tools. A secret field never goes in config.toml: its value goes in secrets.toml as secret:connector_<id>_<field>. [[mcp.servers]] stays for the servers you add by hand, and the supervisor never manages those.
Built in step 2; the supervisor (step 3) calls it.
Everything a connector needs lands under ~/.meru/runtime/, so deleting that folder removes every install:
~/.meru/runtime/
node-24.21.0/ pinned Node, with its npm
uv-0.12.21/ pinned uv
python/ the Python uv downloads (3.12)
cache/npm/, cache/uv/ download caches
home/ HOME for npm and uv, so nothing lands in yours
npmrc an empty npm settings file
chrome-headless-shell-154.0.8037.92/ pinned headless Chrome, web_fetch's page reader
chrome-profile-*/ one page's Chrome profile, removed when the page is read
pkg/obsidian-2.0.1/ one folder per connector and version
pkg/google-1.30.0/
state/<id>.json the tool list from the last health check
logs/<id>.log (planned) the connector's error output; merud.log has it at debug level for now
The runtimes. internal/connectors/runtimes.go pins Node 24.21.0, the newest Long Term Support release on 30 September 2026, and uv 0.12.21, each with a download URL and a SHA-256 for macOS and Linux on arm64 and amd64. It also pins chrome-headless-shell 154.0.8037.92 for web_fetch's page reader (see Pages that need JavaScript), a .zip from Google's Chrome for Testing. Google publishes MD5, not SHA-256, for those zips, so each SHA-256 was computed from a download whose MD5 matched Google's. Windows has no pin yet. The first time a connector needs one, merud downloads the .tar.gz, or the .zip for Chrome, into a temporary folder under ~/.meru/runtime, checks its SHA-256 against the pin, and unpacks it only if the two match. Unpacking refuses an entry that is absolute, climbs out with .., links outside the folder, or is a hard link or a device. The finished folder gets a marker file, .meru-installed, and then moves to <runtime>-<version>, such as node-<v>, uv-<v> or chrome-headless-shell-<v>, in one rename, so a runtime folder either doesn't exist or is complete. Once a new pin's folder is in place, older versions of the same runtime go.
The installs. Each connector installs into ~/.meru/runtime/pkg/<id>-<version>/, by its install type:
| Type | What merud runs |
|---|---|
npm | <node>/bin/node <node>/lib/node_modules/npm/bin/npm-cli.js install --prefix <dir> <pkg>@<version> --no-audit --no-fund --no-update-notifier --ignore-scripts |
pip | <uv>/uv venv <dir>/.venv --python 3.12, then <uv>/uv pip install --python <dir>/.venv/bin/python <pkg>==<version> |
binary | download this platform's file into <dir>, check its SHA-256, mark it runnable |
container | docker info, then docker pull <image>@sha256:<digest> |
npm_config_cache under cache/npm and npm_config_userconfig pointing at the empty npmrc, so your ~/.npm and ~/.npmrc play no part. --ignore-scripts stops the code a package may run while it installs; obsidian-mcp 2.0.1 and its dependencies need none.~/.meru/runtime: UV_CACHE_DIR, UV_PYTHON_INSTALL_DIR, UV_PYTHON_BIN_DIR, UV_PYTHON_CACHE_DIR, UV_TOOL_DIR and UV_TOOL_BIN_DIR. UV_PYTHON_PREFERENCE=only-managed makes it use a Python it downloaded there, never one from Homebrew or the system, and UV_NO_CONFIG=1 skips your uv.toml. Each uv release fixes the list of Python builds it knows, so the uv pin also fixes the Python patch release./usr/local/bin, /usr/bin and ~/.docker/bin). When no docker is there, podman in the same folders or /opt/podman/bin takes its place: Podman takes the same commands and flags. A shell alias such as alias docker=podman doesn't count, since merud runs no shell. None there is "Docker isn't installed"; a failing docker info is "Docker isn't running". Podman's info names the version field differently, so merud picks the template by the program's real name. Only docker gets your real HOME, where Docker keeps its socket and settings.Install works in the final folder, because a Python environment can't move once made. It deletes a folder that has no marker, a leftover from an install that stopped part way, before it starts; writes the marker last; and deletes the folder again if any step fails. The marker records the connector, the version and the runtime folder it used. A manifest version or a runtime pin that differs from the marker means a new install, and the connector's older folders go once the new one is complete. npm resolves the package's own dependencies within the ranges the package names; only the package itself is pinned.
Starting a program. LaunchCommand turns the manifest's [launch] table into a program, its arguments and the variables to add to its short environment, with every placeholder filled in:
node_modules/<pkg>/package.json, finds the script behind the program name in its bin key, and returns the pinned node as the program with the script as its first argument. obsidian-mcp's script starts with #!/usr/bin/env node, which asks PATH for node. Running it through that line would work only while the child's PATH finds the pinned Node, and launchd's short PATH finds none; naming node by its absolute path works with any PATH.<dir>/.venv/bin/<name>. uv writes that script's first line as the environment's own Python, by absolute path.{pkg}, with {binary} replaced by the name of this platform's download.In each case the child's PATH starts with the runtime's bin folder, so a node or python the connector starts in turn is the pinned one.
One place runs programs. internal/connectors/run.go is the only file in the package that imports os/exec, and a policy test holds it to that. It runs each program by absolute path, with no shell, with only the environment the caller lists, streams each output line to a progress callback, and keeps the last 40 lines for the error message.
Built in step 3 for stdio connectors, and in step 5 for http ones (internal/connectors/supervisor.go). merud runs one small state machine per MCP connector, Obsidian and Google, built at startup from the manifests and kept for its whole life. It moves through ten states inside; you see six:
| State | Meaning | Inside it |
|---|---|---|
ok | ready to use; its tools are offered | ok (running) or ready (installed, checked, not running) |
off | config never turned it on, or turned it off | off |
by_hand | an [[mcp.servers]] entry with the same name runs instead ("set up by hand") | by_hand |
needs_config | a field is missing or wrong, the port is taken, or you need to sign in | needs_config, sign_in (running, waiting for you) |
starting | on its way | installing, starting, backoff after a crash |
failed(reason) | stopped until config changes or merud restarts; the reason says why | failed |
off, by_hand, needs_config ──config fixed──▶ installing ──ok──▶ ready ──first call──▶ starting ──▶ ok
│fail ▲ │ crash
▼ └─backoff◀─┤
failed ◀────── fifth crash in 10 min ────────────────┘
ok ──idle_timeout──▶ ready
installing, starting ──check wants a sign-in──▶ sign_in ──you sign in──▶ ok
installing, starting ──port taken──▶ needs_config ──30 s, or a reload──▶ installing
[connectors.<id>] table says enabled = true, or its manifest says default_on; neither Obsidian's manifest nor Google's does.[[mcp.servers]] has an entry with the connector's ID, that entry runs through the pool's own rules, unchanged, and the connector shows by_hand with the sentence "Obsidian runs from your own setup, the obsidian entry in [[mcp.servers]]. There is nothing to do. Optional: meru mcp adopt obsidian lets Meru run and restart it." The desktop app shows the state on a green pill, "Your setup", with Adopt as a quiet secondary button: the server works and needs nothing. Adopt moves such an entry over (see Moving to connectors).merud checks the table against the manifest's fields: a required field needs a value, a folder must exist, an email needs an @, a choice must be one of its choices, a value must match its pattern, and a key the manifest lacks is a mistake. An oauth field has no value in config: the server signs you in (see Google). The first problem becomes the sentence, and Fix lists the fields. When Obsidian's vault_name is empty, merud makes one from the vault folder's name.~/.meru/runtime/state/<id>.json and stops the program. The connector is then ready. A failed install or check sets failed.merud offers them without starting anything. The first call starts the program, runs the health check again, and waits for it at most the connect timeout, 30 seconds. A program left unused for idle_timeout (Obsidian: 10 minutes) stops, and goes back to ready; a call still running holds it up.merud never sends it again, as for a hand-added server. The fifth crash within ten minutes sets failed("keeps stopping: <last line of its error output>"), so the waits run 1, 2, 4 and 8 seconds. A call that arrives during a backoff waits for the restart.ok offers no tools.Spawn hook, and never starts, restarts or stops one; a hand-added server keeps today's code. A reload hands each supervisor its table again: one whose config didn't change keeps its program running, and one that failed gets a fresh try.The child gets a short environment: the PATH and variables LaunchCommand gives, the user's real HOME, and TMPDIR. Its error output goes to merud.log at debug level, with the query of every link in it replaced by ?…, so a sign-in link's one-time state never lands in the log; the supervisor keeps the last line for the sentence.
Status. The socket op connectors returns one ConnectorStatus per connector: id, name, kind, state, sentence, required, the fields with each non-secret value and whether each secret is saved, fix, the fields to ask again, and link, the sign-in link while a connector waits for one. The sentences:
| State | Sentence |
|---|---|
ok, not running | Obsidian is ready. It starts when a question needs it. |
ok, running | Obsidian is running. |
off | Obsidian is off. |
by_hand | Obsidian runs from your own setup, the obsidian entry in [[mcp.servers]]. There is nothing to do. Optional: meru mcp adopt obsidian lets Meru run and restart it. |
needs_config | Obsidian needs your vault folder. / Obsidian can't find the vault folder ~/Notes. / Google needs you to sign in. / Google can't start: another program listens on 127.0.0.1:8000. Stop that program; Meru looks again every 30 seconds. |
starting | Meru is installing Obsidian 2.0.1 and checking it. / Obsidian is starting. / Obsidian stopped (…) and starts again in 2 s. |
failed | Obsidian couldn't install: … / Obsidian failed its check: … / Obsidian keeps stopping: … |
mcp_status and connections carry the same state and sentence for a connector the pool runs, in their connector and sentence fields, and connections marks a hand-added server that takes a connector's place as by_hand. Settings shows each connector's card with a pill and its sentence, the rail gives each connector that isn't off a dot, green when it is ok and amber otherwise, which opens its card, /mcp and meru mcp status print the state and sentence, and about_meru adds the sentence. A sign-in link shows as a "Sign in to Google" button on the Settings card, and after "Sign in:" in /mcp and meru mcp status. A needs_config connector in meru mcp status ends with the command that asks for its fields: "Run meru mcp fix obsidian to set vault_path." A connector's tool lists come from its manifest, or from its table, so the switches on its tool card don't move yet.
Built in step 6 (cmd/merud/connectors.go, internal/connectors/change.go). Two socket ops change a connector, both user commands like the memory ops, so neither goes through dispatch:
connector_set takes the connector's ID and a change: enabled, new field values, and new secrets, each by field ID. merud checks the change against the manifest with the rules the supervisor applies to config (connectors.CheckChange). When the connector would be on afterwards, the whole table must pass: "Obsidian needs your vault folder." refuses the change. When it would be off, each value given must pass its own field's rule, and a required field may stay empty. merud also refuses a secret sent as a plain value, a value for an oauth field, a value on two lines, Ollama, which Meru doesn't run, and a connector set up by hand, which Adopt moves over first. A refused change writes nothing. Otherwise, holding the lock every config.toml write takes, merud saves each secret in secrets.toml as connector_<id>_<field>, with mode 0600, writes [connectors.<id>] through the catalog's checked writer (catalog.SetConnector), which keeps every comment, and reloads.connector_fix is the Fix button. A connector that needs fields answers with its status, whose fix names them; the client asks for those and sends them with connector_set. A connector that is off or set up by hand answers with its status, whose sentence says what to do. Any other gets its check again: a stdio or http connector installs and checks again even when its saved tool list would let it skip that, SearXNG looks at its URL at once, and for Ollama merud checks now and waits up to 5 seconds for the answer.After either change, merud follows the connector: it sends a connector event with the status at once and another each time the state, sentence or sign-in link changes, every 250 ms at most, until the connector is no longer starting or five minutes pass. The last event says where it settled. A secret never comes back: a field's status says only whether one is saved.
Every client draws the same form from the field list, so a new connector in a later release needs no new screen:
| Field type | Settings | /mcp and meru mcp fix |
|---|---|---|
text, email | a text field with the value config holds | one line, Enter keeps the value |
secret | a password field, empty, with "saved" when secrets.toml holds one | read without showing it; Enter keeps the saved one |
folder | a text field and Choose…, which opens the system's folder dialog | a path |
choice | a list of the choices | one line, with the choices named |
oauth | "Sign in to Google", which opens the server's link, once merud has one | skipped; the link prints after "Sign in:" |
Which fields a client asks for comes from one rule, rpc.AskFields: the ones fix names; for a connector that is off, every field but an oauth one; otherwise none, since Fix only checks again.
merud reports. Fix marks the fields it names on the card and moves the cursor to the first. A connector set up by hand has an Adopt button instead of a form: it asks connector_adopt for the plan, shows it in the page's own dialog, and applies it only after Adopt there. The tool card below a connector that isn't ready links to its connector card./mcp in meru chat lists the connectors first. On a connector's row, f runs Fix and then asks the fields it names one at a time, a secret with • for each character; o turns it on or off; and a, on a connector set up by hand, shows merud's plan, which a second a applies. The note line shows each step merud reports.meru mcp set <id> [enabled=true|false] [field=value…] [secret-field…] sends one change. A secret field named alone is read without echo; a secret given as field=value is refused, since the shell's history would keep it. meru mcp fix <id> runs Fix, asks what it names, and for a connector that is off asks first whether to turn it on. Both print each step, then the state and sentence, and the sign-in link while Google waits for one.Built in step 5. Google is the one http connector: merud starts workspace-mcp 1.30.0 from its own Python environment, ~/.meru/runtime/pkg/google-1.30.0/.venv/bin/workspace-mcp, with --transport streamable-http, the four services and the extended tool tier, and talks to it over Streamable HTTP at http://127.0.0.1:8000/mcp. The environment carries USER_GOOGLE_EMAIL, GOOGLE_OAUTH_CLIENT_ID, the client secret from secret:connector_google_client_secret, WORKSPACE_ATTACHMENT_DIR=~/meru-output/attachments, and WORKSPACE_MCP_HOST=127.0.0.1 with port 8000. The child keeps your real HOME, so the tokens a hand-run server saved in ~/.google_workspace_mcp/credentials/ keep working.
merud looks at the port, waiting up to 3 seconds for its own last program to let go. If another program still listens there, the connector is needs_config with "Google can't start: another program listens on 127.0.0.1:8000.", and merud looks again every 30 seconds and on each reload. It never stops that program: it may be the server you started by hand.merud starts the program, waits for it to listen, then connects. A Streamable HTTP session doesn't end when the server's program does, so merud watches the program and closes the session when it exits; a crash then counts as for a stdio connector.list_calendars, marked read-only: one read of the calendar list. Before you sign in, workspace-mcp asks Google nothing and answers the call with an error whose text holds Authorization URL: https://accounts.google.com/o/oauth2/auth?…, with a callback to http://localhost:8000/oauth2callback. The integration test TestIntegrationGoogle checks this against the real 1.30.0 on a free port.sign_in, which you see as needs_config with "Google needs you to sign in." and the link. Every 15 seconds merud runs the check again: a new link replaces the old one, since each works for ten minutes, and once the check passes the connector is ok, with the program running. A check that fails for any other reason, such as a Google API that is off in your project, sets failed. The link never goes in merud.log, and a link counts only after "Authorization URL:" or when its query names both client_id and redirect_uri, so a help page in an error isn't taken for a sign-in.Built in step 4 (internal/connectors/container.go, cmd/merud/ollama.go).
SearXNG is the one container connector. Its own supervisor, a Container, runs one loop while the connector is on: it checks [web] searxng_url, acts on what it finds, and waits a minute, or the backoff after a crash, before the next check. The check is catalog.CheckSearXNG: GET /search?q=&format=json. SearXNG with JSON on refuses the empty query with 400 and {"error": "No query"}, and with JSON off answers a 403 web page; either way it asks no search engine, so the check sends nothing off the machine. The pinned image's /healthz answers OK even with JSON off, when web_search can't work, so Meru doesn't use it.
The mode comes from config (connectors.ContainerMode):
| Config | Mode | What merud does |
|---|---|---|
[connectors.searxng] enabled = true, and searxng_url is http://127.0.0.1:8888 | run | checks, and runs its own container when nothing answers |
enabled = true with another searxng_url | watch | checks and reports; Meru's container answers only at 8888 |
no enabled key, and [builtin] tools lists web_search | watch | checks and reports, as merud did before connectors; it starts nothing |
enabled = false, searxng_url = "", or no enabled key and web_search not listed | off | nothing |
The watch mode is the back-compat rule: a config from before connectors, which lists web_search and names a URL by default, keeps working, and an upgrade starts no container nobody asked for.
In run mode, one pass goes:
docker inspect meru-searxng says whether it is Meru's container, for the sentence.meru-searxng without Meru's label: needs config. Meru leaves it alone.docker pull of the pinned image by digest (the install), then docker run of a new container, docker start of a stopped one, or docker restart of one that runs but fails its check. A container from an older pin goes first. The container then gets 90 seconds to pass its check.docker run gets --name meru-searxng, --label meru.connector=searxng, --restart no, --publish 127.0.0.1:8888:8080, the settings volume ~/.meru/searxng:/etc/searxng and SEARXNG_BASE_URL. Before the first run, merud writes settings.yml there, with JSON on and a random secret key, unless the file exists; an older Mac installer wrote the same file, from catalog.WriteSearXNGSettings. The supervisor alone restarts the container, so it counts each crash, and Docker never starts it on its own: after a reboot the next merud does. Closing merud leaves it running, and turning the connector off stops it.
External SearXNG. A healthy server at searxng_url that isn't Meru's container, such as one you run with Docker Compose or the one an older Mac installer started, counts as external: the connector is ok with "Web search uses the SearXNG already running at http://127.0.0.1:8888.", and Meru never starts, stops or pulls anything for it.
Tools follow health. The model gets web_search only while the connector is ok; web_fetch doesn't depend on it. The sentences:
| State | Sentence |
|---|---|
ok | Web search is running in the container meru-searxng. / Web search uses the SearXNG already running at … |
off | Web search is off. |
needs_config | Web search needs Docker or Podman, and neither is installed. / Web search can't start: Docker or Podman isn't running. / Web search can't use SearXNG at …: nothing answers there. (and, at Meru's own address, how to turn the connector on) |
starting | Meru is checking Web search at … / Meru is downloading Web search (image sha256-…) and starting it. / Web search stopped (…) and starts again in 2 s. |
failed | Web search couldn't install: … / Web search keeps stopping: … |
Settings shows them on the Web search card, /mcp on the built-in tools' line, meru mcp status in its connector table, about_meru in a "Web search" line, and the desktop app's rail names web search with its state.
Ollama is a status-only dependency. Meru never installs or starts it. merud opens its socket before it checks Ollama, so a client hears why merud can't answer instead of finding no merud at all. The check asks GET /api/version through the engine's Info, at start, then every 30 seconds, and at once when a request comes while Ollama fails. Once Ollama answers with 0.40.5 or later, merud loads the fast and embedding models and only then opens the store and builds the rest. Until then:
failed, with "Ollama isn't running at http://127.0.0.1:11434.", "Ollama 0.34.0 is too old for Meru's search model. Update it from ollama.com/download." or "Ollama … couldn't load a model: …";mcp_status answers with no servers, so meru mcp status prints the connector table;merud answers ping from the start. The desktop app's status block says "Waiting for Ollama" with the sentence, and no advice to start merud. After merud is ready it keeps checking every 30 seconds, so the connectors op stays true. A question that finds Ollama stopped, its connection refused, gets the same "Ollama isn't running, so Meru can't answer yet." and makes merud check Ollama at once.
Built in step 5 (internal/connectors/adopt.go, internal/catalog/adopt.go). A working setup keeps working. An [[mcp.servers]] entry named google or obsidian runs as it did, and its connector says "set up by hand". Nothing moves until you run meru mcp adopt <id>. Two socket ops do the work, both user commands like the memory ops, so neither goes through dispatch:
connector_adopt, with the connector's ID. Without adopt.apply it only works out the changes and sends them in an adopt event; with it, it makes them and reloads the MCP servers. adopt.values gives what the entry doesn't hold: Google's email, client_id and client_secret.connector_unadopt, the same two steps for the undo.meru mcp adopt [--yes] <id> asks for the plan, prints every change, asks, and only then applies. meru mcp unadopt [--yes] <id> does the same for the undo. The Adopt button on a Settings card and a in /mcp follow the same two steps (see Setting up a connector). Adopt, for each connector:
| Obsidian | ||
|---|---|---|
| takes | an entry that runs obsidian-mcp through npx, node or its own program, with one --vault name=path | an entry at http://127.0.0.1:8000/mcp (or localhost) |
| reads | the vault name and folder from --vault | the address, client ID and secret from ~/.config/workspace-mcp/start.sh, the script docs/google-setup.md has you write, or from --email, --client-id and a secret it asks for |
| refuses | mcp-obsidian through uvx (the Local REST API server, with other tool names), no vault or two, a folder that isn't there, a vault name obsidian-mcp refuses, env | another address, a stdio entry, a start script on another port, a missing value (it names what to give), another program on port 8000 |
| saves | nothing in secrets.toml | the secret as connector_google_client_secret, with mode 0600 |
| stops | nothing | the launchd job com.meru.workspace-mcp, if loaded (launchctl bootout), and renames its plist to .plist.disabled so it doesn't start at login |
Then, in one write of config.toml through the catalog's checked writer, Adopt comments out the entry, its own comments included, between two marker lines, and puts [connectors.<id>] right after it, with enabled = true, the values, and each tool list that differs from the manifest's:
# adopted by merud on 2026-09-30; meru mcp unadopt obsidian restores it
# [[mcp.servers]]
# name = "obsidian"
# command = "npx"
# args = ["-y", "obsidian-mcp", "serve", "--vault", "notes=/Users/dana/Notes"]
# allow = ["obsidian_list_vaults", "obsidian_search_vault", "obsidian_read_note", "obsidian_create_note"]
# end of the adopted obsidian entry
[connectors.obsidian]
enabled = true
allow = ["obsidian_list_vaults", "obsidian_search_vault", "obsidian_read_note", "obsidian_create_note"]
vault_name = "notes"
vault_path = "/Users/dana/Notes"
The reload hands the supervisor the new table: it installs the pinned version if it isn't there, checks it and runs it from then on, Google on the same port, so its sign-in callback and saved tokens still work. Adopt refuses when config has both the entry and a [connectors.<id>] table, and does nothing, with a line that says so, when the entry is adopted already. If the config write fails, it starts the launchd job again.
Never killed. A Google server you started by hand in a terminal isn't Meru's to stop. Adopt refuses while it listens on port 8000 and asks you to stop it (Ctrl+C where it runs), then to run adopt again.
Undo. Unadopt takes out [connectors.<id>], puts the entry back without the markers, reloads, so the supervisor stops its program, and then renames the plist back and starts the launchd job with launchctl bootstrap, if Adopt stopped it. After an adopt and an unadopt with no edit between them, config.toml is the same, byte for byte. The secret stays in secrets.toml, where the next adopt finds it. The connector IDs stay google and obsidian, so tool names such as google.search_gmail_messages don't change in tool_calls, transcripts or the router.
Meru runs local programs as built-in tools that you declare in config.toml. The model picks a declared command and fills in its parameters. It never writes a command line.
[[commands]]
name = "git-log"
description = "Commits from the past week in one of the user's repositories"
argv = ["git", "-C", "{repo}", "log", "--since=1.week", "--oneline"]
timeout = "10s" # default 30s, at most 300s
confirm = false # true asks before each run
cwd = "~" # the default
env_allowlist = [] # names passed through besides PATH, HOME and LANG
[commands.params.repo]
type = "path" # string, int, enum or path
under = "~/repos" # a path must resolve inside this folder
description = "The repository's folder, such as meru"
Each entry becomes one tool, cmd.<name>, whose description ends with the argv template, and whose argument schema has one required property per parameter.
Why named commands, not a command allowlist. One run_command tool with a list of allowed programs looks like deny-by-default and isn't. Half the Unix toolbox runs a shell through its flags:
| Allow this | And you have allowed |
|---|---|
git | git -c core.pager='sh -c …' log |
find | find . -exec sh -c … \; |
awk | awk 'BEGIN{system("…")}' |
tar | tar --checkpoint-action=exec=… |
ssh | ssh host <any command> |
rsync | rsync -e '…' |
sonirico/mcp-shell carried CVE-2026-55581 (CVSS 8.4) until 0.6.0: its validator checked only the first token and let /bin/bash -c through. Checking arguments means owning a validation engine that is never finished. A declared command needs none: the program and its flags come from config, and a parameter fills one argv element.
How a call runs.
exec.CommandContext(argv[0], argv[1:]...). Never sh -c, never a string.{param} placeholder becomes part of exactly one argv element, even when the value holds spaces, quotes or a semicolon. A placeholder inside a longer element, such as "--repo={repo}", is fine: the result is still one element. {{ and }} write a literal brace; any other brace fails the entry at startup.merud refuses at startup an argv[0] that runs code given as text: sh, bash, zsh, dash, ksh, fish, python, perl, ruby, node, env, pwsh, powershell, cmd and osascript, matched on the base name without case, .exe or a version (python3.12 counts). You declared the command, so this guards against a slip, not an attacker; a script of your own, run by its path, is fine.PATH, HOME and LANG, plus the names in env_allowlist, and on Windows SystemRoot and USERPROFILE. The rest of merud's environment stays out.cwd, your home folder unless set.merud keeps the first 1 MiB of stdout and of stderr and says when it cut.ok, and the model sees the code and decides what to do.Parameter types. Every parameter is required, and an unknown one fails the call.
| Type | Accepts |
|---|---|
string | non-empty text, no null byte, at most max_len bytes (default 4096). It may not start with - when it fills a whole element, where the program would read it as a flag. With pattern set, a Go (RE2) regular expression, the whole value must match it, and the tool's schema carries the same pattern |
int | a whole number, within min and max when set |
enum | one of values |
path | a path that exists and, once filepath.EvalSymlinks resolves every link, lies inside under. ~ expands, and a relative path starts at under. The argv gets the resolved path |
A path resolves before the check, because a prefix check on the path as written lets a symlink out of the tree. This mirrors write_file's rule for ~/meru-output/.
Checked at startup. merud refuses to start, naming the command, on a duplicate or badly formed name; an empty argv; a placeholder or an interpreter in argv[0]; a placeholder with no parameter, or a parameter no placeholder uses; an unknown type, or a key the type doesn't take; a path with no under; an under or cwd that isn't an existing folder; an enum with no values; min above max; a pattern that doesn't compile; and a timeout over 300 seconds. A program missing from PATH gets a warning in merud.log, not a refusal. merud reads the list when it starts; restart it after a change.
The audit record. dispatch asks the commands backend, before it writes the tool_call line, which argv the call will run, and records {"argv":[...],"params":{...}} in place of the model's arguments: in the transcript, the approval prompt and the tool_calls row. An audit log without the arguments isn't one. meru log shows the argv as a command line, and meru tools shows each command's template. The meru.dispatch span carries meru.command.exit_code and meru.command.truncated; the argv goes on the span only with capture_content = true, since a path or search term can say something about the question. The metrics use kind = "command", server = "meru" and tool = "cmd.<name>", all names from config, never the arguments.
GitHub through gh. The config template carries nine read-only commands for GitHub's gh CLI, all commented out: gh-prs, gh-pr, gh-issues, gh-issue, gh-runs and gh-repos, which ask gh for --json with a fixed list of fields and a fixed --limit, and gh-repo-stats, gh-repo-traffic and gh-release-downloads, which call gh api with a fixed path and a fixed --jq filter. A repo parameter must match owner/name and an owner one name, so the model can't pass a URL, a host or a flag; inside a gh api path, the repository can't start with a dot, so .. can't climb to another endpoint. gh keeps the token that gh auth login stored in the system keychain, and finds it with HOME alone, so Meru never holds a GitHub token. A command that writes, such as gh issue comment, stays out of the template; a user who adds one sets confirm = true.
Machine facts, snapshots, sed and awk. The template also carries 15 read-only commands for macOS, commented out. Seven report facts about the machine, each with a fixed argv: kernel (uname -a), macos-version (sw_vers), hardware-summary (sysctl with named keys), system-report (system_profiler -detailLevel mini and one section from an enum; the mini level leaves out the serial number), battery (pmset -g batt), disk-list (diskutil list) and uptime. Four take a snapshot of the machine: system-load and top-processes run top -l, which prints once and exits, find-process runs pgrep, and memory-free runs memory_pressure -Q. htop and a bare top redraw the screen until someone quits, so a command can't use them. The other four run sed or awk with the script in config: file-lines, count-lines, csv-column and csv-sum. The model fills in line numbers, a column number and a file, never script text, since a pattern of its own could end a sed address and add a w command that writes a file. perl stays refused. These commands don't skip secret files the way read_file does, so their under names ~/Documents, not the home folder.
meru setup walks you through setup in the terminal. You don't need to know how MCP works to finish it. You can run it again at any time. v0.3 doesn't start it on its own the first time you run meru.
q stops setup.config.toml yet, you pick lite (the default) or full. Meru names the profile's models and, after a yes, downloads each with ollama pull, which draws its own progress bar.~/notes) and writes config.toml from the config template, with two lines filled in: the profile and [index] folders. The template holds every key. What is on by default stays uncommented, with its default value, so you see it and can change it; what is off, such as the catalog's MCP servers, sits there commented, ready to uncomment. Setup writes the file only when none exists: rewriting yours would drop your comments, so for an existing file setup says what to edit instead. meru config template prints the template, to compare with your file or to start over. merud creates the rest of ~/.meru/ when it starts; setup doesn't write prompt.md or the built-in skills yet.[web] searxng_url. When nothing answers at Meru's own address and merud runs, it offers to have merud run SearXNG and sends connector_set (see Setting up a connector), printing each step merud reports; with merud down it names meru mcp set searxng enabled=true. When SearXNG answers HTML, it names the search.formats setting to change. Then it waits: Enter checks again, s skips. Meru works without web search (see Web search).merud running, Meru offers the Obsidian and Google connectors, one at a time. For one that is off it asks the connector's fields, a secret without showing it, and merud turns it on with them; for one set up by hand it offers Adopt, which shows merud's plan and asks again. With merud down it names meru mcp fix <id> for later. Setup prints no docker or uvx command: merud installs each connector. meru mcp add still adds any server by hand (see below).merud runs, Meru offers meru setup user, which asks your name, your email, your work, where you live and how you like answers, and saves each as a memory (see Memory).Send it? [Y/n], then writes [usage_report] send. With DO_NOT_TRACK set it writes "off" without asking. A config that was there before setup keeps its own choice (see The anonymous usage report).merud runs, Meru asks it one question so you see it working. Otherwise it tells you how to start merud. A new config.toml takes a restart of merud; a new server doesn't (see MCP).The desktop app has its own Setup screen, which needs merud running: its four steps cover the models, your folders, connections and about you, and every change goes through merud (see The desktop app). Writing the first config.toml and pulling models stay with meru setup.
The binary carries a small catalog of known servers, one for each kind of example this document uses: mail and calendar, and notes. Web search needs no server; it is built in (see Web search).
| Name | Server | Transport | Needs | Asks first |
|---|---|---|---|---|
google | taylorwilsdon/google_workspace_mcp (uvx workspace-mcp) | Streamable HTTP on 127.0.0.1:8000/mcp | a Google OAuth client, a sign-in, and you running it | sending mail, changing an event |
obsidian | mcp-obsidian, through Obsidian's Local REST API plugin | stdio | the plugin's API key | appending to a note |
Each entry lists the install command, what the server needs, and a starting allow and confirm list: reading allowed, anything that sends, writes, runs or changes something in confirm.
google is the one url entry. The server's README marks stdio as legacy, and its OAuth 2.1 mode needs HTTP, so you start it yourself and merud connects to it (see MCP). The catalog prints the command:
USER_GOOGLE_EMAIL=<your Google address> WORKSPACE_ATTACHMENT_DIR=~/meru-output/attachments \
GOOGLE_OAUTH_CLIENT_ID=<your client ID> GOOGLE_OAUTH_CLIENT_SECRET=<your client secret> \
uvx workspace-mcp==1.30.0 --transport streamable-http --tools gmail calendar drive docs --tool-tier extended
The server offers 120-odd tools across twelve Google services. --tools limits the process to Gmail, Calendar, Drive and Docs. --tool-tier extended limits it further, to the 45 core and extended tools of those four: the smallest tier that holds get_gmail_thread_content and get_gmail_attachment_content. The flag also wins over a WORKSPACE_MCP_TOOL_TIER in your environment. The catalog's allow limits the model to nine of those tools: search and read mail and threads, save a mail's attachment, send mail, list and change calendar events, search Drive, and read a doc. Sending mail and changing an event sit in confirm. So two layers apply: the server decides what exists, and Meru decides what the model sees. The OAuth client ID and secret go in the server's environment when you start it, never through Meru. Google's own Workspace MCP servers are remote only, so the catalog keeps the local one.
get_gmail_attachment_content saves the attachment as a file and returns its name, not its text. WORKSPACE_ATTACHMENT_DIR points the server at ~/meru-output/attachments, inside the output folder the file tools read. In testing, a model left to open the file itself failed: it downloaded one PDF four times, guessed the wrong folder and ran out of rounds. So dispatch reads it. When an MCP or A2A result names, word for word, a file in the attachments folder that changed after the call began, dispatch adds to that result a line with the file's path, then its text. It reads with read_file's rules, a PDF page by page, up to read_file's 12,000 characters or the room the result leaves under 16,000. A longer file ends with the offset for read_file. A file Meru won't read, such as a symlink, gets the path line and the reason. One result gets at most two files. The time rule keeps out an older attachment that a result happens to name. With no [index] folder the file tools are off, and so is this. The server deletes each saved file after an hour. The model reaches the file on disk, with no network call: the server's download URL is on loopback, and web_fetch refuses loopback.
The catalog has no shell server; to let the model run a program, declare it in [[commands]] (see Local commands).
meru setup hands Obsidian and Google to merud as connectors, which merud installs and runs itself (see Setting up a connector). meru mcp add adds a server by hand, and offers three choices for it:
google, Meru prints the command that starts the server and never runs it, and notes that the server gives you a sign-in link the first time the model uses a Google tool. When merud will probe the server, Meru saves the key to secrets.toml first, so merud can start it. Then Meru shows you the exact config block it will add, and changes config.toml only after you approve.secrets.toml lines, and names the file to paste them into. Nothing changes until you do it yourself.Meru adds the block to the end of config.toml as plain text, so your comments stay. It writes a temporary copy first and loads it, and replaces the file only when the copy loads and its servers pass the main checks merud runs: a name, one of command and url, no wildcards, and confirm inside allow. merud checks the rest, such as the loopback rule, when it loads the entry.
Outside setup, one command adds any server:
meru mcp add <catalog-name> # a catalog entry
meru mcp add stdio <name> -- <command> [args...] # a server merud starts
meru mcp add http <name> <url> [--remote] # a Streamable HTTP server you run
meru mcp add google offers the same three choices. The older forms, meru mcp add <name> -- <command> and --url <url>, still work. meru mcp shows the state of each configured server (see MCP). meru mcp list shows the catalog, then each server in config.toml with what merud says about it: connected or not, and how many tools it offers and allows. meru mcp remove <name> takes one [[mcp.servers]] block out of config.toml, with the comment lines above it, keeps every other line, and checks the result loads before it replaces the file, as the append does.
Nobody knows a server's tool names until something connects to it, and a guess would either miss or allow a tool nobody has read. So meru asks merud to probe the server first: merud starts it for a moment (or connects, for a URL), lists every tool it offers, and stops it. The probe uses the same code, trimmed environment, loopback rule and resolved secrets as the pool, calls no tool, and saves nothing. It gives up after 30 seconds; a first npx -y or uvx run downloads the server, so the error says to try again.
For each tool the probe reports two MCP hints, when the server gives them: readOnlyHint (the tool changes nothing) and destructiveHint (it may delete or overwrite). meru proposes a split from readOnlyHint alone: read-only tools go in allow, and tools that may change something go in allow and confirm, so each call asks first. A tool with no hints counts as one that may change something. destructiveHint only labels a tool "may delete" in the table. For a catalog entry the probe runs too, but the catalog's own lists win over the hints, and a tool the catalog doesn't name starts out of allow. You edit the proposal before meru writes the entry: Enter accepts, and -name, +name and ?name leave a tool out, allow it without asking, or make it ask. MCP calls these hints, not promises: a server can mislabel a tool, so the proposal is a starting point and you make the call. When the probe fails, meru says why and offers to try again, to write the entry anyway (with the catalog's lists, or an empty allow), or to cancel. With merud down, meru probes nothing and writes the catalog's lists, or an empty allow for a server outside the catalog. For a catalog server you start yourself, google, meru probes only when something answers at the URL. When nothing does, it writes the catalog's lists and says merud connects on your first question after you start the server. A URL off this machine needs --remote, and meru says that each tool call sends your data there; the entry gets remote = true.
After it writes the entry, meru asks merud to reload its MCP servers, so the new tools work without a restart.
In chat, "connect my Gmail" works too: the model calls the built-in configure tool, which adds a catalog entry, or a custom one from a name and a command or URL. configure never writes an entry whose secret is missing from secrets.toml. It tells the model to send you to meru mcp add <name> in a terminal instead, because a key typed into chat would pass through the model, the approval prompt and the transcript. After it writes, merud rebuilds the MCP client pool and swaps it in, so the new server works without a restart.
Config changes always ask. configure goes through dispatch and asks you every time, and offers only "approve once" and "deny". A session approval isn't available for it, and builtin.confirm can't switch the prompt off. Config grants lasting trust, so the model can't grant any to itself. (Built-in tools need no MCP allowlist entry. [builtin] tools lists the ones the model sees, all of them by default, and taking a name out, configure included, turns that tool off.)
Secrets stay out of config. API keys go in ~/.meru/secrets.toml, a flat list of name = "value" lines. A config value refers to one as secret:<name>, in an MCP server's env or headers or an A2A agent's headers:
env = { OBSIDIAN_API_KEY = "secret:obsidian_api_key" }
env belongs to a stdio server, which merud starts. A url entry with env fails at startup: merud starts no process for it, so the variables would go nowhere. The message names the server and points at headers, the way to send a key to an HTTP server.
merud swaps in the value when it starts a server or calls an agent, and refuses to start when group or other users can read secrets.toml (it says to run chmod 600). meru mcp add writes the file with mode 0600. Every stored value of 8 or more characters becomes [secret:<name>] before it lands anywhere; shorter values would match ordinary words:
dispatch redacts each call's arguments and result before the transcript line and the tool_calls row;merud.log redacts every line's message and attributes, an error's text included;merud;merud redacts a server's last error before mcp_status and Settings show it.All four read one redactor, which merud hands the secret set each time it loads secrets.toml, so a key added in Settings is hidden from the next line on. A config file you share or commit holds names only.
On a Mac, the installer in each release's disk image does all of this in a window, and more: it installs Ollama, starts merud at login, and hands merud the connectors you turned on (see The Mac installer).
The Mac installer, "Install Meru.app", takes a Mac with Apple silicon from nothing to a running Meru in eleven steps: Ollama and the models, folders in the index, web search, your Obsidian notes, your Apple Notes, skills and commands, Google if you want it, your profile, and merud started at login, which then installs the connectors you turned on. Each release carries it in a disk image, Meru-vX.Y.Z-macos-arm64.dmg, beside the zip files. scripts/install.sh and the meru-install skill stay for people who prefer a terminal.
On Linux, scripts/install-linux.sh is the one command: curl -fsSL https://github.com/aarora79/meru/releases/latest/download/install-linux.sh | bash. It downloads the release, checks it against SHA256SUMS, and puts meru and merud in ~/.local/bin. It then offers the desktop app, Ollama through Ollama's own script, meru setup, and merud as a systemd user unit with lingering, so it starts at boot. On a machine with no systemd running, such as a container or the Windows Subsystem for Linux (WSL), it starts ollama serve itself before it pulls the models and tells the user to start merud by hand; if a model download fails, the rest of the install still runs. It holds no model table: meru setup reads the GPU through internal/platform and offers the model that fits. The desktop app builds with cgo against GTK 4 and WebKitGTK 6.0, so the owner's Mac can't build it. The desktop-linux workflow, run by hand after a release, builds it on Ubuntu 24.04 and adds meru-desktop-vX.Y.Z-linux-amd64.tar.gz, with SHA256SUMS-desktop-linux, to the release; it changes no file the release holds. The script installs the desktop app in ~/.local/bin, a desktop entry in ~/.local/share/applications and the icon, and offers GTK 4 and WebKitGTK through apt.
Why it is its own program. The clients never run a program. The desktop app changes config only by asking merud, and meru setup writes it only through catalog. The installer has to install Ollama, pull models and load merud's launchd job before any merud exists, so it can't ask merud for those. The connectors are a different matter: their steps only gather what each needs, and the last step hands them to merud, which installs and runs them (see The hand-off). It is a fourth program, cmd/meru-installer: a Wails window with Meru.app's fonts, colours and logo, which it borrows from Meru.app's page, and a dark palette that follows the Mac's setting. Its logic lives in internal/installer, which doesn't import Wails, so CI tests every step with fakes.
| Part | Runs as | Does |
|---|---|---|
cmd/meru-installer | the window | serves the page, binds the Bridge, shows the folder dialog |
internal/installer | the installer's process | the eleven steps, the Bridge the page calls, the allowlist of programs |
| programs from the allowlist | child processes, no shell | brew, launchctl, open, ditto, xattr, codesign, sysctl, sw_vers, df |
| Ollama | Ollama.app, or a Homebrew service | answers POST /api/pull, whose stream gives each download's progress |
workspace-mcp | the launchd job com.meru.workspace-mcp | the Google server, when you set it up |
merud | the launchd job com.meru.merud | everything after the last step |
The rules it keeps. internal/policy checks each one:
internal/installer/run.go, which holds a fixed map from each program's name to the absolute paths it may live at. No other installer file imports os/exec or syscall, and the map holds no shell, interpreter or downloader. The code builds each argument as its own string, so no argument can grow into a second command. It never searches PATH: an app opened from Finder gets a short one, and with fixed paths no file dropped on PATH can stand in for a program.index, dispatch, the MCP or A2A clients or commands, and never talks to a model. It pulls models through Ollama's HTTP API on loopback, which carries no prompt.config.toml only through catalog: SetTableLists, SetTableString and AppendCommand. Each edits lines of text, keeps every comment, and replaces the file only after the result loads. A missing config.toml starts as the template. The profile goes into memory files through memory, the same files merud reads, and the installer talks to merud only over the socket.https://ollama.com/download/Ollama-darwin.zip, whose address the screen shows first. codesign --verify then checks Ollama.app's signature, and the installer deletes the app when the check fails. It sends no telemetry and never checks for updates. Its last step shows the anonymous daily usage report, ticked on, and writes the answer to config.toml; merud sends nothing until a client has shown the notice (see The anonymous usage report).https address. The page can't open an address of its own. The Apple Notes step's two buttons have a Bridge method each: one opens the fixed System Settings address of the Full Disk Access list, the other shows ~/.local/bin/merud in Finder with open -R.The steps. Each screen says what the step does, why Meru needs it, and what it downloads and how long it takes. Continue runs it and shows its progress line by line, with a bar while a model downloads. A failed step shows the reason with Retry and Skip. You can skip every step but About you.
| # | Step | What it does | What it writes |
|---|---|---|---|
| 1 | Check this Mac | reads the chip, macOS, memory and free disk with sysctl, sw_vers and df, and offers the model sets that fit | nothing |
| 2 | Install Meru | copies meru and merud to ~/.local/bin and Meru.app to /Applications, or ~/Applications when that isn't writable, with ditto; clears the quarantine mark with xattr when its box is ticked; adds the PATH line to ~/.zshrc when asked | the three programs; config.toml from the template when missing |
| 3 | Ollama and the models | installs Ollama when missing, starts it, and pulls each model of the chosen set that Ollama lacks | [models] main, when the set names one |
| 4 | Folders to search | lists the folders config has, then Documents, Desktop and Notes with file counts; the system's folder dialog adds more | [index] folders |
| 5 | Web search | keeps a SearXNG that already answers JSON on 127.0.0.1:8888, which merud then only watches. Otherwise it looks for the docker command in its usual places, and hands the SearXNG connector to the last step, turned on | [web] searxng_url; web_search and web_fetch in [builtin] tools |
| 6 | Obsidian notes | takes your vault folder from the folder dialog, checks it is a folder, and hands the Obsidian connector to the last step with it. An obsidian entry in [[mcp.servers]] stays as it is, or goes to the last step as an Adopt | nothing |
| 7 | Apple Notes | turns on the three notes tools; a button opens the Full Disk Access list in System Settings and another shows merud in Finder, to drag into it. No program can grant that access, so the step can't check it; merud checks on each call | search_notes, list_notes and read_note in [builtin] tools |
| 8 | Skills and commands | takes the built-in skills out of [skills] disabled, and offers the template's sample [[commands]]: the Mac snapshots start ticked, and a sample whose program or folder this Mac lacks is greyed out | the ticked [[commands]], uncommented, at the end of the file |
| 9 | Gmail, Calendar and Drive | walks through Google's console in three screens, takes your address, client ID and secret, and hands the Google connector to the last step with them. A google entry stays as it is, or goes to the last step as an Adopt | ~/meru-output/attachments/ |
| 10 | About you | asks your name, your email and how you like answers | memory/me/ and memory/preferences/ |
| 11 | Start Meru | writes com.meru.merud.plist from deploy/launchd/ with the paths filled in, loads it, waits for ping, hands merud the connectors, then follows merud's own first scan through index_status for up to two minutes | the launchd job; merud writes [connectors.<id>] and secrets.toml |
The last screen lists what each step did, or that you skipped it. It names ~/.meru/config.toml, with a button that opens it in your text editor, and says that Meru.app's Settings and /help in meru chat change most settings. A button opens Meru.
About you can't be skipped. Meru reads files and mail that name many people. Without your name, the model can't tell who "I" and "my" mean, and mixes you up with someone in your files. The screen says so, and says the answers stay in ~/.meru/memory/ as files you can edit, or change in Settings, About you, or with /me in meru chat. The name is required. The email is required only after the Google step, because every Google tool takes the address; the screen fills it in from that step. How you like answers stays optional. Start Meru refuses to run until About you is done. On a second run the form shows what Meru already knows.
The model table. config.Recommend picks from one table in internal/config/recommend.go, next to the profiles, so a change of default models changes one Go file. Every Mac gets lite. With 32 GB or more the installer suggests gemma4:26b-a4b-it-qat as [models] main too, with 48 GB or more qwen3.6:35b, and with 64 GB or more qwen3.6:35b-a3b-mxfp8, following the table in “Models we tried”. You can pick any row that fits, lite alone included.
Running it again. Each step first looks for its own work: the same programs in ~/.local/bin, Ollama answering with the models, folders in config, commands in config, a saved name, merud answering; for the connectors, a SearXNG answering, a [connectors.<id>] table that turns one on, or an entry set up by hand. The screen says what it found and offers Skip. Each write checks before it changes anything: a command or a server config already has stays as it is, and an unchanged answer keeps its memory file. Continue on Start Meru restarts merud, so it reads what this run wrote.
Signed ad hoc, not by Apple. Meru has no Apple developer account, so the installer and Meru.app carry ad-hoc signatures, with no certificate, and Apple doesn't notarize them. The build still signs each finished bundle, which seals its Info.plist and resources: with only the signature Go's linker puts on the program, macOS calls a downloaded copy "damaged" and offers no way to open it. An ad-hoc-signed app downloads as one Apple couldn't check, which the user can open once from System Settings, Privacy & Security, Open Anyway. "Read me first.txt" on the disk image explains that step, and the installer's first screen says why macOS asked. The Install Meru step clears the quarantine mark only from what it installed, and only when its box is ticked; the box says what the mark does.
What it doesn't do. It doesn't uninstall, update itself or look for a newer Meru. It doesn't install Docker, whose licence terms and size are yours to weigh; it links the download page and offers Skip. It can't do Google's console steps for you, and it doesn't sign you in to Google: it opens the link merud gives, and you sign in there.
Built in the second half of step 6 of the connectors plan (internal/installer/connectors.go). The Web search, Obsidian and Google steps keep what they gathered in the Bridge's memory, one hand-off per connector, and write no connector config. Once merud answers, Start Meru sends each in step order: connector_set with the values, for a connector turned on, or connector_adopt with apply, for a server set up by hand that the user chose to adopt. It shows each sentence merud reports while it downloads, installs and checks the connector, then its state. A connector merud refuses, or one that fails, doesn't stop the step: its line says what went wrong and points at Meru.app's Settings, where its card has a Fix button. Google's client secret goes to merud in the connector_set and nowhere else: not to the page, a log or config.toml. When Google then waits for a sign-in, the last screen has a Sign in to Google button: the Bridge keeps the link merud gave and opens it with open, so the page never holds an address of its own.
The installer runs no docker, uv or launchctl for a connector, so the allowlist lost docker; launchctl stays for merud's own job. An install from an older installer keeps working: its SearXNG container answers at 8888, so the Web search step finds it and hands nothing over, and merud watches it as an external SearXNG; its hand-run Google server, with start.sh and the com.meru.workspace-mcp job, shows as set up by hand, and the Google step offers Adopt in place of a second setup.
Meru searches the web through SearXNG, a metasearch engine you run on your own machine. SearXNG keeps no index of its own. It passes the search words to engines such as Google, Bing, DuckDuckGo and Wikipedia, drops the cookies and headers that identify you, and merges what comes back. It needs no account and no API key. It runs in Docker: merud runs it as a connector when config turns that on, or uses one you run (see SearXNG and Ollama), and reaches it on loopback, as it reaches Ollama.
Two built-in tools use it. Both go through dispatch, so every search, page and download lands in the transcript and in tool_calls. While web_search is on, both go with every route, direct included (see A question, end to end); without it, web_fetch waits for a tools route:
| Tool | Offered when | What it does |
|---|---|---|
web_search | [web] searxng_url is set and [builtin] tools lists it, as both are by default, and the SearXNG connector is ok | One GET to <searxng_url>/search?format=json, with a 15-second limit. It returns up to max_results results, numbered after the turn's other sources, each with its title, URL, a snippet cut to 300 characters and the date when SearXNG has one, and one web source per result (see Citations). Its text tells the model to cite results by number. |
web_fetch | [builtin] tools lists it, as it does by default | Fetches one public page (HTML, PDF or plain text, at most 16 MiB, 20 seconds; news pages run past 5 MB, almost all scripts). It works in three modes, described below. HTML and PDF go through the indexer's own readers. A page whose text comes from JavaScript goes through a headless Chrome (see Pages that need JavaScript). |
[web]
searxng_url = "http://127.0.0.1:8888" # loopback only; "" turns web_search off
max_results = 8 # 1 to 20
render = "auto" # "off" reads every page as plain HTML
[builtin] tools is web_fetch's switch; [web] render decides only whether it may render a page that needs JavaScript. A config that still says fetch or the older read_pages under [web] stops merud with a message that says to list web_fetch in [builtin] tools, or leave it out to turn page fetching off.
web_fetch takes {"url", "prompt"?, "offset"?, "save"?}:
prompt it returns the page's text, 12,000 characters per call, with the offset for the next call, as read_file does.prompt it hands the page's text, up to 48,000 characters from offset, to the fast model with thinking off, and returns From <final URL> (fetched <date>): <answer>. The instruction is short: answer only from the page, quote numbers, versions and dates as the page writes them, and say when the page doesn't say. A longer page gets an answer from its first 48,000 characters, and the result says so and gives the offset for the rest. The call gets a gen_ai.chat span under the call's meru.dispatch span; its tokens don't join the turn's usage, as the router's and the skill pick's don't. The tool description tells the model to pass a prompt for one fact or a summary, and to leave it out when it needs the text itself.save it downloads the file to <[skills] output_dir>/downloads/, at most 50 MiB and 2 minutes, through the same client and checks as a fetch. The name comes from the Content-Disposition filename or the URL's last path part, cut down to letters, digits, ., - and _; a name in use gets -2, -3 and so on, so a download never overwrites. The file gets mode 0600, and the write goes through an os.Root that refuses symlinks. The result gives the path, the size, the content type and, for HTML, PDF or text, the first 2,000 characters of its text. read_file and grep can read the downloads folder; the indexer never indexes it.The URL guard. A URL is a way out: https://attacker.example/?notes=<your notes> carries data in its path or query, and a page the model reads can ask it to build one. So web_fetch runs without asking only when the URL appeared, in the same session, in a web_search result or in something the user typed: this turn's question or an earlier one. The guard compares URLs with the scheme and host in lower case and the fragment dropped; the query counts, because that is where data would go. A URL with no query string also runs unasked when its host is one the user's own words named: the model often knows a site's canonical page, such as go.dev/doc/devel/release, when you named go.dev. A search result makes only its own page known, not its site: an attacker's page can rank in a search, and any path on that site could carry data out as well as a query string. Another page on such a site asks, with this website for this chat on offer. Any other URL asks, with no choice that covers the tool for the session, as configure does: such a choice would let every later made-up URL through. It offers four choices: once; this website for this chat; always this website; and deny. The two website choices name the URL's host, such as raw.githubusercontent.com, exactly as it is written, with no wildcard: trusting github.com trusts no other host.
merud appends the host to [web] trusted_sites in config.toml, through the same checked edit as every other list, and Settings lists the hosts with a Remove button; meru chat lists them with /sites and removes one with /sites remove <host>. An entry is a bare host name: no scheme, path, port or wildcard.Trusting a host lets the model put anything in a URL on that host, and the host's owner can read those URLs in their logs. On a large public site, such as GitHub's raw files or arxiv.org, the owner is not the one a page would leak data to. On a small site anyone runs, it would be, so the prompt names the exact host and never offers a pattern. save asks even for a known URL or a trusted host, because a download stays on disk; there it offers once, session and deny, as write_file does, and a session approval covers later saves of known URLs. A download to an unknown URL never offers the website choices: it asks every time. A scheduled job has nobody to ask, so dispatch declines a call that asks every time there, even when the job's allow lists web_fetch (see Scheduled jobs).
dispatch decides whether a tool asks per tool, from Confirm. For the guard, a backend may also have ConfirmCall(call), which decides per call and which dispatch asks first, and CallSite(call) and TrustSite(call, host, always), which name the host a call reaches and record the user's trust in it. dispatch offers the website choices only when the backend names a host, so the code that knows URLs stays in the built-ins. The built-ins keep each session's known URLs in memory: web_search adds each result it shows, and ConfirmCall adds the URLs in the call's Question, which the agent fills with the user's words (this turn's question and the earlier questions in the session's history), never with excerpts or tool results. The sets end with merud; at most 256 sessions keep one, the session used longest ago goes first, and one session holds at most 2,000 URLs.
Why built in. SearXNG's API is one GET that returns JSON. The MCP server that wraps it, mcp-searxng, needs Node.js, an npm package to pin and a child process per start; the built-in tools need a few hundred lines of Go and nothing to install. SearXNG needs no key, account or card, so web search works on day one.
What stays on the machine. searxng_url must be a loopback address, and merud refuses to start otherwise. The search client uses no proxy and follows no redirect. Your question, your files and the answer stay here.
What leaves. SearXNG sends the search words to the engines it asks, with no account and no cookies, spread across several companies. The model writes those words, or merud does on a web-first turn, so they can hold words from your question. The named rule (see Web first) sends a search with no request from you: a name your files don't cover, in quotes, with a few words of the question. A question that says "my" or "our" never goes, and neither does one about mail, a calendar or notes.
Fetching pages is on by default. Asked for the latest Go release, the lite model trusted months-old snippets and answered 1.26; the answer sat on go.dev's release page, which it couldn't read. So merud fetches public pages when the model asks, under the URL guard, and taking web_fetch out of [builtin] tools turns that off. It is the one case where merud connects off this machine with no remote = true entry. The site sees your IP address and a User-Agent that names Meru. web_fetch keeps no cookies and uses no proxy. It checks each address as it connects, after DNS, and refuses loopback, private networks (10/8, 172.16/12, 192.168/16, fc00::/7), link-local addresses (169.254/16, where cloud metadata services answer, and fe80::/10), unspecified and multicast addresses, 0.0.0.0/8 and 100.64.0.0/10. The check runs on the connection itself, so it catches a link, a redirect (the tool follows at most 5) or a DNS name that points inside your network, and the model can't use the tool to read a service on your machine or LAN. A rendered page's own requests pass the same check, through merud's proxy (see Pages that need JavaScript).
When SearXNG isn't there. merud starts anyway. The SearXNG connector checks it at start and every minute (see SearXNG and Ollama), and the model gets web_search only while the check passes. A call that comes between a failed check and the next turn's tool list fails with the connector's sentence. A SearXNG that answers HTML has JSON turned off, and the sentence names the search.formats setting in settings.yml. meru setup runs the same check in its Web search step.
Many pages send an empty HTML shell and fill it in with JavaScript: job boards such as Workday, many docs sites, most single-page apps. web_fetch runs no scripts, so it found no text there. On 1 October 2026 the Workday page for one job came back as 6.1 KB of HTML with no text, and the model answered from search snippets and got the place and the date wrong. The same page in a headless Chrome gave 10,855 characters in about 3 seconds.
So when [web] render = "auto", as it is by default, web_fetch reads the HTML first, and when that is a shell (under 500 characters of text and a <script> on the page) it loads the same URL in a headless Chrome and reads the text the page shows. A page with its text in the HTML never reaches the browser.
merud installs a pinned chrome-headless-shell from Google's Chrome for Testing into ~/.meru/runtime the first time a page needs it (about 95 MB; see The runtime folder). That first call waits up to 2 minutes, and both clients show "Installing Meru's page reader (about 95 MB, once)" under the running tool, through a progress event on the ask stream.internal/render starts a fresh Chrome with a fresh profile for each page, drives it over the DevTools Protocol through two pipes (--remote-debugging-pipe; no port), and stops it when the page is read. No browser runs between pages, and no cookie outlives a call.merud runs on loopback for that page (--proxy-server, with no exception for loopback). The proxy dials with web_fetch's own check, so a page and its scripts can't reach this machine or your network. It refuses everything until the page starts to load, so Chrome's own start-up requests go nowhere. --disable-quic and a WebRTC policy keep UDP, which an HTTP proxy doesn't carry, off the network; a test proves a page's WebRTC sends no packet. While a page loads, another program on this machine could use the proxy too, but it reaches only public addresses, which that program could reach anyway.HTML, rendered. When rendering fails, web_fetch returns the HTML's own text with a first line saying the page needs JavaScript and why it couldn't be loaded.[web] render = "off" reads every page as plain HTML. Windows has no pin yet: Go can't pass a child the two pipes there.meru.web.render.duration times each rendered page, and a meru.web.render span under the call's meru.dispatch span records the requests the proxy let through and refused.
A question about Meru itself, such as "do you send any tracking data to the cloud?" or "which model are you?", runs about_meru before the model's first round, and the turn skips the search of the files (agent/self.go). A real turn showed why. That question routed search+tools; the search found the telemetry code of a project in the user's indexed folders, about 40,000 tokens of it went into the prompt, and the model read "you" as "your code", answered about that project, and never called about_meru, though the prompt says to.
The rule needs two signs. The question addresses Meru, by name or with "you" as its subject ("do you", "are you", "who are you"), or says "your" without "my" or "our". It also names something Meru is, does or sends: its data, privacy, telemetry, model, version or name. The rule leaves out a request for a task, such as "can you search my files for telemetry" or "can you run the tests", and a question about the user's own things, such as "does my repo send telemetry?". merud makes the call itself, through dispatch, so it gets its tool_calls row and transcript lines, and the facts go into the prompt under a line that says "you" means Meru. A question that names an indexed folder, as "what database does Meru use?" does for someone who indexes Meru's own code, keeps its search too: about_meru knows the setup, the code knows the rest. about_meru's facts include what leaves the computer: the daily report when it is on, and nothing else about Meru.
A model left to decide when to search can guess wrong. In a real session with qwen3.6:35b-a3b-mxfp8, thinking off, the user asked about a product released after the model's training. Asked to search for it and compare it with Meru, the model searched for an older product with a similar name and answered about that one. After the user pasted the product's page, three follow-ups called no web tool: their history held only the questions and answers, and the model made up features. "do a web search about quick and educate yourself" routed direct at 0.55, and the model called web-research, a skill, as a tool, twice, then apologised. Only "do some deep research about quick", at tools 0.86, got two searches, four pages and a right answer.
So merud itself searches before the model's first round in two cases:
| Case | When | What merud runs |
|---|---|---|
asked | the question holds an http or https URL and web_fetch is on; or it holds no URL, asks for the web (see Routing, the fourth rule) and web_search is on; or the desktop app's scope is web | web_fetch on each URL, two at most. With no URL, web_search on the question without its URLs, the phrases that asked for the web, a closing instruction ("and tell me what it is in three lines") and the filler words at either end (see below); a follow-up too short to stand alone gets the earlier question, as a file search does, and one that speaks only of the web searches for the earlier question alone |
named | an auto turn searched your files first, no connected tool is the question's target, the question doesn't say "my", "mine", "our" or "ours", it names a thing, the excerpts don't cover it, and no earlier turn of the chat names it | web_search on the name in double quotes, then up to five of the question's other words that aren't filler |
The calls go through dispatch like any other. Their tool_call lines and tool_calls rows carry caller = "meru", so meru log shows by meru in the approval column, and each sends its tool_call and tool_result events, so the chat shows the search. What comes back sits in the prompt under "From the web", among the parts each question changes, with a rule that mirrors the one for your files: cite each source by its number, never swap in a product, company or person you know for the one the user named, and search again with other words when the results are about something else. The section holds at most 8,000 characters, in equal shares among the calls. The route becomes at least tools (direct becomes tools, search becomes search+tools), so the model can search again or read a page. A call that fails, as when SearXNG doesn't answer, leaves the section out; the model still has the tools.
The search words for an asked turn. No model writes them; merud cuts the question down with short word lists. A closing instruction goes: "and" or "then" before a verb that asks for an answer ("tell", "explain", "summarize", "give", "write", "list", "describe", "show", "say"), and a length at the very end ("in three lines", "in 50 words"). So "search the web for Acme Flow pricing and tell me what it costs in three lines" searches for "Acme Flow pricing". A follow-up that speaks only of the web searches for the session's latest earlier question that doesn't, cleaned the same way. It speaks only of the web when no words are left once the web phrase and the filler go, or when fewer than three subject words are left and one of them speaks of what Meru can reach, such as "have", "access", "use" or "go ahead". A real session drove this. After the song question in A question, end to end, the user wrote "you have accerss to web search", and merud searched for "have accerss what does the song ... acvtually mean", the follow-up's words glued to the question before it. Now it searches for "song maname maname sung by r. devi acvtually mean". A follow-up with a subject, such as "search the web for the pricing", still gets the earlier question after it.
Named things. The detector reads English and knows three shapes: a term in double quotes; a run of capitalised words, such as "Acme Flow", where a lone capitalised word that starts a sentence doesn't count and a lone word needs three characters; and a word shaped like a product name anywhere, such as "GitHub", "iPhone" or "qwen3". "I", "Meru", the months, the days, greetings and the short words a title capitalises never count.
Files that don't cover a name. The excerpts cover a name when the best one scores above 1/61 and at least one holds the name in its text, heading or path. Vector search ranks every chunk, so it always hands back a nearest one, however unrelated. Reciprocal-rank fusion gives the top chunk of one list 1/61, about 0.0164, and a chunk both lists found at least 2/110, about 0.0182, so a best score of 1/61 or less means only one search found the chunk. The keyword search matches any word of the question, "what" and "is" included, so a strong score alone doesn't show that your files know the name.
What it skips. A direct question never gets the named search: no file search ran, and the router judged it small talk. Neither does a question that points at mail, a calendar or notes, a turn in agentic retrieval, or a scope of files, talk or mail. When the tool a case needs is off, the turn goes on without the section and a debug line says why. The turn's info log line carries web_first (asked, named or none), and the turn span meru.turn.web_first.
Follow-ups remember the web. Each web call that succeeds, merud's or the model's, leaves notes on the turn's assistant line (see Session transcripts), and a later turn's history carries them after the answer. Each note's gist comes from the result as dispatch returned it, after the redaction of secrets, and holds no more than 300 characters of a page.
In Meru.app you press a microphone button, speak, and press it again. Meru turns the words into text in the composer, where you read them, fix them, and press Send. The text then goes as a typed question would. The answer model never hears the audio: speech to text is a step before the question, not part of it. meru chat keeps typing, since a terminal has no microphone without a native audio library, which the thin client can't take on.
The work lands in six steps after this design. Five are in place: the binary built by CI, the connectors' service kind and [[install.files]], the whisper connector with a model per profile, which Settings and meru mcp set whisper enabled=true turn on, and the transcribe op in merud with meru transcribe, and the button in Meru.app. One comes next: the installer step with a FAQ page.
A test on 2026-10-18 (Mac Studio, M4 Max, 64 GB, Ollama 0.40.5) tried both.
Ollama has no transcription endpoint. Its gemma4:e2b and gemma4:e4b models list audio among their capabilities, and they transcribe a WAV file passed in a message's images field, which the API docs name for pictures only. Ollama ignored every field named for audio without an error. They cost too much for the job:
OLLAMA_MAX_LOADED_MODELS models loaded, 3 per GPU by default, and a Mac with a separate answer model already has three. A voice question loaded gemma4:e2b (7.4 GB) and pushed out the router, so the question waited about 5 seconds for its first word against 0.1 seconds typed, and 13 seconds when the answer model was the one pushed out. On a 16 GB Mac, lite and gemma4:e2b together need more than the GPU may use.gemma4:e2b explained why the sky is blue. A system message stopped it, and half a second of silence at the end stopped it losing the last word, but each new model would need both checks again.whisper.cpp's whisper-server does only speech to text, so it has nothing to obey. It runs in its own process, outside Ollama's count, and on the same Mac it transcribed a 26-second clip in under half a second:
| Profile | Model file | On disk | In memory | Languages |
|---|---|---|---|---|
lite | ggml-base.en.bin | 148 MB | 445 MB | English |
full | ggml-large-v3-turbo-q5_0.bin | 574 MB | 890 MB | many |
On a real recording through a USB webcam's microphone, the full model made no mistake and the lite one heard "Porto" as "portal". The connector's model setting, [connectors.whisper] model, picks the other file. Both come from huggingface.co/ggerganov/whisper.cpp at commit 5359861c739e955e79d9a303bcbc70fb988958b1, each pinned by SHA-256.
whisper.cpp publishes whisper-server for Linux and Windows but not for macOS, where it ships only a library for Xcode apps. merud is built without cgo and can't load it. So a GitHub Actions workflow in Meru's repository, whisper-server.yml, run by hand, builds it:
v1.9.5 source tarball, checked against a SHA-256 kept in the workflow (commit d2a764c648779feb36d44363f212a29b00aad1af);macos-14 runner, for Apple silicon, with Metal, the Metal shaders inside the binary and static libraries, so the result is one file that links only to macOS's own frameworks;GGML_NATIVE=OFF, so the compiler doesn't tune the code to the runner's CPU, which could crash it on an older Mac, and for macOS 13.3 and later.The workflow checks that otool -L lists only system libraries and that the program transcribes a test clip to the expected words. It publishes the file, SHA256SUMS and whisper.cpp's MIT licence to a release of its own, whisper-server-v1.9.5, which nothing moves or deletes, and records which commit and workflow built the file with GitHub's build attestation. The connector pins the file's SHA-256. A new whisper.cpp version is a pull request that changes the workflow's pin and the manifest's.
The first run published whisper-server-darwin-arm64 on 2026-10-18, SHA-256 8a41d4c21710a0325e35a5a5b66548b9d952e6832e2c13de81ccb64c3a56f2db, built from commit 2a2736e. On the M4 Max it used Metal, took 897 MB with the full model, and transcribed the real recording as before. It still needs a run on an M1 or M2 before the connector ships.
The same workflow builds whisper-server-linux-amd64 on an ubuntu-22.04 runner and publishes it as a release of its own, whisper-server-v1.9.5-linux-amd64, so the Mac's release never changes. It builds for the processor, without CUDA: CUDA would tie the file to the CUDA libraries, and the base model heard a 4-second clip in 1.4 seconds on a 4-core server processor. Static libraries, no OpenMP, and the C++ library linked in leave a 5 MB file that needs only glibc 2.35 or later; the workflow checks that with ldd, then transcribes a clip pico2wave speaks. The same build on an Ubuntu 24.04 machine heard that clip word for word.
The manifest's launch command is {pkg}/{binary}, so each platform runs the file it downloaded. The first Linux run published whisper-server-linux-amd64 on 2026-10-28, SHA-256 396a63f7da5c0874ee591bca58a7fb4f7d15a2128bc7d599ea01d0d565934805, a 5.1 MB file that needs only glibc. Windows comes later.
whisper is a connector (see Connectors and the supervisor), off until [connectors.whisper] enabled = true. It uses the service kind and [[install.files]] (see The manifest), and merud runs it with the Service supervisor (internal/connectors/service.go):
[[install.files]] and has a choice field, model, whose choices are their names. Only the chosen file downloads. merud hands the supervisor the profile's choice as the field's default, base.en for lite and large-v3-turbo for full, and a model key in the table wins over it. One setting, then, in the place every connector keeps its settings, and the Settings card draws it as a choice.whisper-server answers any web page in the browser (Access-Control-Allow-Origin: *), and its /load endpoint loads a model from any path it is given. So each start passes --request-path /{token}, where {token} is 128 random bits merud makes for that start. Every route then sits under that path, and /inference, /load and /health without it answer 404. Only merud knows the path; another user on the same Mac could read it in the process list, as for any command line.The launch is whisper-server --host 127.0.0.1 --port 8178 -m {file.model} --request-path /{token}, so the server listens on this machine only. Turning it on downloads about 160 MB for lite or 580 MB for full: on the development Mac the first took 18.5 seconds and the second 58. A model the user picks later downloads beside the first one, which stays until the runtime folder goes. A model that isn't one of the two is refused before config changes.
The manifest has downloads for darwin_arm64 and linux_amd64. On any other computer the connector stays off, even when switched on, and says why: "Speech to text isn't available on this computer yet: Meru has no windows_amd64 build of it." The microphone shows the same sentence, so Meru never asks anyone to turn on a connector that can't run, or tries an install that can't work.
TestIntegrationWhisper, behind the integration build tag, installs the real connector into a temporary home, starts it through the supervisor, and checks that it writes down a clip say spoke (pico2wave on Linux) and that /inference and /load answer 404 without the token.
The app records 16 kHz, mono, 16-bit PCM and wraps it as a WAV file, for at most 60 seconds: 1.9 MB. The Bridge sends it to merud in a transcribe request, in Request.Audio, a pointer to a struct that holds the bytes, so a Request stays comparable with ==. Go's encoding/json writes the bytes as base64, 2.6 MB. Events and replies keep the socket's 1 MiB limit on a line; a request line may run to rpc.MaxRequestLine, 4 MiB.
merud's handleTranscribe (cmd/merud/speech.go) does four things:
speech.CheckWAV reads the RIFF header: it walks the chunks to fmt and data and divides the sound's bytes by the bytes per second. It refuses anything that isn't PCM or float WAV, such as an .m4a, which whisper-server would refuse anyway, and a recording over 60 seconds, with half a second of slack for a recorder that stops late.Service's Use gives the base URL, with the start's token path, and starts the server when it isn't running. With the connector off, installing or failed, its sentence is the error.speech.Transcribe posts the file to <base>/inference as a form, with temperature=0, so the same recording gives the same words, and response_format=json, through a client that follows no redirect.speech.Clean drops what Whisper writes in square brackets and treats text with no letter or digit as nothing heard: on silence base.en writes [BLANK_AUDIO] and large-v3-turbo writes .. The reply is one transcript event, its Text empty when nothing was heard, then done.Speech to text isn't part of the Engine interface, which serves Ollama and keeps its four methods.
meru transcribe <file.wav> sends a file through the same op and prints the words, or "(Meru heard no words.)". It lets a user try speech to text before Meru.app's button, and a script use it.
On the development Mac, through the scratch merud with large-v3-turbo: the first recording, 20 seconds from the USB webcam, took 3.6 seconds, which includes starting the server and loading the model; after that each took 0.3 to 0.4 seconds, the 26.5-second clip included. Silence came back as no words, an .m4a file and a 61-second one as refusals.
SpeechStatus whether the whisper connector is ok; when it isn't, the line above the box shows the connector's sentence, such as "Speech to text is off. Turn it on in Settings, Connections.", and nothing records. Otherwise the button turns red and pulses, and the line reads "Listening… 12 s. Press the microphone again to stop". A second press, or 60 seconds, stops it. "Turning speech into text…" follows, then the words land in the box after any text already there, with the cursor at the end, and the line says "Check the words, then press Send." Nothing sends without that press. No words gives "Meru heard nothing. Try again closer to the microphone."web/js/voice.js with getUserMedia and MediaRecorder, which in the macOS WebView makes AAC. When it stops, decodeAudioData decodes it and an OfflineAudioContext of one channel at 16 kHz mixes and resamples it in one pass, faster than real time; a few lines of JavaScript write the 44-byte WAV header and the 16-bit samples. No audio worklet and no native recorder were needed. The microphone is let go as soon as recording stops, so macOS's indicator goes out.Transcribe takes the WAV as base64, decodes it, refuses more than 3 MiB, and sends the transcribe op with a two-minute timeout; it keeps no copy.Permissions (Wails v3 beta.28) allow the microphone without WebKit's own prompt, which would ask on every launch, and deny the camera. macOS still asks once, from Info.plist's NSMicrophoneUsageDescription: "Meru turns what you say into text on this Mac. The sound never leaves it." Wails' WebView exposes navigator.mediaDevices on its own wails:// page, so getUserMedia works as in a browser.Nothing of the sound. The WAV lives in the app's memory and in merud's for the one request, and nothing writes it to disk: no file, no transcript line, no tool_calls row, since speech to text isn't a tool call. The text joins a chat only when you send it, as typed text does. merud logs one info line per request with the model, the length of the audio, the time taken and the outcome, never the words:
level=INFO msg=transcribe model=ggml-large-v3-turbo-q5_0.bin seconds=20.0 ms=3525 outcome=ok
The supervisor logs whisper-server's own output at debug level. Version 1.9.5 prints its startup and request lines but not the words it heard; every server log from the tests on 2026-10-18 was searched for them.
Meru hands tasks to other agents over A2A, an open protocol for agent-to-agent work. As with MCP, Meru is only a client; it doesn't serve A2A. The client comes from the A2A project's Go SDK, github.com/a2aproject/a2a-go/v2 (v2.7.0), and speaks version 1.0 of the protocol over JSON-RPC or REST. An agent whose card speaks only an older version fails with an error that says so.
The model sees each allowed agent skill as one more tool, named a2a.<agent>.<skill>, that takes one argument, {"message": "..."}, and returns the agent's answer as text. A2A has no field that picks a skill: the agent reads the message and decides. The skill in the tool name picks the description the model sees and the allow entry the call needs. The call goes through the same dispatch function as MCP tools, so it gets the same allowlist check, confirmation, tool_calls row (with kind = "a2a") and trace span.
[[a2a.agents]]
name = "research"
url = "http://127.0.0.1:9100" # Meru reads the agent card from here
allow = ["summarize"] # skills from the agent card
confirm = []
remote = false # true only if the agent isn't on loopback
timeout = "60s" # the default
dispatch line, the same boxes an MCP call passes through.Agents are deny-by-default too. Meru can reach only the agents in config, and only the skills in allow become tools. An agent on another machine may use a cloud model, so your data would leave the machine. Reaching one takes remote = true; without it, merud refuses any agent URL that isn't loopback. As for MCP, remote covers only where merud connects, and a config that still says network fails with "network was renamed remote".
merud starts without contacting any agent. It reads an agent's card the first time a turn needs its tools, so an agent that starts after merud shows up on the next turn. A failed fetch waits 10 seconds before the next try; inside that wait the agent offers no tools and a call fails at once.SendStreamingMessage, under the same per-call timeout as a tool (60 seconds unless the entry sets timeout). When the card says the agent can't stream, the SDK sends a plain request instead, so one code path covers both. When the timeout passes or you cancel the turn, Meru asks the agent to cancel the task.remote = true. The client follows no redirects, because a redirect could carry the entry's headers, which may hold an API key, to another host.merud runs jobs on a schedule: a prompt, a prompt with a named skill, or one declared [[commands]] entry. It is the first half of v0.5, built in steps under #167: the schedule rules in internal/jobs came first; now merud runs every kind of job in [[jobs]], a prompt, a skill or a command, with allow and output, files each run in the Jobs folder, and answers every op below, with a Jobs section in Settings and /jobs in meru chat to add, edit, pause, remove, run and stop jobs, and schedule_job adds one when you ask in chat.
A job is a name, a schedule and one action, declared in config.toml:
[[jobs]]
name = "morning-brief"
schedule = "0 7 * * 1-5" # 7:00 on weekdays, this computer's time zone
prompt = "Brief me on today's calendar, unread mail and anything due this week."
allow = ["write_file"] # tools it may use without asking once
output = "briefs/{date}.md" # optional; under [skills] output_dir
[[jobs]]
name = "go-news"
schedule = "0 9 * * 2" # Tuesdays at 9:00 ...
every_weeks = 2 # ... every other week
from = "2026-10-27" # the first day it may run
skill = "web-research"
prompt = "Summarize what changed in the Go release notes."
[[jobs]]
name = "backup"
schedule = "30 23 * * *"
command = "backup-notes" # a [[commands]] entry; no model runs
| Key | What it says |
|---|---|
name | letters, digits, - and _, unique; at most 50 jobs, so the metric's job attribute stays a small set |
schedule | five-field cron: minute, hour, day of month, month, day of week; *, numbers, names (mon, jan), ranges, steps (*/15) and lists |
every_weeks, from | run only every N weeks; the weeks count from the Monday of from's week, and nothing runs before from |
prompt | the question the run asks, through the agent loop |
skill | a skill the run loads without the pick step; needs prompt |
command, args | a [[commands]] entry and its parameters; no model runs |
allow | tools the run may use without asking, when they would ask once |
output | a file under [skills] output_dir the answer also goes to; {date}, {time} and {job} fill in |
enabled | false pauses the job |
Each cron field becomes a set of allowed values, kept as a bitmask, and Next finds the first matching minute after a time, skipping whole months, days and hours that can't match. It builds each candidate from the wall clock with time.Date, so daylight saving time does what people expect: 2:30 on the night clocks jump from 2:00 to 3:00 doesn't happen, so a 2:30 job skips that day, and 1:30 on the night it happens twice runs once. A schedule that matches no date within five years, such as 31 February, is refused when config loads. When the two day fields are both restricted, a day matches if either does, as in cron. Describe writes the schedule in words for the clients: "7:00 on weekdays", "9:00 on Tuesdays, every other week from 27 October 2026".
A loop in merud asks jobs.Due about every enabled job every 30 seconds, comparing wall-clock times. A ticker that compares the clock finds a run that fell due while the Mac slept within 30 seconds of waking, whatever Go's timers do across sleep. Due takes the job's schedule, its last run and the time now:
jobs.CatchUp). The job doesn't run; merud logs the slot it skipped and moves on, so yesterday's brief doesn't arrive at 9 p.m.The last run of each job comes from the turns table at startup, which a rebuild fills from the transcripts. A run moves the job's last run when it starts, so a run that fails waits for its next time. Runs share the warm model and go one at a time; a job whose last run still runs skips that slot. A question you type isn't blocked: Ollama serves both.
Each run is a chat. Its session sits in a chat folder named Jobs, which the first run creates; both clients show it first in the chat list, and merud refuses to rename or remove it while [[jobs]] holds a job. A run's title is the job's name and the time, such as "morning-brief · Fri 24 Oct 07:00", so a job's runs read as a log, newest first. The user line records the job's name, so the turns row carries it and a rebuild knows each job's last run.
agent.Handle with source job, as a typed question would, within [agent] turn_timeout. Nothing streams, since nobody watches.[[commands]] entry through dispatch, with no model: a user line names it, and its output, cut to 4,000 characters, is the answer.output, when set and the run ended ok, writes the answer with one write_file call through dispatch, caller meru, so the file lands in the audit log and stays under output_dir.Nobody can answer an approval during a job, so dispatch treats a job's calls by how they would ask:
| The call | In a job |
|---|---|
| needs no approval | runs |
asks once (confirm lists it, or a command has confirm = true), and the job's allow names it | runs; the approval line reads once |
asks once, and allow doesn't name it | declined; the answer says it skipped the call |
asks once, allow names it, and the job has read outside content (mail, a web page, another server's answer) | declined, whatever allow says; nobody can see what that content asked for |
asks every time: configure, web_fetch on a URL nobody gave, a download, an MCP tool in always_confirm | declined, whatever allow says |
The last row keeps the URL guard whole: an unattended job can't send data out through an address the model made up, and a page it reads can't change config. A website in [web] trusted_sites reads without asking, in a job as anywhere. A job that reads mail or web pages can be told by them to do something, so once a job has read outside content, its allow list stops answering: a send after a mail search is declined. A digest job writes its result to a file through output instead of sending it. A tool that needs no approval still runs, so keep a tool that sends in confirm.
| Op | What merud does |
|---|---|
jobs | lists each job with its schedule in words, next and last run, the last run's outcome and chat, and whether it runs now |
job_set | adds or replaces one job in config.toml through a checked edit, which keeps the comment above it; with dry_run it only checks the job and returns its schedule in words, which the add form shows as you type. enabled = false pauses; resuming doesn't catch up the slots missed while paused, and a changed schedule counts from the edit |
job_remove | takes the job out of config.toml; its runs stay in the Jobs folder |
job_run | runs the job now, outside its schedule; this doesn't count as its last run |
job_cancel | stops the job's run in progress, as Ctrl-C stops a question: the run ends cancelled, its chat keeps what it wrote, and the schedule stays |
Meru.app has a Jobs section in Settings, with an Add a job form, and Pause, Edit and Remove on each job. meru chat has /jobs: Enter runs the marked job now, c stops its run, p pauses or resumes, d d removes, and a and e walk through a new job's or the marked job's name, schedule, prompt and skill. A job's command, arguments, allow and output are set in Settings or config.toml. A request's job fields come only from merud's own scheduler; the socket refuses them from a client, so no client can make an ask that borrows a job's approvals.
You can also ask: "every other Tuesday at 9, summarize the Go release notes". The built-in tool schedule_job proposes the job, and asks every time, as configure does: the card shows the job with its schedule in words, such as "9:00 on Tuesdays, every other week from 27 October 2026", and nothing is saved until you say yes. It sets no allow list; what a job may do unwatched is set in Settings or config.toml. A question with "schedule", "daily" or "weekly", "every" or "each" before a time word such as "weekday" or "morning", or "job" with a time of day such as "8am", gets the tools route, so a direct guess still offers the tool. A job's own turns never see schedule_job or configure, so no job makes or changes jobs.
It sends no notifications and keeps no digest yet; those and meru brief are planned for v0.6. A job never waits for an approval. It runs no shell line, only declared commands, and a script runs by its own path. It has no seconds, no @reboot, and no time zone but the computer's own. The operating system's service manager (launchd, systemd) restarts merud after a reboot; the scheduler lives inside merud, so jobs use the loaded models and land in the same audit log and traces.
Every stage of a turn emits OpenTelemetry (OTel) data, the open standard for timing and counting what software does. It emits two kinds. A metric is a number aggregated over many turns, such as latency per model. A trace records one turn, split into timed spans, one per stage: routing, retrieval, each model call and each tool call. The model-call metrics cover the main model's rounds and the summarizer; the router, the skill pick, web_fetch's prompt and every embedding call get spans only. Meru needs no dashboard program to show them: the Usage screen in both clients draws its charts from meru.db, and a Prometheus you run can read the same metrics from merud (see Reading the metrics).
Meru collects this data about itself, and none of it leaves your machine. The anonymous daily usage report is a separate, much smaller thing, with rules of its own (see The anonymous usage report). The data here goes only to an endpoint you run on this machine:
observability.otlp_endpoint. With neither otlp_endpoint nor prometheus set, metrics go to a no-op provider and spans record nothing. Each span still gets a trace ID, so the log and the transcript can name the turn. Instrumentation then costs almost nothing.merud refuses to start if the endpoint isn't a loopback address. No setting sends metrics or traces anywhere else./metrics page stays off until you set observability.prometheus to a loopback host:port, and merud refuses any other address. It answers GET and HEAD on /metrics alone, and only to a request whose Host names this machine, so a web page can't read it through your browser by pointing its own domain name at 127.0.0.1.capture_content = true. They always carry token counts, durations, model names and tool names, which reveal nothing about what you asked.[observability]
prometheus = "127.0.0.1:9464" # serves /metrics; loopback only; unset = off
otlp_endpoint = "http://127.0.0.1:4318" # OTLP/HTTP; loopback only; unset = off
metrics_interval = "10s"
traces = true
capture_content = false # prompt/response text in spans
Each turn produces one trace. A question over the socket starts at rpc.request; a scheduled job's run (v0.5) starts at meru.job, with the run's meru.turn under it. In v0.3 a turn on the search+tools route with one round of tool calls looks like this:
search+tools route with one tool round. The router's one-token call and each round of the main model get a gen_ai.chat span with its HTTP request under it; the search sits before the first round, and each tool call gets a meru.dispatch span between the rounds. The trace ID also sits on the transcript lines and every log line of the turn, so a slow bar in a trace viewer leads to the exact lines, and a line leads back to its timing.A turn on the direct route has no meru.search, unless the question names an indexed folder or asks about past chats; with [index] retrieval = "agentic" no turn searches first, and a question with an attached picture gets a meru.search span for the image search. direct and search offer fewer tools (datetime, about_meru, the web tools, and on search the file tools), so they can still have tool rounds. The calls of one round run at the same time, so their meru.dispatch spans overlap. v0.4 adds a meru.recall span under meru.turn for memories, on every turn, and a meru.retrieve.sessions span on turns that search first, for past sessions. The skill pick has its own meru.skills.pick span beside meru.route, with the fast model's gen_ai.chat under it.
Indexing has traces of its own, apart from any turn. A scan of every folder is one meru.index.scan span (folders, whether it re-embeds, and the counts it ends with), with a meru.index.file span for each file it reads (kind, outcome, chunks, bytes, and the skip reason). Indexing one path, as the watcher and meru index <path> do, records only meru.index.file spans. The startup scan and each file the watcher re-indexes start a new trace; meru index puts its spans under its own rpc.request.
Model spans follow the OTel GenAI semantic conventions (gen_ai.operation.name, gen_ai.request.model, gen_ai.request.max_tokens, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.response.finish_reasons) and add meru.tier plus Ollama's own timings: meru.ollama.load_ms, meru.ollama.prompt_eval_ms and meru.ollama.eval_ms. The HTTP spans follow the OTel HTTP conventions. A failed span records the error and sets its status to Error; a cancelled one gets a cancelled event instead.
Every tool call gets a meru.dispatch span, whatever its kind. It carries gen_ai.tool.name, meru.tool.kind, meru.tool.server, meru.tool.outcome and meru.tool.approval, the same keys the tool metrics use, so a dashboard can go from a metric to its traces. One value differs: the span's gen_ai.tool.name is the full name, such as google.search_gmail_messages, while the metric's tool is the bare name. The backend's own span nests under it:
tools/call <tool> and carries mcp.method.name and gen_ai.tool.name.invoke_agent <agent>, with gen_ai.operation.name = invoke_agent, gen_ai.agent.name, server.address and server.port. Meru adds meru.a2a.skill, meru.a2a.task.id and meru.a2a.task.state.meru.dispatch span, with three exceptions: web_fetch with a prompt adds the fast model's gen_ai.chat span, and on a page that needs JavaScript a meru.web.render span; search_files adds meru.retrieve with its embedding call; and search_images adds its embedding call.meru.command.exit_code and meru.command.truncated to the meru.dispatch span, which has no child.MCP and A2A spans also carry meru.tool.server and meru.tool.allowed. A failed call's error.type says how it failed: tool_error (the MCP convention's name) when the server or agent reports failure, Meru's own denied, unavailable or timeout, or, for an MCP protocol error, the JSON-RPC error code. Arguments and results go on the spans only when capture_content = true. merud writes each trace ID to the session transcript, messages and tool_calls, and to every log line of the turn.
Metrics use the standard GenAI names where a convention exists, and meru.* names for the rest.
| Metric | Type | Attributes | Answers |
|---|---|---|---|
gen_ai.client.token.usage | histogram | model, tier, operation, gen_ai.token.type (input/output) | tokens per call |
gen_ai.client.operation.duration | histogram | model, tier, operation | model call latency |
gen_ai.server.time_to_first_token | histogram | model, tier | the v0.1 "first token < 1 s" target |
gen_ai.server.time_per_output_token | histogram | model, tier | decode speed |
meru.engine.load.duration | histogram | model | cold loads Ollama had to do (should be ~0) |
meru.route.decisions | counter | route, outcome (ok/low_confidence/degraded) | how often each route wins, and how often the router is unsure |
meru.turn.duration | histogram | route, source (cli/tui/desktop/job), outcome (ok/error/cancelled/timeout/cut_off/window_full/capped/gave_up/bad_output) | end-to-end latency |
meru.turn.iterations | histogram | route | loop depth |
meru.context.tokens | histogram | section (skills/memories/sessions/chunks/web/history/tools) | data for the context budget policy; the fixed part of the system prompt isn't measured yet |
meru.tool.calls | counter | meru.tool.kind (mcp/a2a/builtin/command), meru.tool.server, gen_ai.tool.name, meru.outcome (ok/error/denied/declined/cancelled/timeout) | tool usage and failures |
meru.sessions | counter | source | sessions started |
meru.turn.tokens | counter | gen_ai.token.type (input/output), route, source | the main model's tokens per answered question, summed over its model calls |
meru.turn.docs | histogram | route | distinct files each answered question read |
meru.tool.duration | histogram | meru.tool.kind, meru.tool.server, gen_ai.tool.name | tool latency, for calls that ran |
meru.model.malformed_calls | counter | model | tool calls the main model wrote that Meru couldn't run as written |
meru.retrieval.duration | histogram | stage (vector/fts/fusion/memories/sessions/images) | retrieval cost (v0.2; memories and sessions stages v0.4; images v0.4.13) |
meru.speech.duration | histogram | model (the whisper connector's two files), outcome (ok/error/empty/too_long/cancelled) | how long one recording takes to become text, the server's start included |
meru.web.render.duration | histogram | outcome (ok/error/timeout/cancelled) | how long a page that needs JavaScript takes in the page reader, Chrome's start included |
meru.rpc.active_streams | up-down counter | — | open client sessions |
meru.scheduler.job_runs | counter | job, outcome | (v0.5) scheduled work: did each job run, and how did it end |
meru.scheduler.lateness | histogram | job | (v0.5) how late runs start after sleep or a restart |
The OTel Go runtime package adds heap, garbage-collection and goroutine metrics.
What counts as a malformed call. The agent counts one for each of these, in the round where it happens:
ErrModelOutput in the middle of a stream: its parser couldn't read what the model wrote, most often a tool call. The retry that follows counts again if it fails too.dispatch also refuses as denied.A repeated call isn't malformed: the model wrote it well, and the agent hands back the earlier result (see Agent loop). The counter carries the model name alone, which config bounds; the tool's name, which a model can make up, stays off it. The answer line's bad_calls holds the same count per turn, for /usage by model.
Token counts come from Ollama's counters on each response; Meru doesn't estimate them. merud measures time to first token from the start of the request to the first streamed text, so it includes time spent waiting in the queue and reading the prompt.
Keep attribute values to small, fixed sets such as model, tier, server, tool, route and outcome. Every distinct value creates a separate time series in the metrics store, so a session ID or file path there would grow it without limit. Put session IDs, file paths and text on spans. Server and tool names come from config, with one exception: a denied call names a tool the model made up, and a model can make up any number. The tool metrics record such a call's server and tool as other; its tool_calls row keeps the real names. meru.tool.duration covers only the time a tool ran, so a call that never ran (denied, declined, or cancelled before it started) adds to meru.tool.calls and records no duration.
Meru ships no dashboard program. There are three ways to read the numbers, and the first needs nothing installed.
/usage in meru chat draw their charts from the turns and tool_calls tables in meru.db, which rebuild from the transcripts. The socket op usage with kind detail returns the data: 30 days of tasks, tokens and time to first token (p50 and p95 by nearest rank, in local days), the ten slowest tasks of the last 7 days, the twelve busiest tools by outcome, use by answer model, and the /metrics address. An older merud answers that kind with the plain windows, and both clients then say the charts need a newer merud./metrics for Prometheus. With prometheus = "127.0.0.1:9464", merud serves every metric above in Prometheus's text format, version 0.0.4, at http://127.0.0.1:9464/metrics. A manual reader beside the OTLP push collects the instruments on each request, and merud writes the text itself, with no Prometheus library. Names follow the OpenTelemetry Collector's rule: dots become _, the unit adds _seconds or _bytes, and a counter ends in _total, so meru.tool.calls is meru_tool_calls_total and meru.turn.duration is meru_turn_duration_seconds. A target_info line carries service_name="merud" and the version. Counters start from zero when merud restarts; rate() and increase() allow for that. A taken port stops merud at start, with the key to change.otlp_endpoint pushes metrics, and traces when traces = true, to any OTLP/HTTP collector you run on this machine, such as an OpenTelemetry Collector in front of Jaeger. Traces go only this way. When the push fails, merud logs it once an hour, with the hint to blank otlp_endpoint if no collector runs there./metrics and OTLP can run at once; each reader sees every instrument, so they report the same numbers. A few PromQL queries for the page:
# Tasks per day
sum(increase(meru_turn_duration_seconds_count[1d]))
# Time to first token, p95 over the last hour
histogram_quantile(0.95, sum by (le) (rate(gen_ai_server_time_to_first_token_seconds_bucket[1h])))
# Tool calls that failed today, by tool and outcome
sum by (gen_ai_tool_name, meru_outcome) (increase(meru_tool_calls_total{meru_outcome!="ok"}[1d]))
merud writes key=value lines with log/slog to merud.log in its home folder, and doesn't export them. [log] level picks how much it writes; merud -v forces debug. merud.log has mode 0600. Under launchd, anything merud prints before that log opens goes to merud.out.log and merud.err.log; the plist's Umask makes launchd create them 0600 too, and merud sets either to 0600 at startup if an older install left it readable by other accounts. The systemd unit sets UMask=0077 for the same reason.
info (the default): startup settings, each model warm-up, the store's counts, each index scan's counts, shutdown, a route line per decision with its whole distribution, and one turn line per turn with its route, outcome, total time, time to first token and token counts.debug: adds a line for each stage of a turn: the request, the session, the history, each transcript write, the search's result count, the prompt's size, each Ollama call (status, time to headers, first token, Ollama's own timings, tokens per second) and the reply.Every line of a turn carries its trace_id, the same ID the trace and the transcript lines hold. No level writes question or answer text. With capture_content = true, the debug lines add the first 200 characters of each.
Once a day, merud can send one anonymous report to a collector the project runs, so the project can count how many installs run Meru, on which systems, and which releases they keep. It is the only thing Meru sends about itself. The owner chose it on 11 November 2026, in place of "no telemetry leaves the machine, ever" (#251).
The body is thirteen fields of JSON, about 250 bytes (report version 2, from v0.7.7; v0.7.6 sent the first seven as version 1):
{"v":2,"meru":"0.7.7","os":"darwin","arch":"arm64","profile":"lite","age":"month","questions":"1-5",
"active_days":"3-5","streak":"2-4","previous":"0.7.6","week_first":true,"month_first":false,"first":false}
| Field | What it holds | Values |
|---|---|---|
v | the report's format | 2 |
meru | the release | such as 0.7.7 |
os | the system | darwin, linux, windows |
arch | the chip's family | arm64, amd64 |
profile | the model set | lite, full |
age | how long ago a client first showed the notice | week (under 7 days), month (under 31), year (under 366), older |
questions | the questions answered the day before, in UTC, leaving out scheduled jobs | 0, 1-5, 6-20, 21+ |
active_days | the days among the seven before today with a question, jobs left out | 0, 1-2, 3-5, 6-7 |
streak | the ISO weeks in a row, Monday to Sunday in UTC, with a report, this one included | 1, 2-4, 5-12, 13+ |
previous | the version in this install's last report | none, or such as 0.7.6 |
week_first | this is the install's first report of the ISO week | true, false |
month_first | this is its first report of the UTC month | true, false |
first | this is its first report ever | true, false |
It holds no ID, no question, no answer, no file name, no setting and no time of day. merud works out the last six from usage-report.jsonl and the turns table; previous is sent only when it is a release number, so a hand-edited record can't put text in a report. Each install sends at most one report a UTC day, so the collector counts the installs that reported each day. The three flags count across days with no ID: each install sets week_first on exactly one report a week, month_first on one a month and first on one ever, so counting the rows with a flag counts each install once in that window. The FAQ, docs/faq/usage-report.md, gives each count and its SQL. A new field or value needs a new v, and a new v shows the notice again before anything sends under it. A golden test in internal/usagereport pins the fields.
merud checks every 30 minutes, comparing dates, so a computer that slept past midnight sends within half an hour of waking. It sends only when all of these hold:
[usage_report] send = "on".DO_NOT_TRACK is unset, or 0, in merud's environment.v0.7.6. A development build never sends.meru chat or Meru.app showed the notice for this v on an earlier UTC day. The first report waits a day, so a user who sees the notice and turns it off that day sends nothing.merud picks a random minute up to two hours after midnight UTC each day, so the time a report arrives says nothing about the user's day.A failed send tries again at the next check. Nothing queues, so a missed day stays missed.
Send today's now. The Usage screen's Send today's now, t in /report and meru report send send today's report at once. They skip the two waits, the day after the notice and the send minute, and keep every other rule, so a click never sends a second report in one day and the daily counts still count installs. The button stays greyed out while a click wouldn't send, and a refused send says why.
meru setup and the Mac installer's last step show the fields and an example body, with the answer on, and write send = "on" or "off". With DO_NOT_TRACK set, they write "off" without asking.send line, which reads as "", not chosen. Both clients ask, and merud sends nothing until the user says yes. An install script with no terminal writes the template's send = "", so it behaves the same way.meru report on before an app ran, marks the notice seen, since the user who chose it knows of it. "Off" marks nothing.[usage_report], and a policy test keeps it that way.One-shot meru and meru run --json never count as showing the notice, so an install that never opens meru chat or the app never sends.
Both clients show a banner above the chat until the user acts on it. For a new install it says the report is on and offers See the report, Turn off and Got it; after an upgrade it asks, with See the report, Share and Don't share. See the report shows the exact next body. The Usage screen has an "Anonymous daily count" section with the choice, why nothing will go if something holds it back, when the next one goes, the recent entries, each with the body sent, and Send today's now. meru chat has /report, and meru report [on|off|send] does the same from a terminal. Every client reaches it through one op, usage_report.
~/.meru/usage-report.jsonl, mode 0600, holds one line for each event: seen when a client showed the notice, dismissed when the user closed it or chose, and sent or failed for each try, with the exact body. Nothing about the report lives in meru.db. Deleting the file means no client has shown the notice, so nothing sends until one does.
merud posts the body to https://meru-report.meru-workers.workers.dev/v1/report over HTTPS, with no proxy, no redirects and a 10-second limit, and only a 204 answer counts as sent. [usage_report] url names another collector, such as one a company runs; it takes an https address, or one on this machine, which the end-to-end tests use. The clients show the address whenever config changes it. Only internal/usagereport holds Meru's collector's address, and a policy test keeps it there.
The collector is a Cloudflare Worker with one D1 table; its code is in collector/. It stores a report only when the body has exactly the fields of its version, version 1 or 2, each with a value from its list, and answers 400 to anything else. It keeps the UTC date and the fields, with no column for an IP address or a time, and an all-time count of first reports in a counter that outlives the 400-day clean-up. It reads the sender's address only as the key for a rate limit of five reports a minute, and Workers Logs stay off, because they would record it. Cloudflare's network still sees each sender's address, as any host does. The Worker publishes the active and new installs of each of the last 90 days, weeks and months, the total, and this week's counts by version, system, chip, model set, streak and active days at / and /totals. It shows each field's counts on its own, never crossed, since a cross of several fields on a quiet week could single out one install. It deletes rows older than 400 days.
The Usage screen's switch, /report, meru report off and send = "off" each stop it at the next check. DO_NOT_TRACK=1 stops it too, but only in merud's own environment: launchd and systemd don't pass a shell's variables on, so set it in the service file or use one of the others.
near-edge, on your own network, gets a turn only after you answer "this time" or "this chat" to the question the turn asks, which lists what the turn carries; an incognito chat and a scheduled job never leave. The code names no provider and ships no provider's SDK, and the engine refuses Ollama's cloud models, which Ollama would run on ollama.com.remote = true in its config entry. remote says where merud may connect, not what the server reaches: a loopback server such as google still talks to Google. The A2A client checks each address again as it connects and follows no redirects, so an agent card can't send your messages elsewhere.~/.meru/secrets.toml, which merud refuses to read when other users can. Config names them, never holds them, and dispatch strips their values from transcripts, tool_calls, logs and spans. No key passes through the model: configure sends you to meru mcp add to type one. about_meru reports server names and counts, never a value from secrets.toml, an env value or a header. The gh commands leave GitHub's token with gh.merud also searches on its own before the model's first round (see Web first): for a question that asks for the web, and for a name your files don't cover, in quotes with a few words of the question. A question that says "my" or "our", or one about mail, a calendar or notes, never gets the second search.merud installs from a pinned zip and starts for that one page. Chrome reaches the network only through a proxy in merud, which applies web_fetch's check to every request the page makes and refuses everything while no page loads. QUIC and WebRTC's UDP stay off. Each page gets a fresh profile, deleted when the page is read. [web] render = "off" turns this off (see Pages that need JavaScript).web_fetch makes merud fetch public pages off this machine, by default, when the model asks; taking it out of [builtin] tools turns it off. It refuses any address on this machine or your network. It runs without asking only for a URL that a search result or your own question gave in the same session, so the model can't carry your data out in a URL it made up; any other URL, and every download, asks you first, and a scheduled job declines them (see Web search).remember asks, and a scheduled job can't send (see Approving a tool call). Someone, or some program, running as you on your computer is out of Meru's reach: they can edit config.toml or read your mail without it. docs/design/security.md has the whole design.curl or ssh. You chose it, and the tool_calls row records each run with its argv.lite or full), how long ago a client first showed the notice (a week, a month, a year or longer), how many questions Meru answered the day before (0, 1 to 5, 6 to 20, or more), on how many of the seven days before it you asked any, how many weeks in a row it has reported, the version it reported last, and whether it is its first report of the week, the month or ever. It holds no ID, no question, no answer, no file name and no setting. merud sends it only after a client has shown the notice, writes each report to ~/.meru/usage-report.jsonl as sent, and stops when you turn it off or set DO_NOT_TRACK. A new field needs a new report version, and a new version shows the notice again before anything sends. Meru's own metrics and traces still go only to loopback, Meru sends no crash reports, and it never checks for updates (see The anonymous usage report)./metrics page while it's on. It holds counts, durations and names from small fixed sets: models, routes, servers, tools and outcomes, never a question, a path or a session ID.0600). Back it up or delete it; it's yours.meru.db; its tool_calls rows stay without arguments or results. An incognito chat writes no transcript, no session rows and no summary, and saves no memory; tool_calls records each of its calls without arguments or results (see Incognito chats).merud copies that one file into ~/meru-output/uploads/, and refuses a link, a folder and a file whose name looks like a secret's. An attached image goes to Ollama on loopback with that one question, like its text, and nowhere else.read_file, list_folder, grep, search_files, search_images and view_image, apply the same rules through the indexer's own code, so outside the output folder and your own session transcripts the model can read no file that search couldn't reach.view_image, which Meru offers while the main model lists vision; the bytes go to Ollama on loopback, and the transcript keeps only the file's name and size. [index] images = false keeps images out of the index.merud Full Disk Access. What they return goes to the local model, and the transcript and tool_calls keep it as they keep any tool result. They never write to the database, and Meru keeps no copy of a note. Take the three names out of [builtin] tools, or turn off Full Disk Access for merud, and Meru reads no note.meru log and the tool_calls table let you review every external action.merud; the package and its dependencies from the npm registry or PyPI; a Python build through uv; and a container image by digest through Docker (see The runtime folder). Nothing downloads until a connector needs it: merud installs a connector the first time it starts it, and the page reader installs chrome-headless-shell the first time a page needs JavaScript.meru transcribe sends it to merud over the socket, merud to whisper.cpp's server on loopback, and nothing writes it to disk. Only the text you send joins a chat. The connector downloads its program from Meru's own release and its model from Hugging Face, each pinned by SHA-256, when you turn it on.remote = true as consent for your data to leave.analyze_table's fixed fields, never code: no SQL, no Python and no formula the model writes reaches an interpreter.We'll settle these with working code and measurements.
make router-eval measure it. The figures below come from the first 135 rows. On the development machine with MiniCPM5-2B, a prompt that puts contrastive option text, the indexed folders and two examples per route ahead of the turn picks the labelled route for 32 of 40 held-out questions, and takes about 28 ms per warm decision. The v0.1 prompt picked 17 of 36. Naming the folders lifted held-out search recall from 8 of 12 to 11 of 12. At a temperature of 1.25 the probabilities are close to calibrated (expected calibration error 0.065 over all 135 rows), so min_confidence = 0.45 means what it says. The weak spot is tools recall (4 of 9 held out): the model answers questions about recent events from memory, and sends requests such as "text alex that I'm on my way" to search. Next: label real turns from transcripts, refit, and decide whether lite needs a larger fast model for tool-heavy use. For the main model, model sets and /usage by model now measure a change on real questions: time to first token, speed, bad calls and capped turns per model, rebuilt from the transcripts.meru.context.tokens will supply the numbers to set a budget per section.merud self-contained, but Meru would take over tool-call parsing and loading models. v0.3's tool calls work through Ollama's parser; decide once we can measure what taking it over would cost.ncruces/go-sqlite3 runs SQLite as WebAssembly, slower than native SQLite, so v0.2 measured it before building on it. On the development machine with 768-dimension vectors, 100,000 chunks index in 6.1 s, a file replaces in about 6 ms, a vector search takes 147 ms and a keyword search 90 ms; at 10,000 chunks the searches take 13 ms and 9 ms (see Why this driver and this vector store). That fits a personal index. If search must get faster, use fewer dimensions or compute distances in Go.| Question | Decision |
|---|---|
| Language | Go, for a small footprint, easy distribution, room to scale, built-in concurrency and fewer dependencies (see Why Go). |
| Platforms | macOS on Apple silicon first, Linux supported, Windows untested at first. Cloud servers count as "a machine you control". internal/platform holds what differs by system in one table, one row per system, which tests check on any machine, and reads the machine, an NVIDIA GPU on Linux and Windows included. |
| Agent harness | Our own loop plus the official MCP and A2A Go SDKs. We looked at Eino and ADK Go. ADK Go pulls a cloud-model client into the dependency tree, and neither saves much once the allowlist, audit and budget logic are ours. |
| Model runtime | Ollama on loopback for now (see open question 4). |
| Models | The lite profile by default (MiniCPM5-2B + embeddinggemma-2:440m), and full for Apple silicon with 64 GB or more (qwen3.6:35b-a3b-mxfp8 + embeddinggemma-2:440m). |
| Storage | JSONL transcripts as the source of truth; SQLite via ncruces/go-sqlite3 as the index, with vectors in a plain table and vec1's distance function. No separate vector database. |
| Routing | A one-token classification read from log probabilities, falling back to search and tools when unsure (docs/fast-router.md). Temperature 1.25 and min_confidence = 0.45, fitted with make router-eval. |
| Hybrid search | FTS5 BM25 plus vector distance over every stored vector, merged in Go with reciprocal-rank fusion. The query is the question, plus on a short follow-up the session's latest earlier question that isn't only filler words; no model call rewrites it. List sizes are constants (50, 50, 10) until measurements say otherwise. |
| Indexing | Only the folders in [index] folders, nothing by default; secrets, hidden files, build folders and ignored files skipped; symlinks never followed; email, calendar and Drive reached live through MCP, not indexed. |
| Built-in skills | writing, explainer, web-research, file-research and mail-research ship in the binary and are copied to ~/.meru/skills/ on first run; your edits always win. |
| Setup | meru setup checks Ollama, pulls the models, writes a first config.toml, and offers a catalog of MCP servers, each added "for you" (with approval of the exact config block) or by copy-paste. For a server outside the catalog, merud probes it first, and meru proposes allow and confirm from the tools' read-only and destructive hints. A reload makes the server work without a restart. |
| Terminal UI | Bubble Tea, with Bubbles for input and scrolling, Lip Gloss for styling and Glamour for Markdown answers, in meru chat only. Answers always stream. Each code block gets a ⧉ copy N label; /copy N or Ctrl-Y copies it, and so does a click, unless [chat] mouse_copy is off. Links in an answer show short and open on a click. Questions typed while a turn runs wait in a queue of up to five in the client. |
| Tool approvals | Approve once, approve for this session, or deny, asked over the same socket as the answer. Session approvals never touch config; lasting trust comes only from editing the confirm list. With no one to ask, as in a script, dispatch declines the call; a scheduled job runs a call that asks once when its allow names the tool, and declines the rest. |
| Tool results | The model reads up to 16,000 characters of each result; the transcript and tool_calls keep 4,000, with secrets removed. Base64 runs of 2,000 characters or more in an MCP or A2A result become a short note first. |
| Secrets | One file, ~/.meru/secrets.toml, mode 0600, referred to from config as secret:<name>. No system keychain: each platform has its own, and a file only you can read works the same everywhere. |
| Memory | One Markdown file per memory under ~/.meru/memory/<kind>/, no index file. Session summaries in the transcripts serve as episodic memory. Memories save through the remember tool and dispatch, without asking in a clean chat and after a yes in one that read outside content. |
| Other agents | An A2A client on the A2A project's Go SDK (protocol 1.0), through the same dispatch path as MCP tools. |
| Local commands | Named commands in [[commands]], with typed parameters that each fill one argv element, run with no shell; no MCP shell server and no command allowlist. |
| Isolation | No sandbox. Meru runs as an ordinary user process, and the tool and agent allowlists control what the model can call. |
The roadmap ships this design in five milestones: v0.1 talks (daemon, engine, traces), v0.2 knows your files (store, hybrid search), v0.3 does things (MCP, A2A, dispatch, meru setup), v0.4 knows you (memory, skills, the built-in skills), and v0.5 acts on a schedule.
Repo files read 23 September 2026. External links checked the same day.
meru chatmeru-desktop/metrics writes