Memo — User Guide

Memo is a privacy-first AI assistant that runs on your own computer. It can chat like any assistant, but it can also act: read and write files, run commands, work through a multi-step checklist unattended, talk to you by voice, watch your WhatsApp/Telegram, and remember what matters across conversations — all without your data ever having to leave your machine, unless you explicitly connect a cloud model.

This guide walks through actually using it, task by task. For the deep technical reference (architecture, file-by-file internals), see the obsidian-doc-en/ vault instead — this file stays practical.

011. Getting Memo running

The wizard walks a new user through everything that used to need a trip to Settings. Required steps carry a trailing *; "Next" is off on a required step that is not done, and the final button is off while any required step is missing. The side list scrolls (there are up to thirteen steps) and every row can be opened directly; compact windows use a single column. Plan and unit history: docs/plans/PLAN_setup_wizard_v2.md.

Steps (* required)

How it decides

The rules are pure functions of a snapshot of the real application state (frontend/lib/widgets/setup/setup_progress.dart): active provider, downloaded chat models, embedding model, mail accounts, the twin reply model. There is no separate progress record, so the wizard resumes where it was left and stays right when something is changed elsewhere. The model step is always required; the reply model step is required only while a mail account exists; everything else is optional.

Running it again

Settings -> General can restart the wizard. A re-run starts from the theme in use and writes the persona prompt only if it was touched in the wizard, so a custom prompt survives (memo_setup_rerun flag, cleared when the run finishes).

Tests

frontend/test/widgets/setup_progress_test.dart (rules), setup_steps_test.dart (step widgets, time zone and drafts writes, both languages) and setup_wizard_test.dart (gating, mail requirement, store window, summary, re-run, the full flow in Turkish and English at 360x900, 1100x900 and 1100x600).

022. Basic chat

