Meru (मेरु): an AI assistant that stays on your machine

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.

~50 msfor the meru client to start and connect
< 1 sto first token on a cold meru "hello", the v0.1 target
1.6 GBthe default chat model, sized for a 16 GB computer
4methods on the Engine interface

Design 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.

What Meru is

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:

  1. Nothing leaves the machine by accident. Meru connects only to loopback, except to A2A agents and MCP servers you mark as remote in config, to the answer endpoints you name, and to the public web pages the model fetches with 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).
  2. Files are the source of truth; SQLite is a projection. Meru can rebuild everything in the database from your files and config. Delete 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).
  3. You can inspect everything. Memories and skills are Markdown files, and answers cite the files they drew on. Meru traces and times every turn, so you can find out why it said something and why it took so long.
  4. Few, narrow abstractions. One engine interface, one store, one agent loop we own, and two wire protocols: MCP (Model Context Protocol) for tools and A2A (Agent2Agent) for other agents. Broad frameworks for large language models change their APIs every few releases, and we don't want to chase them.
  5. Fast or unused. People stop asking an assistant that makes them wait. The process model in the next section exists to keep answers quick.
  6. Simple wins every time. Pick the design with fewer parts, even if it is slower or less general, until a measurement says otherwise. Write code that a developer new to Go can follow.

Two programs: a daemon and a thin client

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:

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.

