Get started with Mnemo

#Quick start

Three commands from nothing to a working agent. The first line is for macOS and Linux; Windows is just below.

On first run type /login to add a provider key or subscription, then /model to choose a model. No key yet? mnemo --demo plays a scripted session in a scratch project so you can see a turn first. Prefer a download button? The download page has one for your system.

#Installing

The installer downloads one archive holding mnemo and its memory sidecar memsrv, checks its SHA-256 against the release's checksum file, puts both in ~/.mnemo/bin (%USERPROFILE%\.mnemo\bin on Windows) and links mnemo onto your PATH. On a terminal it draws itself as it goes; piped, or with NO_COLOR, it prints plain lines. It never touches your memory or settings, and running it again upgrades in place.

Three ways

• One-line installer: the commands above. Read the script first if you like.
• A downloaded archive: from /download. Unpack it and keep mnemo and memsrv in the same folder on your PATH. On Windows, double-click mnemo.exe in the unzipped folder instead: it offers to put both in %USERPROFILE%\.mnemo\bin and add that to your PATH (mnemo install does the same from a terminal; --yes skips the question).
• From source: needs Bun and a Rust toolchain. CONTRIBUTING.md has the steps.

Installer options

Set these before the command (for example MNEMO_HOME=/opt/mnemo curl … | sh):

• MNEMO_HOME: where Mnemo lives (default ~/.mnemo).
• sh -s -- --uninstall / --deep (Windows: $env:MNEMO_UNINSTALL=1, deep): remove it. See uninstalling.

#First run

1. mnemo doctor reports the model, the memory sidecar and Python. Add --fix to repair what it can (file permissions, a broken settings file, a missing sidecar).
2. Start Mnemo in a project folder: cd my-project && mnemo. It asks once whether to trust the folder's own .agents/ extensions and prompts.
3. /login adds a provider; /model chooses the model; /thinking sets how hard it thinks. Mnemo also uses keys it finds in your environment, such as ANTHROPIC_API_KEY.
4. Ask for something. By default it asks before every edit and command. shift+tab cycles the mode.
5. Type / for the command menu, @ to mention a file, ctrl+k to jump anywhere. Everything is on the shortcuts page.

#Permission modes

The mode decides what Mnemo may do without asking. Only you can change it; it is never a tool the model can call.

Put rules in ~/.mnemo/permissions.json (allow, ask, deny; first match wins, and a deny beats every mode). A file that exists but cannot be parsed stops all edits and commands until it is fixed.

#Memory

After each run Mnemo writes down what it learned about the project and about you, recalls it in the next session, keeps the fix when something failed, and writes skills for itself. It all lives in a local, append-only journal that only you can read: ~/.mnemo/memory/journal.jsonl. Nothing is uploaded.

• /memory shows what it remembers; /memory deploy searches it.
• /remember we deploy with fly tells it something to keep; /forget package manager retires a fact.
• The memory pane (sidebar, key 2): + / - say an item helped or was wrong, e edits, d forgets, m opens the map.
• mnemo memory tidy lists duplicates, facts about files that are gone, and what you marked wrong; --apply retires them.
• Recall is trust-weighted: what helped ranks higher, and what you marked wrong twice stops coming back.

Search quality

Search uses a local hashing embedder, which is offline and plain. To do better, point it at your own embedding server (an Ollama on this machine, say) with MNEMO_EMBED_URL and MNEMO_EMBED_MODEL. For OpenRouter, set MNEMO_EMBED_URL=https://openrouter.ai/api/v1/embeddings and the key in MNEMO_EMBED_KEY. A model key alone sends nothing: until you set MNEMO_EMBED_URL, memory never leaves your machine.

Share it with other agents

The same memory can serve Claude Code (hooks) and Codex, Cursor and opencode (MCP):

Only attach memory to agents and repositories you trust with all of it: a project's identity comes from its git origin.

#Updating

Installs the latest release with the same checksum-checked installer. Inside Mnemo, /update does the same. On Windows the running mnemo.exe can be replaced, so this works from inside the app.

• mnemo update --check only says whether there is a newer version.
• mnemo update --auto on adds a daily check at launch that tells you and never installs on its own. Off by default; until you turn it on, Mnemo contacts nothing but your model provider.
• Installed with Homebrew or Scoop? Use brew upgrade mnemo or scoop update mnemo.
• Pre-releases and older versions are on GitHub; what changed is in the changelog.

#Uninstalling

Removes the program (mnemo, memsrv and the PATH link). What it learned stays: memory, sessions, credentials and settings, so a later install picks up where you left off.

Also deletes ~/.mnemo: memory, sessions, credentials, skills, logs and settings. It lists what it will remove and waits until you type delete. Add --yes to skip the questions in a script.

No working mnemo? The installer does the same, from the same address you installed with:

Add --deep (Windows: $env:MNEMO_UNINSTALL="deep") for the full removal. Installed with Homebrew or Scoop: brew uninstall mnemo / scoop uninstall mnemo, and mnemo uninstall --deep first if you want the data gone.

#Where things live

Everything is under $MNEMO_HOME, which defaults to ~/.mnemo and is private to you (mode 0700).

Project-level files (.agents/ extensions, prompts and skills) load only for folders you trust.

#Troubleshooting

Start with mnemo doctor; it names what is missing. Then:

mnemo: command not found

The installer prints the line to add if your PATH lacks its link folder: export PATH="$HOME/.local/bin:$PATH" in ~/.profile. Or run ~/.mnemo/bin/mnemo directly. On Windows, open a new terminal after installing.

"It is not using my model" / "no model"

Run /login then /model. Mnemo also picks up provider keys from your environment, which can choose a provider by default; unset the ones you do not want.

The memory sidecar is missing or will not start

mnemo doctor --fix reinstalls it. If you keep the binaries in different folders, put memsrv beside mnemo. On Windows, a mnemo.exe run from where it was unzipped, or another mnemo earlier on your PATH, is a common cause: mnemo doctor says so, and mnemo install from the unzipped folder fixes it.

Edits and commands are refused

A permissions.json that cannot be parsed blocks them on purpose. Fix the file (or set it aside) and restart. doctor --fix sets a broken settings file aside.

The mouse wheel scrolls Mnemo and I want to select text

/mouse toggles it, or start with MNEMO_MOUSE=0.

Links, notifications or animations are unwanted

MNEMO_LINKS=0, MNEMO_NOTIFY=0, --no-motion and --no-boot.

A command the agent runs cannot see my API key

That is deliberate. Hand one back with MNEMO_PASS_ENV=NAME.

Still stuck

Open an issue with the output of mnemo doctor and what you did. Mnemo redacts common credential shapes in its logs, but read anything before you paste it. Vulnerabilities go through private reporting, not public issues.