• New chat: the + button top-left of the chat list.
• Memory: Memo saves what you tell it and retrieves it automatically on later turns (a hybrid vector + keyword search over everything you've said) — ask about something from a few days ago and it'll actually remember, no manual "remind me" needed.
• Attach a file or image: the +/paperclip icon in the composer, or type @ to mention a specific file by name from the current project folder.
• /insight: ask Memo to look back over your recent mood/memory history for a real pattern — it says so honestly if there isn't enough signal yet, rather than inventing one.
• Quick model switch: click the model/provider pill in the chat's own top bar instead of opening full Settings.
• Incognito Mode: a toggle for a fully ephemeral session — nothing gets written to memory.

033. Connecting a model

You have two independent paths, and you can use both at once (local for memory embeddings, cloud for chat, for example):

Local models (Settings → sidebar → Model Store)

• Search Hugging Face for a GGUF model right inside the app.
• Memo shows a compatibility badge based on your detected RAM/VRAM before you download.
• Background download manager with real progress, pause/resume.
• Hit "Start Model" once downloaded — a local llama-server process starts and Memo talks to it directly, no data leaves your machine.

External providers (Settings → API Providers)

Click "Add Provider" and pick a type. As of this release, 12 provider types plus 2 CLI-based ones are supported:

Every provider except the CLI ones lets you pick a model from a live, fetched-on-the-spot list — nothing is a hardcoded guess. API keys are encrypted at rest (AES-256-GCM, machine-bound key).

If a provider fails repeatedly, Memo's router auto-disables it and falls back to the next enabled one; a background health check re-enables it once it recovers.

044. Agent Mode — giving Memo hands

Start an Agent chat from the Chat | Agent composer and choose its project folder. Memo gives the model a permission-gated toolset:

• Files: read_file, write_file, edit_file, insert_line, delete_lines, delete_file, list_directory, get_file_info, search_files, change_directory
• System: run_command (sandboxed, timeout + a large blocklist of destructive patterns), read_env
• Web: web_search, fetch_page (reads a URL's full content, not just a search snippet)
• Calendar & routines: get_calendar_events, create_routine, list_routines, cancel_routine
• Self: self_clone, configure_provider, share_file
• Task loop control: get_task_status, pause_task, resume_task, create_task_md, edit_task_md, start_self_driving_task — see §5

Messaging tools depend on the connected channel and its permissions.

Every tool call goes through a permission check before it runs, based on a danger level (safe — auto-allowed, medium/dangerous — asks you). You can allow once, allow for the session, or allow forever per tool — forever-allows persist to disk and are manageable from Settings.

055. The Self-Driving Task Loop — hand it a checklist and walk away

This is the headline feature of this release: instead of one chat turn, Memo can work through a whole checklist across many turns, unattended, recovering from the kinds of errors that would previously have just stopped it.

The Task.md format

A plain checklist file. Ask Memo to write one for you in chat (it uses the create_task_md tool), or write it by hand:

# bildirim: önemli
# mod: planlayıcı
# sağlayıcı: sabit
# onay: otomatik

Build a small local blog: signup, salted-hash login, a session cookie,
and a page to write + list posts. Keep it simple, no framework needed.

- [ ] User signup with a hashed password
- [ ] Login that sets a session cookie
- [ ] A larger piece [parallel] — write + list posts
  - [ ] POST endpoint to create a post
  - [ ] GET endpoint that lists posts

---
Any free notes here are ignored by the parser.

Header reference (all optional, any order):

Put [parallel] anywhere in an item's text to let it fan out to sub-agents automatically.

Two ways it runs

• Worker mode — each checkbox item is one agent turn: do it, get reviewed, check it off, move on.
• Planner/executor mode (# mod: planlayıcı) — a planning turn produces a Plan.md (concrete steps, acceptance checks, dependencies) that you approve — either from the Tasks tab's approval card, or automatically with # onay: otomatik. Once approved, steps execute one at a time, each checked against its acceptance criteria before moving on.

Sub-agents, for real parallel work

An item marked [parallel] (or one the planner judges large enough) can split into up to 3 sub-agents: exactly one write-capable coder runs first and alone, then up to 3 read-only analyzer/reviewer/test-runner sub-agents run genuinely at the same time. Their combined output feeds a chief review before the item is marked done. Sub-agents get no long-term memory or persona — just the raw model and whatever skills you've enabled for the task.

Watching and controlling it

• Tasks tab shows every running/paused/done list, with a live activity feed: tool calls, [coder]/[analyzer]-tagged sub-agent turns, a "model is generating" line during long silent calls, and "starting…" lines for slow tools before they finish.
• From chat: ask "how's the task going" — the model has a get_task_status tool for exactly this (phase, step N/M, current item, elapsed time) and is instructed not to guess when it hasn't called it. Say "pause"/"devam" (resume) to control it — pause_task/resume_task carry forward anything you typed while paused into the next step.
• The composer locks while a task is running in that chat, so there's no ambiguity about who's driving.

What happens when something goes wrong

This loop is built to never fail silently:

• A busy chat queues and retries rather than killing the task instantly.
• A rate limit parks the list, waits, and resumes from the exact item it was on — never restarts from the beginning.
• A transient fault (timeout, 5xx) gets an escalating wait-and-retry (5 minutes, then 10) on the same provider before finally parking the item.
• An auth/config fault parks the whole list in a waiting-for-you state instead of retrying forever.
• Every terminal state — done, stuck, parked, failed — sends you a notification (chat message and push), not just a silent status flag.

066. Orchestra Mode — multiple models as a team

An alternative to Agent Mode for work that benefits from splitting across specialized models: a chief plans and assigns sub-tasks to expert roles (planner, frontend, backend, bug_fixer, reviewer, security, devops, general), runs them (in parallel where there's no dependency, sequential where depends_on says so), and synthesizes the results. Configure roles and their models from Settings → Orchestra. Note it's a separate execution path from the Self-Driving task loop above — Orchestra bypasses the provider fallback router and creates its own provider connections directly.

077. Routines — scheduled automation

Sidebar → Routines. Describe what you want in plain language — "every morning at 8, summarize my calendar and send it to me" — and Memo figures out the timing, content, and delivery channel from that sentence alone. A routine can be a simple scheduled message or a full tool-using agent run. Fires in your device's own timezone, resynced on every reconnect.

088. WhatsApp & Telegram

Settings → WhatsApp/Telegram to pair (QR code for WhatsApp, bot token for Telegram). Once paired:

• Self-chat assistant — message yourself and get a full assistant back, same as the desktop chat.
• Third-party takeover — Memo can step into a conversation with someone else on your behalf, either announcing itself or impersonating your writing style (your call, made explicit per-conversation).
• Routines and (on WhatsApp) 4 dedicated agent tools work the same way as in desktop chat.

099. Live Mode — real-time voice

The voice icon next to the chat input opens a full-screen call: pick Google Live or OpenAI Realtime as the engine in Settings first, paste its API key, choose a voice. This is native audio-to-audio — the model actually hears your tone and pauses, not a transcribe-then-read relay.

• Delegate mode (default): the live model's only "tool" is handing real work to your main chat model, then narrating the result back in its own voice.
• Standalone mode: the live model gets your full agent toolset directly — faster, but dangerous tool calls get a spoken permission prompt instead of a screen dialog.
• You can interrupt it mid-sentence (barge-in sensitivity is configurable), and the transcript is kept in your normal chat history afterward.

1010. Settings you'll actually touch

Settings is a searchable rail, not a wall of tabs — type a few letters of what you're after. Worth knowing about specifically:

• System Prompt / Gizli Mod Prompt — how Memo talks to you, and a separate prompt for Incognito sessions.
• Bellek (Memory) — turn memory off entirely, or manage what's stored.
• Öğrenme (Learning) — the proactive-nudge settings from the setup wizard, revisited any time.
• Cloud Sync — Google Drive backup of your data, end-to-end encrypted.
• Uzaktan Erişim (Remote Access) — expose Memo to other devices (Tailscale or ngrok tunnel), with token/password auth required.
• Hafızayı İçe Aktar (Import Memory) — paste another AI's summary of you and Memo breaks it into atomic facts.

1111. Self-hosting

Memo runs standalone on a home server, NAS, or Raspberry Pi (Docker image, CasaOS, or the plain binary). Point another device at it with a Backend URL + Token, same flow the desktop and mobile clients both use. See docs/SELF_HOSTED.md for the setup script and reverse-proxy notes.

1212. If something's not working

• Check docs/TROUBLESHOOTING.md (or the Turkish docs/tr/TROUBLESHOOTING.md) first.
• BUG_REPORT.md at the repo root lists currently-open, known issues — worth a quick check before assuming you've found a new bug.
• For a stuck/misbehaving local backend, memo --kill followed by a relaunch clears most transient state issues.

1313. Mail & Digital Twin

Everything in this section is off by default; nothing is read, drafted or sent until you switch it on. Deep dives: DIGITAL_TWIN_AND_MAIL.md, MAIL_SECURITY.md, DIGITAL_TWIN_APPROVAL.md.

Connecting and reading mail

• Zero-config sign-in. Gmail and Outlook through OAuth (XOAUTH2, no app passwords); any other provider through IMAP/SMTP with settings found from built-in presets or Thunderbird's autoconfig database. Credentials are kept in an encrypted vault on the machine.
• A 60-second watcher. New mail is polled in the background. Only mail that arrives after you connect is handled; the old inbox is never backfilled and a cold start never floods the model.
• Three-layer triage (the Gatekeeper). Layer 1 is structured data and your own contacts (invitations, flights, invoices, one-time codes, people you already write to, active reply threads); layer 2 is standard headers (List-Unsubscribe, Auto-Submitted, Precedence, noreply-style senders); layer 3 is a model, only for what is left. Mail lands in one of five categories and bulk, newsletter and one-time-code mail never enter memory or get a reply.

Protection

• Inbound shield. Deterministic English and Turkish instruction-override, role-delimiter and base64-encoded-instruction checks run before triage, memory indexing and calendar extraction. An optional decision-model review adds a second opinion and fails closed: if it can't answer, the mail is held, not passed. A blocked mail stays readable in the inbox.
• Mail is data, never instructions. Mail text reaches a model inside an untrusted-data envelope, and the research assistant that reads it has four read-only tools only (contact history, memory search, calendar availability, git status of a registered project).
• Outbound scan. Subject, body, To/Cc and drafts are checked for API keys, private-key blocks, KEY=value lines and recently seen one-time codes before any connection is opened.
• Privacy wall. The model sees only masked free/busy ranges from your calendar, never titles, places or guests, and other people's data never leaks into a reply.

The twin

• One person, every channel. Link a person's mail address and WhatsApp number; a timeline shows both with their original dates, and a "tomorrow" written last week keeps its meaning. People are never merged by name alone.
• Your style, not a clone. A plain summary (formal or casual, language, greeting) from your last 100 sent messages; it says so when examples are few.
• Prepared replies. Read-only research, then a draft in your style, uploaded to the account's Drafts folder and shown in Mail → Replies, where you edit and send it yourself. A separate reply model writes the text; the decision model only scores.
• Per-person policy never / draft_only (default) / full_auto.
• Approval from anywhere. In the app, or on WhatsApp and Telegram with #onay N, #iptal N, #asla N (only your own chat is accepted).
• Automatic sending with an undo window. For a full auto person, a reply waits a 60-second window (adjustable); at the moment of sending every rule is re-checked, plus an independent confidence score of at least 0.95. Groups and CC are never answered automatically, nothing is sent twice, mail older than six hours is never answered on its own, one automatic reply per person per hour at most, and after a restart whatever still waits returns to you.
• Calendar-aware. An .ics invitation is added with a note to review, conflicts are flagged, up to two alternatives are offered, and the reply never reveals other events.
• Follow-up radar and promises. A review-only reminder draft for answers you are waiting on (one per person, groups never nagged), and tracking of your own dated promises.
• Chat tools. Pending drafts, open commitments, a contact's timeline and the unfinished work of your projects; /mail and /twin in the terminal; a message can become an idle Self-Driving task, only on your say-so.

1414. Daily briefing

• Morning card. Today's meetings, what was prepared overnight, drafts waiting, overdue replies, promises due, unfinished code work. Built from local data, no model needed.
• Pre-meeting note. 5–120 minutes ahead (15 by default): promises to that person, replies you wait for, waiting drafts, recent messages.
• Yours to shape. Any half hour; any mix of six built-in sections (meetings, overnight, drafts, waiting, promises, code); up to five custom items (a title plus an instruction or reminder); an optional briefing model, separate from the reply model. With a model, it writes a short summary and answers the custom items from the day's data (which goes to the provider you picked); without one, custom items appear exactly as written, and a failed model never blocks the card.
• Channels. Always the app; optionally Telegram (your owner chat), WhatsApp (your own number) and/or mail (your own address, from the account you pick), any combination, only ever to you. Each send is claimed before it starts (briefing_deliveries), a restart can never send it twice, an unsure send is not repeated, and a failed one is retried up to five times, five minutes apart, within six hours. Outbound secret scan first. Only the morning briefing leaves the app.
• Settings live in the twin preferences (twin.db), not config.yaml.

1515. Projects and skills

Open a folder as a project and Memo can keep a small .memo/ folder in it — generic working rules, notes — plus AGENTS.md and handoff.md in the root (never overwriting anything). A one-line session-start instruction tells the model to read .memo/AGENTS.md first; the files are not pasted into the prompt. Each project gets a stable id, so its memory follows it when the folder moves; a project chat reads and writes only its own project's memory and never sees your general memory, name or style notes, while an ordinary chat still sees everything. Project skills (/skill add owner/repo) are instructions only and stay out of the prompt until switched on. Your home folder and Memo's own ~/.memo can never be a project. Minimal Mode adds nothing. Details: PROJECT_FOLDER.md.

1616. One chat list and sub-agents

• One chat list. The Agent tab is gone; an agent chat is a chat with a project folder, marked with a robot. New chats start on a Chat | Agent screen with a centred composer; a blank chat is reused instead of piling up.
• Live agent. The model's text, thinking and each tool call stream in order, grouped and expandable; stopping keeps what you saw; long turns keep the task instead of forgetting it; an empty step after tool use is nudged to answer.
• Chat sub-agents. Bounded background jobs with their own focused context (never your memory or persona), isolated project copies for parallel writers merged one at a time, a durable per-chat queue, live cards you can open and steer, a history list, and the selected provider and model carried over. Settings → Chat sub-agents sets how many run at once (1–16, default 3). See CHAT_SUBAGENTS.md.
• Skills by name. /pair-programming or "using the Pair Programming skill" in a message switches it on for that chat; / lists installed skills and real commands (/remember, /forget, /model, /orchestra).
• Terminal next to the app. The REPL's settings are per session and it no longer moves the desktop app's open chat.

1717. Privacy and usage sharing

Memo keeps chat history and memory on your machine. When you choose an external model, the context sent for that request is processed by that provider. Remote access, mail, messaging and cloud backup use the services you connect.

18Official builds

The daily usage summary is on by default, including an upgrade from a version without this feature. Turn it off in the setup wizard or Settings → Privacy. An existing off preference is preserved. Source builds do not send daily reports unless you enable sharing.

The summary includes a random installation ID, version and platform, coarse hardware information, model/provider usage counts, token totals, error classes, update results, Memo crash locations and feature counters. It does not include messages, replies, memory contents, contacts, mail addresses, files, project names, credentials or personal file paths.

19A separate installation count

Official builds send a one-time count per data directory with version, operating system and architecture, without an installation ID. This is separate from the daily report and still happens when the daily sharing switch is off. Source builds and MEMO_TELEMETRY=off do not send it.

20Inspect and control

Use memo telemetry status, preview, on, off, reset-id and delete in the terminal. The preview shows the report before submission. The server can see the source IP of an HTTPS connection even though no IP field is included in the report body.

21Backups and permissions

Encrypted backups are optional. Agent tools use permissions; external services are chosen by you. Usage sharing contains no conversation content, but a random ID connects daily reports for one installation. Read the source inventory for all fields and the limits of client-side verification.