System overview Short-lived clients (meru, meru chat and meru-desktop) talk to the merud daemon over a Unix socket. Inside merud, the socket server and the scheduler feed the agent loop. The loop uses the skill registry, the dispatch function and the Engine interface. The engine reaches Ollama on loopback. Dispatch reaches MCP servers, A2A agents and, for web_search, a SearXNG you run on loopback. The loop reads and writes files under ~/.meru: session transcripts, memory files, skills, config.toml and the rebuildable meru.db index. The OTel SDK serves an optional /metrics page and can push to an optional OTLP endpoint, both on loopback. CLIENTS · short-lived meru "…" one-shot question meru chat terminal UI meru-desktop desktop app Unixsocket merud · always running socket server ~/.meru/merud.sock scheduler cron jobs: prompts, skills, scripts agent loop route → retrieve → call main → dispatch tools → answer skill registry names + descriptions dispatch allowlist · confirm audit · trace Engine OllamaEngine MCP client pool official Go SDK A2A client A2A Go SDK OTel SDK every stage Ollama 127.0.0.1:11434 fast main embed every tier kept loaded keep_alive: -1 HTTP ~/.meru/ · files on disk sessions/*.jsonl source of truth skills/ SKILL.md files memory/ one file per memory config.toml models, tools, folders meru.db rebuildable index of everything above read, write MCP servers separate processes google obsidian stdio or Streamable HTTP other agents (A2A) separate processes research SearXNG for web_search 127.0.0.1:8888 · you run it observability optional · loopback only /metrics page 127.0.0.1:9464 OTLP endpoint 127.0.0.1:4318 metrics · traces All of this runs on one machine. MCP servers and A2A agents stay on loopback unless their config entry says remote = true.
Figure 1. Arrows leave 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.

The terminal UI

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:

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:

CommandWhat it doesOp
/newstart a new session—
/incognitostart an incognito chat, which merud keeps in memory only (see Incognito chats); meru chat --incognito opens with oneask 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 onesessions, session_turns, session_delete
/deletedelete the open chat for good; the first /delete says what it will do, and a second one right after it deletessession_delete
/folder [new <name>|rename <old> -> <new>|delete <name>]list, make, rename or delete chat folderschat_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 foldersession_move
/tag <tags>, /untag <tags>add tags to the open chat, or take them offsession_tag
/retryask 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 autoask with scope
/attach [path]attach a file or an image to the next question; /attach alone takes them all offattach_file
/save [chat]save the newest answer as a note, or the whole chat as a filesave_file
/usedwhat the newest answer used: every source, each tool call, the memories recall brought, and who the calls reachedmemory_forget
/copy [N|answer]copy code block N, the newest answer's last block, or the whole answer—
/usage [by model]the usage boxusage
/reportthe anonymous daily usage report: what goes, the next one, on or off, and t to send today's nowusage_report
/me [add|prefer <text>]the profile memories; add saves one to me and prefer one to preferencesmemory_list, memory_add, memory_forget
/mcpevery 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 yetconnectors, 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 yetfolders, folder_add, folder_remove
/skillsevery skill, on or offskills, skill_enable, skill_disable
/model [name|save]the model sets, a switch, and a savemodels, model_use, model_save
/logthe latest tool calls, the app's Activitylog
/aboutthe tagline, the version, the license, Meru's folder and the project's links—
/helpevery key and command—
/exitquit—

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.

The desktop app

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:

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:

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:

ScopeRouteSearches firstTools offered
filessearchyeswhat the search route offers but the web tools: the file tools, datetime, about_meru, commands that don't ask
mailtoolsnoevery tool of each mail and calendar server, with datetime and about_meru
webtoolsnoweb_search, web_fetch, datetime and about_meru
talkdirectnonone

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.

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:

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:

OpWhat merud does
connectionslists every source with each tool's policy, and the catalog
tool_policysets one tool's allow, confirm or [builtin] lists, then reloads that kind of source
secret_setsaves one key to secrets.toml, for a name config or the catalog uses, then reloads the MCP servers
mcp_addappends 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_removetakes a server's block out, then reloads
folderslists the [index] folders with file counts, and the usual folders not indexed yet
folder_add, folder_removeedits [index] folders, hands the indexer the new list, restarts the watcher and scans
skill_enable, skill_disableedits [skills] disabled and loads the skills again
save_filesaves the chat or an answer as Markdown through write_file
modelsnames the models, asks Ollama which it holds, and lists the models we tried with whether Ollama has each, and the model sets
model_useswitches to a model set until merud stops, unloading the old answer model first (see Model sets)
model_savewrites the models in use to [models]
model_setswitches 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_reportreads 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:

  1. 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.
  2. Every file goes out with a strict Content-Security-Policy: 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.
  3. The page never navigates. A click on a link calls 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.

Built in Go

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.

Why Go

We chose Go over Python, the usual language for AI tools, for these reasons:

  1. A small footprint. Each program is one binary, typically tens of megabytes. A Python app ships an interpreter, a virtual environment and its packages, often hundreds of megabytes. merud never stops running, so its idle memory matters, and the meru client starts in milliseconds instead of waiting on Python imports.
  2. Easy distribution. One command builds for macOS, Linux or Windows, on Intel or ARM. Installing Meru means copying a file: no Python version to match, no dependency conflicts, and a container image that holds little more than the binary.
  3. Room to scale. Meru serves one person, but nothing stops one server from running many Merus. A company, a school or a home lab could give each person their own 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.
  4. Concurrency built in. A turn streams tokens, runs tool calls in parallel, keeps MCP connections open, and shares the process with the indexer, the connector supervisors and, from v0.5, the scheduler. Goroutines and context cancellation handle that directly, without Python's global interpreter lock.
  5. Fewer dependencies. Go's standard library covers HTTP, JSON, Unix sockets, cancellation, structured logging and embedding files in the binary. Fewer third-party packages means less supply-chain risk, which matters for a tool that reads your mail.
  6. Errors caught before it runs. Static types and the compiler catch mistakes that Python finds only at runtime, which suits a daemon that runs for weeks.
  7. It keeps building. Go's compatibility promise means code written today still compiles years from now, which matches the goal that Meru keeps working without anyone's permission.
  8. The ecosystem is already Go. Ollama is written in Go, and the official MCP SDK, the A2A SDK, OpenTelemetry and Bubble Tea all have first-class Go libraries.

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:

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 ./....

Where it runs

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.

PlatformStatusRestarts merud after a reboot
macOS, Apple siliconSupported and tested. The development machine is a Mac Studio (M4 Max, 64 GB).launchd
Linux, x86-64 or arm64Supported, including home servers and cloud virtual machines.systemd
Windows 10 and laterShould 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 harness

docs/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.

LayerPackages and files
Harness coreengine; 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 assistantrouter, 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:

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 question, end to end

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).

A question, end to end: two turns of one session Sequence diagram with eight participants: you, the meru client, the merud agent loop, the store, the fast model, the main model, dispatch and an MCP server. Turn 1 starts a new session. You ask what you agreed on the launch date in email this week. The client opens a new session and passes the question to the agent loop, which appends the user line to the session JSONL, asks the fast model to pick a route, and gets back route search plus tools. The loop runs hybrid search for the question over three sources, file chunks, memories and session summaries, gets the top chunks and relevant memories, sends the client a sources event that numbers the excerpts, builds the context within budgets, and tries once each MCP server that isn't connected. Inside a loop that repeats until the model answers without a tool call, at most 8 rounds, the loop sends the context and the schemas of allowed tools to the main model, which returns a tool call google.search_gmail_messages. Dispatch checks the allowlist, finds the tool is not in the confirm list, calls search_gmail_messages on the MCP server and gets the matching messages, writes tool_call and tool_result lines and a tool_calls row to the store, and returns the result. The loop sends the context and tool result to the main model, which answers without a tool call. The loop streams tokens to the client, the client shows you the answer followed by the sources it cites, and the loop appends the assistant line. Turn 2 continues the same session. You ask Meru to reply to that thread and confirm you can make it. The loop loads this session's recent messages, the fast model reads them and returns route tools without rewriting the question, the loop searches files and recalls relevant memories, because the tools route searches too, and the main model, given the context with turn 1 and the tool schemas, returns a tool call google.send_gmail_message. Dispatch checks the allowlist, finds send_gmail_message in the confirm list, and asks the client, which offers you three choices: approve once, approve for this session, or deny. You approve once, the client sends approved once to dispatch, and dispatch calls send_gmail_message on the MCP server, which reports the message sent. Dispatch writes the tool_call, approval and tool_result lines and the tool_calls row, returns the result, the main model answers without a tool call, the loop streams tokens to the client, the client shows you the answer, and the loop appends the assistant line. you meru client merud agent loop store fast model main model dispatch MCP server Turn 1 · starts a new session "what did we agree on the launch date in email this week?" new session + question append user line to session JSONL pick a route route = search + tools hybrid search on the question: chunks, memories, session summaries top chunks, relevant memories sources [1], [2], … build context within budgets list MCP tools again; try missing servers once context + schemas of allowed tools tool call google.search_gmail_messages dispatch allowlist ✓ · not in confirm list search_gmail_messages matching messages tool_call + tool_result lines, tool_calls row result context + tool result answer, no tool call loop until the model answers without a tool call, max 8 rounds stream tokens answer, then the sources it cites append assistant line Turn 2 · continues the same session "reply to that thread and confirm I can make it" same session + question load this session's recent messages pick a route, reading turn 1 too route = tools search files, recall memories top chunks, relevant memories context (with turn 1) + tool schemas tool call google.send_gmail_message dispatch allowlist ✓ · send_gmail_message is in confirm list ask: send_gmail_message(...)? approve once · for this session · deny? approve once approved once send_gmail_message message sent tool_call, approval, tool_result lines, row result context + tool result answer, no tool call loop until the model answers without a tool call, max 8 rounds stream tokens answer append assistant line Solid arrows are requests, dashed arrows are replies. Blue arrows leave merud for a tool; amber arrows carry the confirmation.
Figure 2. Each dashed frame is one run of the agent loop, and both turns go round it twice: 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.

Who decides what

DecisionMade byHow
Answer directly, search, call tools, or search and call toolsthe 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 formerud, with no modelThe 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 useyou, in config.tomlOnly 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 argumentsthe main modelIt 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 askingyou, in config.toml and at the promptdispatch 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 endsthe main model, with capsThe 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.

Approving a tool call

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:

ChoiceWhat happens
Approve onceThis call runs. The next call to the same tool asks again.
Approve for this sessionThis 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 chatweb_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 websiteThe same, in every session: merud adds the host to [web] trusted_sites (see Web search).
DenyThe 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.

How a conversation continues

Organizing past chats

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.

One lock in merud makes these ops take turns, so two clients can't write the folder list over each other.

Incognito chats

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.

The turn's span carries meru.session.incognito. The metrics count the turn as any other, since they hold no text and no ID.

Three model jobs, two profiles

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.

TierJob
fastrouting, picking a turn's skill, session summaries, answers about a fetched page
mainreasoning, writing the answer, choosing tools
largeoptional: a bigger answer model you ask for by hand
embedembeddings 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.

Tierlite (default)full
fasthf.co/openbmb/MiniCPM5-2B-GGUF:Q4_K_M (1.6 GB)same
mainsame model as fastqwen3.6:35b-a3b-mxfp8 (38 GB, 8-bit)
embedembeddinggemma-2:440m (713 MB, 768 dims, text and images)same
Hardware16 GB of RAM; runs on a CPU, faster with a GPU or Apple siliconApple 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).

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.

Which model answers

[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:

  1. the route is direct, and the router chose it itself (outcome ok);
  2. the router is at least easy_above sure;
  3. the question asks for no facts: it doesn't end with a question mark, and its first word isn't a question word such as "what" or "is", or a command that asks for knowledge, such as "tell", "explain" or "list". A greeting, thanks, or text to reword passes. The fast model states a wrong fact as surely as a right one, and no weak-answer check can see that, so a fact question goes to main;
  4. the question carries no picture, no picked skill, no web-first search and no hand-off from a Continue.

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.

Models we tried

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.

ModelSizeWhat Ollama listsWhat we saw
hf.co/openbmb/MiniCPM5-2B-GGUF:Q4_K_M1.6 GBtools, thinkingabout 55 s; made up command flags and misread what tools sent back
qwen3.8:27b (dense)17 GBvision, tools, thinkingthe 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 GBvision, tools, thinkingabout 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 GBvisionanswers 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.

SetAnswer modelPassedMedian time per task90th percentileMedian time to first tokenTokens a second
qwen-moeqwen3.6:35b-a3b-mxfp8 (38 GB)133 of 150 (89%)6.8 s19.4 s4.1 s63
gemma-moegemma4:26b-mxfp8 (28 GB)138 of 150 (92%)16.3 s29.1 s15.6 s57
qwen-denseqwen3.8:27b (17 GB)135 of 150 (90%)55.9 s121.1 s34.6 s17
qwen-moe-q4qwen3.6:35b (23 GB)133 of 150 (89%)10.6 s28.4 s5.7 s80
gemma-moe-q4gemma4:26b-a4b-it-qat (15 GB)120 of 150 (80%)18.7 s29.8 s17.6 s92
minicpm-liteMiniCPM5-2B, the lite answer model (1.6 GB)102 of 150 (68%)13.1 s28.8 s11.8 s130
Kind of task (runs)qwen-moegemma-moeqwen-denseqwen-moe-q4gemma-moe-q4minicpm-lite
direct (24)242424242423
search of the files (27)272726272725
one tool (39)373737353324
several tools (36)22282424136
several turns (12)111212121212
honesty (12)121012111112

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:

MemoryAnswer modelWhy
16 GBMiniCPM5-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 GBgemma4: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 GBqwen3.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 moreqwen3.6:35b-a3b-mxfp8, the full profile; gemma4:26b-mxfp8 for work across several toolsthe 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.

Model sets

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:

  1. Ask Ollama to drop the old answer model: POST /api/generate with the model, no prompt and keep_alive: 0 (OllamaEngine.Unload).
  2. Ask /api/ps every 100 ms until it no longer lists the old model, for at most 10 seconds.
  3. Load the new model with a one-token question, so the first real question doesn't pay for the whole load.

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.

The engine: four methods, two engines

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).

Answer endpoints

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

Two engines may come later, behind the same interface:

Storage: files hold the truth

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.

Session transcripts

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.

Storage: files as truth, SQLite as projection On the left, the source-of-truth files: your folders, session transcripts, memory files, and config.toml with skills. On the right, the tables in meru.db. The indexer chunks and embeds your folders into documents, chunks, chunk_fts and chunk_vec, a plain table of vectors compared with vec1's distance function. Replaying transcripts fills tool_calls and turns, and from v0.4 sessions, messages, message_fts, summary_fts and session_vec. A syncer embeds the memory files into memories, memory_fts and memory_vec. Config fills meta. From v0.5 a turn row also names the scheduled job it ran for, read from the transcript, so each job's last run survives a rebuild; the jobs themselves stay in config.toml. SOURCE OF TRUTH · files you can read PROJECTION · ~/.meru/meru.db · rebuildable your folders notes, docs, PDFs, repos ~/.meru/sessions/ one JSONL file per session, append-only ~/.meru/memory/ one Markdown file per memory, a folder per kind config.toml · skills/ models, allowlists, folders, skill files documents · chunks chunk_fts (FTS5) · chunk_vec (plain table) sessions · messages · message_fts (v0.4) summary_fts · session_vec, one per summary tool_calls · turns each tool call · answer · job memories memory_fts (FTS5) · memory_vec (plain table) meta schema, model, vector size, prefix hash indexer: chunk + embed replay indexer: embed read config Delete meru.db and merud rebuilds every box on the right from the files on the left.
Figure 3. Every arrow runs left to right, and every table on the right has a file behind it, memories included. v0.2 built 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.

The database

~/.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.

TableHoldsRebuilt from
documentsindexed source files: path, mtime, hash, typeyour folders
chunkspieces of each file's text, plus metadata and the parent documentyour folders
chunk_vecone vector per chunk, a blob of 32-bit floats scaled to length 1chunks, re-embedded
chunk_ftskeyword index over chunks (FTS5)chunks
sessions / messages (v0.4)every session and message, plus each session's summary and tags, for context and meru logsessions/*.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
turnsone 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 itsessions/*.jsonl (the assistant line holds route, duration, files and the model's numbers; the model_switch lines name the model)
tool_callsaudit 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 resultsessions/*.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 hashmemory/*/*.md
memory_vec / memory_fts (v0.4)vector and keyword indexes over memoriesmemories
turns.job (v0.5)which job a run belongs to, for each job's last runthe run's transcript: its user line names the job; the jobs themselves are [[jobs]] in config.toml and stay out of the database
metaschema version, embedding model name, vector size and task-prefix fingerprintconfig

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.

