User manual

Everything she does, and where to find it. For v1.0.1.

The window

Three things, and that's the whole app:

• The conversation — the middle. Type at the bottom, press Enter.
• The top bar — the dials and switches that decide how she behaves.
• Her world — the ☰ menu on the right. Every panel lives in there.

Nothing is hidden in a right-click menu. If you can't find something, it's in Her world.

She runs entirely on your machine. The model doing the thinking is Ollama, installed separately, running locally. There is no account and no server — which is also why she is exactly as capable as your hardware lets her be. That's the trade.

🐧 On Linux, her window is a browser window

On Windows and macOS EMMA opens as an ordinary application window. On Linux she doesn't, and this is expected rather than something broken:

• If you have Chrome, Chromium, Brave or Edge installed, she opens in a separate, frameless window of her own — no tabs, no address bar, her own icon in the taskbar, and a private profile that never touches your browsing session. It looks and behaves much like an app window.
• If you don't, she opens as a tab in your default browser instead.

Either way she is running locally exactly as she does everywhere else — nothing is going over the internet, and every feature works. The native Linux window needs a system library that isn't in the installer yet; it's a known gap and it's on the roadmap.

Closing that window does not stop her, which is the one practical difference. On Windows and macOS closing EMMA's window quits her; on Linux she carries on running in the background — which is also what lets her dream overnight. To stop her completely, either stop the background service (systemctl --user stop emma.service) if you installed it, or quit the emma process from your system monitor.

The top bar

Left to right:

The spine dial

Click to cycle. This is tone, not capability:

• Agreeable — leans towards support, rarely pushes back.
• Candid (default) — honest with you, and will disagree, kindly.
• Challenging — argues her side and holds her ground, with receipts.

Talking to her

Type in the box and press Enter. Stop appears while she's working — press it and she stops mid-sentence.

Voice. Turn it on in Settings → Her voice. You can talk hands-free and interrupt her mid-sentence, like you would a person. She has several voices, and she'll drop to a whisper late at night.

Files. Drag a document, image, audio or video file into the conversation and ask about it.

The two commands worth knowing

/papercut the drawer scrollbar was hidden on my screen

Logs something that annoyed you. No model call, nothing sent anywhere — it just writes a line to a file on your disk. /pc is the short form.

/papercuts

Shows everything you've logged, bundled with your OS, hardware and version, and a Copy all button. Paste that into an email and it's the single most useful thing you can send.

What she remembers

Open the memory panel in the top bar. It isn't a black box — you can read all of it, edit it, and delete it.

Looking for everything ever said? That's two other places: Chats in the top bar for your threads, and Her world → Search to search across years.

Things I want to check

A memory that's years old has one failure mode nothing else does: it remembers things that stopped being true. You moved. You quit. You changed your mind.

So she reads back over what she knows while you sleep, and when two things collide she raises it — "you told me you were vegetarian last year, still true?" — with both versions shown side by side. She asks; she never edits. She can't know which one is right, so she doesn't guess.

Three answers, and "both are true" is a real one — people genuinely do contain multitudes. Answering is the only place in EMMA where a fact is forgotten because you said so.

Making her forget

• Forget everything about… — name a topic, and she shows you exactly what would go before anything is deleted. Nothing disappears before you've seen the list.
• Forget the last hour — for when you said something you'd rather she didn't keep.

Encryption

Settings → Encrypt memory at rest. AES-256, key held in your operating system's keychain.

Letting her use your computer

She can read files, write files, run commands, and drive a browser. The safety dial in the top bar decides how much of that happens without your say-so. Click it to cycle:

"Changes your system" means changes your system — writing a file, creating a folder, running a command. Not a judgement about whether it's harmful.

Two things sit above the dial and apply even on Full:

• Protected paths — SSH keys, GPG, cloud credentials. Refused at every dial position, no exceptions. Add your own in Settings → Protected paths.
• The audit log — everything she does, in a tamper-evident chain, readable line by line under Her world → Activity.

And two ways back: Stop halts her mid-task, and Undo reverses file changes she made — in Her world → Activity, under Reversible changes.

Watch me (computer use) in Settings lets her see and drive the screen. She says what she's about to do before she does it, and hands control straight back the moment you touch the mouse.

Her world — all the panels

Everything under the ☰ menu, in menu order:

Settings

Her world → Settings. Everything below is off unless you turn it on, and this is the order you'll meet them in on screen.

The top of the panel

• How she looks — dark or light, and the colour she's drawn in.
• Her voice — which voice she speaks in.
• Family voices — a voice per person. Consent is required and recorded.
• Kid mode — a restricted EMMA with a bedtime. See Everyone else in the house.
• Encrypt memory at rest — AES-256, and your recovery key. See What she remembers.
• Let her remember the screen — she can see what's on it.
• Let her hear the room — ambient listening, with a Forget what she's holding button.
• Check for updates — see Trial, licence, updates.
• License — your key, and what's left of your trial. See Trial, licence, updates.
• Watch me (computer use) — lets her see and drive the screen. She says what she's about to do before she does it, and hands control straight back the moment you touch the mouse.
• Knowing who's speaking — she recognises enrolled voices and greets each person as themselves. Needs a one-time voice-model download (about a quarter of a gigabyte, checksummed, and only fetched when you click). Not available on Intel Macs.
• Let your other tools ask her — see Letting your other tools ask her.

Her senses

• The air in the room — plug in a USB CO₂ monitor and "why do I feel foggy at 3pm?" gets a real answer. No sensor, no guessing.
• The posture nudge — an occasional webcam glance. No frame is ever written down.
• Who's home — from devices you registered by hand. Everything else on the network is counted, never identified. Optionally goes discreet when a guest arrives.

