Meru (मेरु): the big picture

Meru is a personal AI assistant that runs on a machine you control. It answers questions from your notes and files, remembers what matters about you, and uses tools such as web search, Gmail, your calendar and your Obsidian notes. The models run on your own machine, so no prompt goes to an AI company.

This page covers the main parts in a few minutes. Level 200 explains how each part works, and level 300 is the full design.

The parts

The parts of Meru A dashed line marks your machine. Inside it, you type into meru or meru-desktop, for a chat or one question, and it passes the question to merud, which runs in the background. merud holds the agent loop, which answers your question, and dispatch, which checks each tool call and asks before risky calls. A scheduler runs jobs on a schedule: questions, skills and scripts. The agent loop uses local models run by Ollama (fast, main and embed, in a lite or full setup), your data (the folders you index, memory files, conversation transcripts and a SQLite search index) and skills (writing, explainer, web-research, file-research, mail-research and any you add). Dispatch reaches other agents over A2A and tools over MCP, such as Gmail, Calendar, web search and your notes. The Usage page shows what Meru measures, and a Prometheus you run can read the same numbers on the same machine. Outside the dashed line sit internet services such as a search engine or Google; only the tools you allow connect to them. your machine you meru or meru-desktop chat, or one question merud runs in the background scheduler jobs: prompts, skills, scripts agent loop answers your question dispatch checks each tool call, asks before risky calls metrics (optional) Prometheus, local only local models · Ollama lite or full fast main embed your data your folders indexed memory files Markdown transcripts one per chat search index SQLite skills + yours writing · explainer web · file · mail research other agents · A2A tools · MCP, built in + yours Gmail · Calendar · web search · notes only tools you allow internet services search engine, Google
Figure 1. Everything inside the dashed line runs on your machine: the models, your data and the assistant itself. Only the tools you allow reach the internet, and each call goes through dispatch first. The scheduler, new in v0.5, runs jobs on a schedule: a question, a skill or a script.

What happens when you ask

What happens when you ask Sequence diagram with five participants: you, Meru, your files and memory, the local model, and a tool. You ask a question. Meru looks up related notes and memories and gets back what it found. Meru sends the question and what it found to the local model. Only when the model needs a tool: the model says it needs one; if the tool changes something, Meru asks you first and you say yes; Meru calls the tool, gets the result, and passes the result to the model. The model returns the answer, and Meru streams it to you word by word, with sources. only when the model needs a tool you Meru your files and memory local model a tool ask a question look up related notes and memories what it found question + what it found “I need a tool” ask first, if the tool changes something yes call the tool result the result the answer answer, word by word, with sources
Figure 2. The model never calls a tool itself. It tells Meru what it needs, and Meru makes the call, after asking you if the call would change something.

Most questions skip the tool steps. When the model needs live information or an action, Meru calls the tool, and it only stops to ask you when the call would change something. The answer appears word by word as the model writes it.

The harness underneath

merud is an agent harness: the part that runs a model in a loop, hands it tools, checks each tool call and keeps the record. What makes Meru your assistant, such as searching your files, remembering you and going to the web first, sits on top of that harness. meru, meru chat and the desktop app talk to it, and so can a script, with meru run --json.

What Meru won’t do

Every tool call Meru makes is written to a log you can read with meru log. An incognito chat keeps no record of what you asked; the log still names each tool it called.

Explore further

The roadmap lists the milestones in shipping order.