Why this driver and this vector store

Operation10,000 chunks100,000 chunks
index every chunk0.59 s6.1 s
replace one file6.4 ms6.1 ms
vector search, top 5013 ms147 ms
keyword search, top 509 ms90 ms

Getting your content in

The indexer reads the folders you name into the store, keeps them current while merud runs, and reads nothing else on disk.

What gets indexed

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:

OrderSkipped asWhat it catches
1symlinkany symbolic link; the indexer never follows one
2secret.env*, *.pem, *.key, id_rsa*, *.kdbx, credentials*, .netrc and similar
3hiddena name that starts with .
4build-foldernode_modules, .venv, venv, vendor, target, dist, build, __pycache__
5ignored[index] ignore, then each folder's .gitignore and .meruignore, from the top folder down
6media, binary, unsupportedby 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
7too-largeover max_file_mb, or over 20 MiB for an image
8binarya NUL byte in the first 8 KB (PDFs, images, and Word and Excel files excepted)

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.

Chunking

The indexer cuts each file into chunks along its own structure:

FileSplit byHeading keptCitation points to
Markdownheading, then paragraphsthe heading path, such as Garden > Springlines
Gotop-level declaration, read with Go's own parserthe declaration's namelines
other code, plain textblank-line blocksnonelines
HTML<h1> to <h6>, then paragraphs; scripts, styles and <head> droppedthe heading pathnone
PDFpage, then paragraphs; plain text, no layoutnonepage
Word (.docx)as Markdown: heading, then paragraphs; a table becomes one line per row, cells joined by | the heading paththe heading
Excel sheet, CSV, TSVrows, 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 sheetthe sheet's name, or the file's name without its extensionrows
Image (PNG, JPEG, GIF, WebP)not split: one chunk whose text names the file and its folderthe file namethe file

