Architecture

For contributors: how the pieces fit together.

Crates #

mimir-core modules #

How a message becomes a reply #

1. A channel listener (or the UI's send_local) receives a message for a bot and chat.
2. turn builds the instructions: the bot's role, standing memory, accepted skills, the conversation.
3. provider runs the bot's AI account. For the CLIs, it passes MCP arguments so the CLI starts <app> mcp … and sees Mimir's tools; for APIs, tools are function definitions handled in-process.
4. Each tool call goes through tools::call: the allow / ask / deny rule, taint (outside content read in this conversation), the bot's allowlist, then the tool itself. "Ask" creates an approval and waits for your answer from any app.
5. The reply streams back to where you asked; the run and every tool call are recorded.

Desktop and server #

Both run the same Host. The desktop calls it in-process through one Tauri command (api); the server exposes it as POST /api/<cmd> with a bearer token. The UI's invoke() goes to whichever is active, so the same React app is the desktop UI and the web UI. A few commands are handled by the desktop itself, before the host, because they belong to this computer: meeting (recording, the meetings list), keep_awake, quick_shortcut, selftest.

Meetings #

mimir-desktop/src/meeting.rs records (cpal for the microphone; a Core Audio process tap on macOS 14.4+, else ScreenCaptureKit / WASAPI loopback / parec for the computer's sound), chunks at pauses, and calls transcribe (whisper.cpp through whisper-rs, with Silero VAD run separately because whisper-rs's per-state call skips whisper.cpp's own). After Stop, speaker separation runs through sherpa-rs (feature diarize, linked in, macOS and Windows) or, on Linux, sherpa-onnx's shared libraries downloaded on first use and loaded at runtime (feature diarize-dl: transcribe::sherpa_dl, structs mirroring its C API). Call detection (mic_in_use) is per OS. See Meetings.

Build notes:

• whisper.cpp builds with cmake (and libclang on Linux).
• .cargo/config.toml sets GGML_NATIVE=OFF (+ AVX2 on x86) so builds run on any CPU of the platform.
• The desktop build.rs adds the /usr/lib/swift rpath that ScreenCaptureKit's Swift bridge needs on macOS.
• Speech models must be freed before exit (transcribe::unload), or Metal aborts.

Learning #

Bots can't be fine-tuned (they run on your own subscription), so they improve only through memory and skills, and everything learned is a proposal you accept, with its provenance recorded. Signals are objective (corrections, stops, denials, failed actions), never the model judging its own success. Nothing learned can change permissions, tool grants, saved logins or schedules. See Memory for the user-facing side, and reports/ (local, not published) for the research behind it.

Security rules in the code #

The Security model in terms of where it lives. Keep these when changing the code.

• Outside content.
  • ToolCtx::taint marks the run (runs.tainted) and the conversation (conv_taint).
  • is_tainted also re-reads the run, so the tools server sees what the parent process marked.
  • What carries the mark: routines.tainted, approvals.tainted (restored by run_parked), suggestions.tainted, digest_items.tainted, and Db::recent_outside for replayed history (only after the fresh:{bot}:{chat} marker).
  • A file's or forward's text is wrapped by with_document (its position math uses ASCII lowercasing).
• The gate.
  • tools::call: precheck (limits, before any card), then gate, then leaks_out (data-carrying reads), then the approval.
  • card_text builds every card.
  • site_of / ext::host_allowed parse hosts with url::Url and refuse user info.
• Learning.
  • Db::bootstrap and automatic recall skip unconfirmed memories, and Entry::line flattens text.
  • The tidy-up sees unconfirmed memories by title only, and labels outside lines.
  • suggestion_decide carries the mark into accepted entries.
• Channels.
  • Core::sender_ok: only the person who paired a chat (chats.owner; chats.dm for direct chats).
  • Every Telegram, Slack and Discord entry point passes a Sender.
  • The listener loop recovers from panics.
• Processes.
  • The AI CLIs get instructions through private files (Private), never the command line: Claude --append-system-prompt-file, Codex model_instructions_file, Grok a rules file in a trusted per-bot-and-chat folder (grok_trust, grok_rules; Windows keeps --rules).
  • PDFs are read by <binary> read-pdf (pdf_helper_main).
  • The AI CLIs' transcripts are removed by Provider::forget_session.
  • Host::new does startup cleanup (incognito_leftovers, prune_old, tmp/, old media). Never put that in Db::open: the tools server opens the database on every turn.
• Downloads. transcribe::download(url, path, min, sha256) with pinned hashes. Models come from a fixed Hugging Face revision.

Data #

One SQLite file in the data folder (~/.mimir, or MIMIR_HOME). Schema changes are additive (add_col in Db::open), so an older database opens in a newer build. Installs from before the rename to Mimir (~/.botpoc, botpoc.db) are moved over once on startup.

Environment variables #

Releases #

.github/workflows/release.yml builds the installers when a version tag is pushed:

1. Set version in crates/mimir-desktop/tauri.conf.json (the tag must match it; the workflow checks).
2. git tag v0.1.0 && git push origin v0.1.0.
3. The workflow drafts a GitHub release and attaches the .dmg, .exe/.msi, .deb/.rpm and .AppImage (macOS on Apple silicon; Linux built on Ubuntu 22.04 so it runs on older systems).
4. Read the draft over, paste the "Unreleased" section of CHANGELOG.md into its notes (installed apps show them with the update), rename that section to the version, and publish.

The Mac app is ad-hoc signed (signingIdentity: "-"), which Apple silicon needs to open a downloaded app at all; it isn't notarized, and Windows builds aren't signed.

Updates (crates/mimir-desktop/src/update.rs, Tauri's updater plugin). Apps read latest.json from the newest published release (plugins.updater.endpoints in tauri.conf.json; drafts aren't served), so publishing the draft is what ships an update. With the TAURI_SIGNING_PRIVATE_KEY and TAURI_SIGNING_PRIVATE_KEY_PASSWORD secrets set, each build signs its update files (.app.tar.gz, the installers) and a last job writes latest.json from those signatures; without them, releases still build but installed apps don't see them. Apps refuse anything not signed by the private key whose public half is in tauri.conf.json: losing that key means users must reinstall by hand once, so keep a copy somewhere safe. End-to-end test on a Mac: build 0.1.1 signed and 0.1.0 pointed at a local server (--config '{"plugins":{"updater":{"endpoints":["http://127.0.0.1:8899/latest.json"],"dangerousInsecureTransportProtocol":true}}}'), serve the first, and start the second with MIMIR_UPDATE_TEST=1: it installs and restarts as 0.1.1.

Tests #

cargo test --workspace          # unit and integration tests (needs cmake for the desktop crate)
cd ui && npx tsc -b             # the UI typecheck (`tsc -p .` checks nothing here)

Test hooks and opt-in tests:

• MIMIR_SELFTEST=1 <desktop binary>: starts the real app, reports what rendered, exits 0 only without UI errors (CI runs this on all three OSes).
• MIMIR_MEETING_TEST=<seconds> (+ MIMIR_MEETING_TEST_QUIT=1): records for that long, then stops (or quits) and prints what was saved. With PulseAudio null sinks in a container, this tests the whole meeting pipeline on Linux.
• MIMIR_WHISPER_DEBUG=1: prints voice-activity stretches and chunk timings.
• scripts/mock-telegram.py: a fake Telegram Bot API; set MIMIR_TELEGRAM_API to it.
• scripts/learning-eval.py <mimir binary> [model] [--control] [--web]: does learning work end to end? A simulated person with three hidden preferences talks to a real bot for three "days", correcting it; the tidy-up runs between days. Prints how many replies broke a preference each day (with learning it should drop to about zero by day 2). --control learns nothing, for comparison; --web forces a web search on day 1 (learning must survive it).
• MIMIR_UPDATE_TEST=1: checks for an update after 3 s and installs what it finds (the update test, see Releases).
• Ignored tests that need real models or files (run with -- --ignored): builtin_real, diarize_real, speakers_real, calendar_real, mic_probe. Each says which variables to set.