What she may do without asking

• Research while you sleep — deliberately a separate consent from "search when I ask", because they're different questions.
• Notice when you've changed your mind — she'll ask about it once, and never deletes either version.
• Use a second, smaller brain for narrow jobs, with every route recorded.
• Let her grow to fit you — overnight training on your corrections, never on your chat.
• Keep meeting recordings — normally the audio is destroyed the moment it's transcribed.

Where she looks

• Calendar folders — point her at local .ics files and the morning briefing finally knows your real day. A web address is refused, not quietly ignored.
• Picture generator — point her at AUTOMATIC1111, SD.Next or Forge if you run one.

Services that report in

• Morning dispatch folders — point her at a folder where a service you run drops a small digest of what needs a person (counts, never content), and it joins the morning stand-up. Ask "how are my apps doing?" any time for the same on demand. Dormant until you point her at a folder; a web address is refused. What she already understands about systems below lists the general admin knowledge she ships with — it holds no data about any system of yours.

Your email

• Let her read your email and Let her send email as you — two separate switches, and sending is off. See Your email.

Protected paths

Folders she may never touch, at any dial position. Credentials and key stores are in there already. Add your own.

Dream Mode

Turn it on before bed. Overnight she goes back over what you've talked about, joins up things you said months apart, and has something worth saying in the morning.

Everything is in the Dreams panel in the top bar. The switches, in order:

• Dream Mode — the master switch. She sleeps on the day when you open her in the morning.
• Dream journal — she also writes a short, surreal entry. She's allowed to be weird in here.
• Mood — she gently senses the emotional tenor of your days. Private, and never shown to anyone.
• Rituals — a morning stand-up and an evening wind-down card, bookending your day.
• Dream automatically overnight, around ‹hour› — so she's already dreamt when you wake, rather than dreaming while you wait. This runs while EMMA is up; to dream with the window closed, install the background service (desktop/install.sh --service).
• Whisper after dark — softens her spoken replies between the hours you set.
• Sleep on it now — don't wait for tonight.

And what she leaves you:

• On this day — what was happening a year ago
• Sleep on a problem — hand her something before bed, get her thinking on it
• What EMMA's wondering about you — the questions she's sitting with
• Mood over time — yours, across the year
• Dream journal — what she actually thought about
• Past briefings — every morning briefing she's given you

It's the strangest thing she does and the thing most people end up liking most.

Everyone else in the house

EMMA is one being with many relationships — not one shared account.

• Family voices + voice recognition — say hello and she knows who you are, and greets you like it. Everyone gets their own memories, not one shared assistant treating the room as a single person. Nobody is recognised until they've enrolled themselves on purpose; she keeps a mathematical fingerprint of a voice and never a recording.
• Kid mode — a restricted EMMA with a bedtime. Restriction is the resting state: she starts restricted and stays that way until an adult says otherwise.
• Sanctuary mode (Alt+Shift+S) — for lending someone your laptop. Everything goes discreet at once.

Your email

Settings → Your email. Off until you turn it on.

She talks to your mail server directly from this machine over IMAP — no OAuth app, no consent screen, no third party in the loop:

• Proton — through Proton Bridge on 127.0.0.1, so nothing leaves your computer. (Bridge needs a paid Proton plan.)
• Gmail — on an app password.
• Something else — any IMAP server.

Passwords go into your OS keychain, never into a settings file.

Reading and sending are two separate switches, and sending is off. With reading on, she triages what's waiting into your morning briefing. With sending on, she writes replies in your voice — learned from your own Sent folder — and files them to Drafts. She has no way to delete anything.

Letting your other tools ask her

Settings → Let your other tools ask her, or Her world → MCP connections.

Point Claude Code, Cursor or Zed at your EMMA and they can ask who you are — your facts, your style, your projects — and the answer never leaves your disk. It's read-only, and the panel shows you exactly what they'll be able to ask before you switch it on. There's a Copy config button for your editor's MCP settings.

Backups, moving machines, leaving

Memory → Export Soul File gives you her entire brain as a single file you own. That one file is your backup, your migration, and your exit.

• Backing up — she takes automatic backups, and you can export whenever you like.
• Moving to a new machine — export on the old one, install on the new one, import.
• Leaving — export, then uninstall like any other app. Nothing is held back and nothing is kept anywhere else, because there is nowhere else.

Where her files actually live

Her memory is emma.db in there. Set EMMA_DATA_DIR to put it somewhere else.

Trial, licence, updates

60 days, everything unlocked, no account. When it ends she becomes a read-only companion — still talking, export still working, nothing deleted. Buy six months later and everything she remembered is still there.

£149 once, yours forever, from the pricing section. Your key arrives by email straight after checkout. Your licence is checked on your own machine, with no server involved. 14-day no-questions refund — full terms in plain English in the licence.

Updates never happen on their own. Settings → Check for updates → Check now. If there's one, pressing Update downloads the installer, checks it against the checksum published in the release notes, and starts it. What happens next depends on how she was installed:

She will never update herself behind your back.

Getting a human

Both of these reach the person who built her:

• The EMMA Discord — install help in #install, skills people are passing around in #skills, everything else in #chat. Fastest, and someone else may have hit the same thing.
• loosekeyz84@proton.me — anything at all, including "this is broken".

Security problems: Gregorymoores@proton.me, and please not a public issue.

There's no support desk. It's one person, and he reads everything.