Keeping it current

What stays out

Finding the right text: hybrid search

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:

PieceComes from
Keyword search, ranked by BM25FTS5 (ORDER BY rank, where rank is BM25)
Similarity search, ranked by distanceevery row of chunk_vec, with vec1's distance function (ORDER BY vec1_l2_distance(vector, ?) / 2 LIMIT ?)
Merging the two listsour Go code: reciprocal-rank fusion
Hybrid search The query is embedded with the embed tier and runs as a vector query that reads every row of chunk_vec, orders by vec1 distance and keeps the top 50. The same query runs as a keyword query against chunk_fts, ranked by BM25, for the top 50. The two queries run one after the other. rrf in Go merges the two lists, keeps the top 10 chunk IDs, and merud loads their text and source path from chunks and documents. The list sizes are fixed constants in internal/retrieve, not config keys. query embed embed tier vector query chunk_vec · every row · top 50 stage = vector keyword query chunk_fts · BM25 · top 50 stage = fts run one after the other, inside merud rrf() in Go · k = 60 stage = fusion top 10 chunk IDs highest fused score load text + path chunks · documents List sizes (50, 50, 10) are constants in internal/retrieve, not config. Each stage reports its time in meru.retrieval.duration.
Figure 4. Only the vector side needs a model call. The keyword side, the merge and the final lookup are all SQLite or plain Go inside 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:

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.

Merging two lists with reciprocal-rank fusion

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:

ChunkVector rankKeyword rankSumScore
A131/61 + 1/630.03227
B221/62 + 1/620.03226
C—11/610.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:

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.

Search first, or let the model look

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"
autoagentic
Search before the answeryes, on turns about your files (see below)no
Earlier conversations in the promptyesno
Profile and recalled memoriesyesyes
File tools offeredread_file, list_folder, grep and search_files, and search_images and view_image while images and vision allow them, on the routes that offer toolsthe same
Note in the prompt, on turns about your filesthe 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 passedagentic passedauto median sagentic median s
direct (3)9/99/91.51.8
files: list, grep, read (3)9/99/98.35.6
retrieval: by meaning (3)9/99/98.08.7
web (2)5/62/624.018.1
mcp (2)5/66/615.07.4
command (1)3/33/325.519.0
profile (1)3/33/311.51.3
session: two turns (2)5/60/630.142.0
datetime (2)6/66/64.95.2
all (19)54/5747/5710.87.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:

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.

Turns that aren't about your files

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.

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 passedAfter passedBefore mean sAfter mean sFile sources per turn, before → after
direct (3)9/99/91.61.30 → 0
files: list, grep, read (3)9/99/93.23.18 → 8
retrieval: by meaning (3)9/99/93.63.28 → 8
web (2)2/65/611.69.38 → 0
mcp: almanac by name (2)6/66/64.51.58 → 0
memory: "remember that…" (1)2/31/33.73.78 → 8
session: two turns (2)6/65/66.64.68 → 6.7
datetime (2)6/66/66.76.24 → 4
all (18)49/5450/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:

Citations

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).

Memory you can read and edit

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.

Layout

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.

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.

Facts and episodes

How Meru uses them

  1. Indexing. A small syncer, apart from the file indexer, keeps ~/.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.
  2. Recall. Each turn searches memories by meaning and by keyword, adds a third list ranked by recency, and merges all three with 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.
  3. Saving. The model saves a memory by calling the built-in 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.
  4. Your commands. 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.

Skills: instructions loaded on demand

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.

Built-in skills

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:

SkillWhat it does
writingPlain-English rules for any prose Meru writes: emails, summaries, reports
explainerBuilds a self-contained HTML page that teaches a topic, with diagrams
web-researchFor 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-researchFor 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-researchFor 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.

The agent loop: five steps

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.

  1. Route. The 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).
  2. Build the context. System prompt, skill descriptions, relevant memories, retrieved chunks, this session's history and, on the 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).
  3. Call 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.
  4. Dispatch tools. Every call goes through one function, dispatch, in this order:
    1. Allowlist. A tool that no backend offers is 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).
    2. Transcript. The tool_call line goes in before the call runs. If it can't be written, the call doesn't run.
    3. Confirm. Each tool asks never, asks unless approved for this session, or asks every time (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.
    4. Call. The MCP server, A2A agent, built-in tool or local command runs, under its own timeout. The outcome is 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).
    5. Record. 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.

  5. Repeat from step 3 with the tool results, until the model answers without calling a tool or the turn reaches [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:

OutcomeWhenWhat you read
timeoutturn_timeout ran outthe text so far and a note that it stopped, or a sorry
cut_offthe last call hit max_output_tokensthe text so far and a note that it stopped, or a sorry
window_fullthe 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_upthe 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."
cappedthe 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_outputOllama couldn't parse the model's output, even after the one retryany 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_visionthe question carried images and the main model lacks the vision capabilitywhen 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.

Continuing an 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:

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.

Questions with images

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:

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.

Claims no tool backs

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:

RuleMatches
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:

RuleMatches
"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."

Routing

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:

  1. The prompt opens with four lettered options (A = answer directly, B = search, C = tools, D = search and tools) and two examples per route. Each option's description names the questions that belong to it and the ones that don't. Option B also names the folders in [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.
  2. 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.
  3. The router keeps the alternatives whose text is one of the four letters, adding up variants such as " A" and "a", divides each log probability by a fitted temperature, turns it back into a probability, and normalizes the four so they sum to 1.
  4. The most likely letter is the route, and its probability is the confidence.
Routing: one token, four probabilities The prompt opens with four lettered options, A answer directly, B search, which also names the indexed folders, C tools, D search and tools, and two examples per route, then the session history and the question, ending with Answer. Ollama runs the fast model for one token with log probabilities: num_predict 1, logprobs true, top_logprobs 20. The router keeps the alternatives that are the letters A to D, turns each log probability back into a probability, divides by the temperature and normalizes the four to sum to 1. It then checks whether the confidence is at least min_confidence. If yes, the most likely letter is the route, its probability is the confidence, and the outcome is ok. If no, the router takes the fallback route search+tools, with outcome low_confidence, or degraded when fewer than two letters appeared. prompt A answer · B search C tools · D search+tools examples, then the turn ends with Answer: Ollama, fast model one token, with log probabilities num_predict = 1 logprobs = true top_logprobs = 20 four probabilities keep the letters A–D exp, ÷ temperature normalize to sum to 1 sure enough? confidence ≥ min_confidence and at least two letters yes no route = the most likely letter confidence = its probability outcome ok fallback: search+tools outcome low_confidence or degraded (< 2 letters)
Figure 5. The router reads a route instead of asking for one. It never parses text the model wrote, and when the four probabilities don't pick out one letter, it takes the route that can't leave a turn short of context.

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.

Tools over MCP

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:

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:

TransportWhat merud doesWhat it never does
stdiostarts the server as a child, because the transport is the child's stdin and stdoutrestart it on its own, watch its health, back off and retry
Streamable HTTPconnects to a URLstart 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 startsone try per server
a turn on a tools routetools/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 allnothing
a call whose session is gonefails, 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
KeyMeaning
command, argsstdio transport: merud starts this process. An entry has either command or url.
urlStreamable HTTP transport: you run the server, and merud connects to it here.
env, headersextra 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).
allowthe tools the model may call. Anything missing stays hidden.
confirmallowed tools that still need a yes from you on every call.
remotemerud 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".
timeoutthe 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.
ColumnMeaning
SERVERthe name from config, or a connector's ID
TRANSPORTstdio or http
STATEconnected 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)
TOOLShow many tools the server offers, from its tools/list; — when not connected, since there is no list to count
ALLOWEDhow many tools config allows
CONFIRMhow many allowed tools ask first, from confirm and always_confirm
last fieldthe 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.

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.

Connectors and the supervisor

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.

The manifest

Each connector has one TOML file, internal/connectors/manifests/<id>.toml, compiled into merud. Five ship:

IDKindInstallWhat it is
searxngcontaineran image, by digestthe search engine behind web_search
obsidianstdiothe npm package obsidian-mcpnotes in an Obsidian vault folder
googlehttpthe Python package workspace-mcpGmail, Calendar, Drive and Docs
ollamadependencynonethe model runtime; status only
whisperservicea download and one model file, each by SHA-256whisper.cpp's server, for speech to text

A manifest names:

connectors.Load parses every manifest when asked, and refuses the set when one breaks a rule:

whisper is the speech-to-text connector (see Speech to text).

Pinned versions

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.

Config and secrets

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.

The runtime folder

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:

TypeWhat 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>
binarydownload this platform's file into <dir>, check its SHA-256, mark it runnable
containerdocker info, then docker pull <image>@sha256:<digest>

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:

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.

The supervisor

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:

StateMeaningInside it
okready to use; its tools are offeredok (running) or ready (installed, checked, not running)
offconfig never turned it on, or turned it offoff
by_handan [[mcp.servers]] entry with the same name runs instead ("set up by hand")by_hand
needs_configa field is missing or wrong, the port is taken, or you need to sign inneeds_config, sign_in (running, waiting for you)
startingon its wayinstalling, starting, backoff after a crash
failed(reason)stopped until config changes or merud restarts; the reason says whyfailed
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

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:

StateSentence
ok, not runningObsidian is ready. It starts when a question needs it.
ok, runningObsidian is running.
offObsidian is off.
by_handObsidian 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_configObsidian 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.
startingMeru is installing Obsidian 2.0.1 and checking it. / Obsidian is starting. / Obsidian stopped (…) and starts again in 2 s.
failedObsidian 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.

Setting up a connector

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:

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 typeSettings/mcp and meru mcp fix
text, emaila text field with the value config holdsone line, Enter keeps the value
secreta password field, empty, with "saved" when secrets.toml holds oneread without showing it; Enter keeps the saved one
foldera text field and Choose…, which opens the system's folder dialoga path
choicea list of the choicesone line, with the choices named
oauth"Sign in to Google", which opens the server's link, once merud has oneskipped; 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.

Google

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.

SearXNG and Ollama

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):

ConfigModeWhat merud does
[connectors.searxng] enabled = true, and searxng_url is http://127.0.0.1:8888runchecks, and runs its own container when nothing answers
enabled = true with another searxng_urlwatchchecks and reports; Meru's container answers only at 8888
no enabled key, and [builtin] tools lists web_searchwatchchecks and reports, as merud did before connectors; it starts nothing
enabled = false, searxng_url = "", or no enabled key and web_search not listedoffnothing

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:

  1. Healthy: ok. docker inspect meru-searxng says whether it is Meru's container, for the sentence.
  2. Meru's container stopped answering: a crash. The restarts wait 1, 2, 4 and 8 seconds, and the fifth crash in ten minutes sets failed, as for a stdio connector. Once failed, the loop only checks, and turns ok if the server comes back.
  3. Something answers, badly, and it isn't Meru's container: needs config, with the reason. Meru doesn't start a second server to fight it for the port.
  4. No Docker, or Docker not running: needs config, and the next minute's check tries again.
  5. A container named meru-searxng without Meru's label: needs config. Meru leaves it alone.
  6. Otherwise: 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:

StateSentence
okWeb search is running in the container meru-searxng. / Web search uses the SearXNG already running at …
offWeb search is off.
needs_configWeb 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)
startingMeru is checking Web search at … / Meru is downloading Web search (image sha256-…) and starting it. / Web search stopped (…) and starts again in 2 s.
failedWeb 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:

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.

Moving to connectors

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:

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:

ObsidianGoogle
takesan entry that runs obsidian-mcp through npx, node or its own program, with one --vault name=pathan entry at http://127.0.0.1:8000/mcp (or localhost)
readsthe vault name and folder from --vaultthe 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
refusesmcp-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, envanother address, a stdio entry, a start script on another port, a missing value (it names what to give), another program on port 8000
savesnothing in secrets.tomlthe secret as connector_google_client_secret, with mode 0600
stopsnothingthe 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.

Local commands

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 thisAnd you have allowed
gitgit -c core.pager='sh -c …' log
findfind . -exec sh -c … \;
awkawk 'BEGIN{system("…")}'
tartar --checkpoint-action=exec=…
sshssh host <any command>
rsyncrsync -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.

  1. exec.CommandContext(argv[0], argv[1:]...). Never sh -c, never a string.
  2. A {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.
  3. 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.
  4. The program gets PATH, HOME and LANG, plus the names in env_allowlist, and on Windows SystemRoot and USERPROFILE. The rest of merud's environment stays out.
  5. It starts in cwd, your home folder unless set.
  6. Each run has a timeout, 30 seconds unless set, at most 300. On Unix the program runs in its own process group, and the timeout kills the whole group, so a child it started dies too. On Windows the timeout kills the program alone.
  7. merud keeps the first 1 MiB of stdout and of stderr and says when it cut.
  8. The model reads the exit code, stdout, and stderr when there is any, each labelled. A non-zero exit is a result, not an error: the call's outcome is 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.

TypeAccepts
stringnon-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
inta whole number, within min and max when set
enumone of values
patha 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.

First run and setup

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.

  1. Ollama. Meru checks that Ollama answers and is 0.40.5 or later. If it doesn't answer, Meru prints the install step for your platform and waits for you to press Enter; if it is older, Meru says to update it, and q stops setup.
  2. Models. With no 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.
  3. Your files. Meru asks which folders to index (for example ~/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.
  4. Web search. Meru checks that SearXNG answers JSON at [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).
  5. Tools. With 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).
  6. About you. When 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).
  7. Anonymous daily count. For a config this run wrote, Meru shows the fields of the anonymous usage report with an example body and asks 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).
  8. A test question. When 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.

Adding an MCP server

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).

NameServerTransportNeedsAsks first
googletaylorwilsdon/google_workspace_mcp (uvx workspace-mcp)Streamable HTTP on 127.0.0.1:8000/mcpa Google OAuth client, a sign-in, and you running itsending mail, changing an event
obsidianmcp-obsidian, through Obsidian's Local REST API pluginstdiothe plugin's API keyappending 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:

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:

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

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.

PartRuns asDoes
cmd/meru-installerthe windowserves the page, binds the Bridge, shows the folder dialog
internal/installerthe installer's processthe eleven steps, the Bridge the page calls, the allowlist of programs
programs from the allowlistchild processes, no shellbrew, launchctl, open, ditto, xattr, codesign, sysctl, sw_vers, df
OllamaOllama.app, or a Homebrew serviceanswers POST /api/pull, whose stream gives each download's progress
workspace-mcpthe launchd job com.meru.workspace-mcpthe Google server, when you set it up
merudthe launchd job com.meru.merudeverything after the last step

The rules it keeps. internal/policy checks each one:

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.

#StepWhat it doesWhat it writes
1Check this Macreads the chip, macOS, memory and free disk with sysctl, sw_vers and df, and offers the model sets that fitnothing
2Install Merucopies 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 askedthe three programs; config.toml from the template when missing
3Ollama and the modelsinstalls Ollama when missing, starts it, and pulls each model of the chosen set that Ollama lacks[models] main, when the set names one
4Folders to searchlists the folders config has, then Documents, Desktop and Notes with file counts; the system's folder dialog adds more[index] folders
5Web searchkeeps 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
6Obsidian notestakes 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 Adoptnothing
7Apple Notesturns 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 callsearch_notes, list_notes and read_note in [builtin] tools
8Skills and commandstakes 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 outthe ticked [[commands]], uncommented, at the end of the file
9Gmail, Calendar and Drivewalks 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/
10About youasks your name, your email and how you like answersmemory/me/ and memory/preferences/
11Start Meruwrites 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 minutesthe 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.

The hand-off

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:

ToolOffered whenWhat it does
web_search[web] searxng_url is set and [builtin] tools lists it, as both are by default, and the SearXNG connector is okOne 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 defaultFetches 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"?}:

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.

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.

Pages that need JavaScript

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.

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.

Questions about Meru itself

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.

Web first

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:

CaseWhenWhat merud runs
askedthe 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 webweb_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
namedan 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 itweb_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.

Speech to text

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.

Why whisper.cpp, not Ollama

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:

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:

ProfileModel fileOn diskIn memoryLanguages
liteggml-base.en.bin148 MB445 MBEnglish
fullggml-large-v3-turbo-q5_0.bin574 MB890 MBmany

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.

The binary

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:

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.

The connector

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):

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 transcribe op

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:

  1. 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.
  2. The whisper 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.
  3. 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.
  4. 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.

Recording in Meru.app

What Meru keeps

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.

Other agents over A2A

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
A2A dispatch Sequence with four participants: main model, agent loop, dispatch, research agent. The main model returns a tool call a2a.research.summarize with a message. The agent loop hands it to dispatch. Dispatch checks the allowlist, asks for confirmation if configured, and opens a span. Dispatch sends SendStreamingMessage to the research agent, which returns task updates and a final artifact. Dispatch writes a tool_calls row with kind a2a and closes the span, then returns result text to the loop, which gives the tool result to the main model. main model agent loop dispatch research agent (A2A) tool call a2a.research.summarize {message} dispatch allowlist ✓ · confirm? · open span SendStreamingMessage task updates … final artifact write tool_calls row (kind = a2a) close span result text tool result The agent's URL must be loopback unless its config entry says remote = true. Long tasks use A2A streaming updates, under the same per-call timeout as a tool.
Figure 6. To the model, a remote agent is one more tool. Everything that makes the call safe to audit happens in the two boxes on the 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".

Scheduled jobs

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

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
KeyWhat it says
nameletters, digits, - and _, unique; at most 50 jobs, so the metric's job attribute stays a small set
schedulefive-field cron: minute, hour, day of month, month, day of week; *, numbers, names (mon, jan), ranges, steps (*/15) and lists
every_weeks, fromrun only every N weeks; the weeks count from the Monday of from's week, and nothing runs before from
promptthe question the run asks, through the agent loop
skilla skill the run loads without the pick step; needs prompt
command, argsa [[commands]] entry and its parameters; no model runs
allowtools the run may use without asking, when they would ask once
outputa file under [skills] output_dir the answer also goes to; {date}, {time} and {job} fill in
enabledfalse 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".

When a job runs

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:

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.

Where a run goes

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.

Approvals in a job

Nobody can answer an approval during a job, so dispatch treats a job's calls by how they would ask:

The callIn a job
needs no approvalruns
asks once (confirm lists it, or a command has confirm = true), and the job's allow names itruns; the approval line reads once
asks once, and allow doesn't name itdeclined; 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_confirmdeclined, 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.

Pausing, cancelling and managing jobs

OpWhat merud does
jobslists each job with its schedule in words, next and last run, the last run's outcome and chat, and whether it runs now
job_setadds 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_removetakes the job out of config.toml; its runs stay in the Jobs folder
job_runruns the job now, outside its schedule; this doesn't count as its last run
job_cancelstops 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.

What the scheduler doesn't do

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.

Seeing where the time went

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).

Local only

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]
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

Traces

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:

Trace tree for one turn with a tool round The root span rpc.request carries op, source and question length. Under it, meru.turn carries route, source, session, iterations and outcome. The children of meru.turn, in order: meru.session, new or opened, with history turns and messages; meru.transcript.append for the user line; meru.route with decision, confidence, outcome and meru.route.p per route, whose child gen_ai.chat fast asks for one token with log probabilities and has a POST /api/chat child with the HTTP status; meru.skills.pick, which runs beside meru.route, with a gen_ai.chat fast child that writes up to 20 tokens of skill names; meru.search with the number of results found, on turns about your files, whose child meru.retrieve records the hits from each list, the fused count and the time of each stage, and has a POST /api/embed child that embeds the query; meru.retrieve.sessions for past sessions that match, on turns that search first; meru.recall for memories by meaning, keyword and recency, on every turn; meru.prompt with messages, characters and estimated tokens; gen_ai.chat main for round 1, the text and tool calls with a first_token event, whose POST /api/chat child carries the HTTP status and thinking chunks; meru.dispatch, one per tool call, with tool, kind, server, outcome and approval, whose child tools/call names the MCP tool, or invoke_agent the A2A agent; meru.transcript.append for the call's tool_call, approval and tool_result lines; gen_ai.chat main for round 2, the answer, with its POST /api/chat child; and meru.transcript.append for the assistant line. The router and the skill pick run at the same time, and so do the calls of one round. The same trace ID goes to the transcript, the messages and tool_calls rows, and every log line of the turn. rpc.request op · source · question length transcript · messages · tool_calls and every log line of the turn same trace ID written to meru.turn route · source · session · iterations · outcome meru.session new or opened; history turns and messages meru.transcript.append the user line meru.route decision, confidence, outcome, meru.route.p.<route> gen_ai.chat fast one token with log probabilities POST /api/chat HTTP status meru.skills.pick runs beside meru.route: the skills this question needs gen_ai.chat fast up to 20 tokens: skill names, or none meru.search results found; on turns about your files meru.retrieve hits per list, fused count, time per stage POST /api/embed the query's vector meru.retrieve.sessions past sessions that match; on turns that search first meru.recall memories by meaning, keyword and recency; every turn meru.prompt messages, characters, estimated tokens gen_ai.chat main round 1: text and tool calls; first_token event POST /api/chat HTTP status, thinking chunks meru.dispatch one per call: tool, kind, server, outcome, approval tools/call <tool> MCP; an A2A call is invoke_agent <agent> meru.transcript.append the call's tool_call, approval and tool_result lines gen_ai.chat main round 2: the answer POST /api/chat HTTP status meru.transcript.append the assistant line The router and the skill pick run at the same time, and so do a round's calls, so their spans overlap. Model spans follow the OTel GenAI conventions; HTTP spans the OTel HTTP conventions. No prompt text unless capture_content = true.
Figure 7. One turn on the 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:

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

Metrics use the standard GenAI names where a convention exists, and meru.* names for the rest.

MetricTypeAttributesAnswers
gen_ai.client.token.usagehistogrammodel, tier, operation, gen_ai.token.type (input/output)tokens per call
gen_ai.client.operation.durationhistogrammodel, tier, operationmodel call latency
gen_ai.server.time_to_first_tokenhistogrammodel, tierthe v0.1 "first token < 1 s" target
gen_ai.server.time_per_output_tokenhistogrammodel, tierdecode speed
meru.engine.load.durationhistogrammodelcold loads Ollama had to do (should be ~0)
meru.route.decisionscounterroute, outcome (ok/low_confidence/degraded)how often each route wins, and how often the router is unsure
meru.turn.durationhistogramroute, 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.iterationshistogramrouteloop depth
meru.context.tokenshistogramsection (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.callscountermeru.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.sessionscountersourcesessions started
meru.turn.tokenscountergen_ai.token.type (input/output), route, sourcethe main model's tokens per answered question, summed over its model calls
meru.turn.docshistogramroutedistinct files each answered question read
meru.tool.durationhistogrammeru.tool.kind, meru.tool.server, gen_ai.tool.nametool latency, for calls that ran
meru.model.malformed_callscountermodeltool calls the main model wrote that Meru couldn't run as written
meru.retrieval.durationhistogramstage (vector/fts/fusion/memories/sessions/images)retrieval cost (v0.2; memories and sessions stages v0.4; images v0.4.13)
meru.speech.durationhistogrammodel (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.durationhistogramoutcome (ok/error/timeout/cancelled)how long a page that needs JavaScript takes in the page reader, Chrome's start included
meru.rpc.active_streamsup-down counter—open client sessions
meru.scheduler.job_runscounterjob, outcome(v0.5) scheduled work: did each job run, and how did it end
meru.scheduler.latenesshistogramjob(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:

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.

Reading the metrics

Meru ships no dashboard program. There are three ways to read the numbers, and the first needs nothing installed.

/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]))

Logs

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.

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.

The anonymous usage report

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).

What goes

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}
FieldWhat it holdsValues
vthe report's format2
meruthe releasesuch as 0.7.7
osthe systemdarwin, linux, windows
archthe chip's familyarm64, amd64
profilethe model setlite, full
agehow long ago a client first showed the noticeweek (under 7 days), month (under 31), year (under 366), older
questionsthe questions answered the day before, in UTC, leaving out scheduled jobs0, 1-5, 6-20, 21+
active_daysthe days among the seven before today with a question, jobs left out0, 1-2, 3-5, 6-7
streakthe ISO weeks in a row, Monday to Sunday in UTC, with a report, this one included1, 2-4, 5-12, 13+
previousthe version in this install's last reportnone, or such as 0.7.6
week_firstthis is the install's first report of the ISO weektrue, false
month_firstthis is its first report of the UTC monthtrue, false
firstthis is its first report evertrue, 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.

When it goes

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:

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.

Who chooses

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.

What the user sees

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.

The record

~/.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.

The connection

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

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.

Turning it off

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.

The privacy boundary

What Meru won't do, and what is still open

Limits by design

Deliberate non-goals

Open questions

We'll settle these with working code and measurements.

  1. Router quality. The router reads probabilities instead of parsing text (see Routing). A labelled set of questions, 167 today, and 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.
  2. Context order. Skills, memories and retrieved chunks compete for the same window. meru.context.tokens will supply the numbers to set a budget per section.
  3. PDF extraction. v0.2 reads each page's plain text with a pure-Go library and keeps no layout, so tables and columns come out as running text. A scanned PDF with no text layer yields nothing. Local tools that keep layout are weak, and Go has fewer of them than Python; better extraction may need a cgo library or an external tool.
  4. Leaving Ollama. An embedded llama.cpp engine would make 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.
  5. WebAssembly SQLite speed (answered in v0.2). 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.
  6. How many excerpts to keep. Each search keeps the top 10 chunks, and with a tiny index that is every chunk, so the prompt carries excerpts that don't help. The clients list only the sources an answer cites (see Citations), so this costs prompt length, not a noisy list. A minimum fused score or fewer than 10 chunks would fix it; measurements from real questions will pick one.

Decisions already made

QuestionDecision
LanguageGo, for a small footprint, easy distribution, room to scale, built-in concurrency and fewer dependencies (see Why Go).
PlatformsmacOS 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 harnessOur 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 runtimeOllama on loopback for now (see open question 4).
ModelsThe 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).
StorageJSONL 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.
RoutingA 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 searchFTS5 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.
IndexingOnly 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 skillswriting, 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.
Setupmeru 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 UIBubble 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 approvalsApprove 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 resultsThe 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.
SecretsOne 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.
MemoryOne 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 agentsAn A2A client on the A2A project's Go SDK (protocol 1.0), through the same dispatch path as MCP tools.
Local commandsNamed commands in [[commands]], with typed parameters that each fill one argv element, run with no shell; no MCP shell server and no command allowlist.
IsolationNo 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.

Sources

Repo files read 23 September 2026. External links checked the same day.