Developers

TUI User Guide

Memmy TUI is Memmy's full-screen terminal interface. Whether you install the desktop app or just the CLI, you can run memmy in your terminal to use it.

image.png

Installing Memmy TUI

Option 1: Install the Memmy desktop app

For macOS and Windows. The desktop app provides the memmy command and takes care of starting the local Memory and Agent Gateway services.

  1. Download and install the desktop app from the Memmy official website or GitHub Releases.

  2. Launch Memmy and complete setup in either account mode or API key mode.

  3. Open a new terminal and check that the command is available:

memmy --help
memmy --version
  • macOS: drag the app into /Applications and launch it at least once. If your terminal reports that memmy cannot be found, open a new terminal or run:
source ~/.zshrc
  • Windows: after installation, open a new PowerShell or Windows Terminal window.

When using the TUI provided by the desktop app, keep the Memmy desktop app running. Closing it also stops the Gateway it manages.

Option 2: Install only the Memmy CLI

For Linux x64 or arm64 environments that don't need the desktop app. The installer accepts only Node.js 22.23.4 or newer within 22.x, 24.22.1 or newer within 24.x, or 26.12.1 or newer within 26.x, and the system must support systemd --user. Other major versions are rejected.

curl -fsSL https://raw.githubusercontent.com/MemTensor/memmy-agent/main/scripts/install.sh | bash

Once installation finishes, run:

memmy

On first run, if no model is available yet, Memmy opens the setup wizard. The CLI installer manages the Memory and Gateway services; they keep running after you exit the TUI or close the terminal.

Check service status:

systemctl --user status memmy-memory.service
systemctl --user status memmy-gateway.service

First Time Setup

If you already completed onboarding in the desktop app, you can skip this section. CLI users should run:

memmy onboard --defaults
memmy onboard
memmy status
  • memmy onboard --defaults — creates or refreshes the config file and workspace. It asks no questions when the config does not exist yet, or when the terminal is not interactive. If the config already exists in an interactive terminal, it asks whether to overwrite it with defaults.

  • memmy onboard — configures models, providers, Gateway, Memory, and tools interactively.

  • memmy status — checks the current configuration, workspace, model, and provider.

Default locations:

  • Config file: ~/.memmy/config.yaml

  • Workspace: ~/.memmy/workspace

Opening the TUI

Run:

memmy

This opens the default cli:direct session. Type a message and press Enter to send it.

Resuming or creating sessions:

# Resume an existing session
memmy --session cli:work

# Create a new standalone session
memmy --standalone

# Create a session bound to a project directory
memmy --project /path/to/project

--session, --standalone, and --project are mutually exclusive — pick one.

List existing sessions:

memmy sessions list

memmy vs. memmy agent

To open the full-screen TUI covered in this guide, use bare memmy.

memmy agent is for single-turn tasks or conventional terminal interaction:

# Single-turn task
memmy agent --message "Give me an overview of the current workspace"

# Send a single turn from stdin
echo "Summarize this project" | memmy agent

Sending Tasks

Type after the ❯ prompt and press Enter to send. The TUI does not currently support the workbench's Shift + Enter newline; Enter always submits.

Long text wraps visually in the terminal, but you cannot insert multiple lines. To send multi-line text, use:

memmy agent --message $'first line\nsecond line'

or:

printf 'first line\nsecond line\n' | memmy agent

Typing while a task is running

  • Enter — queue the next turn.

  • Tab — append your input to the current turn, when that turn is being executed by this TUI.

If the current turn came from the desktop app or another IM channel, the TUI will not take it over; use Enter to queue instead.

When there are queued tasks, the interface shows the queue count, a message preview, and the message source. The preview lists at most 3 messages.

Keyboard Controls

Basic controls are the same on macOS, Windows, and Linux; the primary modifier for line-editing combinations differs:

ActionmacOSWindowsLinux
Send; queue next turn while runningEnterEnterEnter
Append to the current TUI executed turnTabTabTab
Move one character← / →← / →← / →
Move by word⌘ + ← / ⌘ + →Ctrl + ← / Ctrl + →Ctrl + ← / Ctrl + →
Move to start of inputHome / Ctrl + AHome / Ctrl + AHome / Ctrl + A
Move to end of inputEnd / Ctrl + E / ⌘ + EEnd / Ctrl + EEnd / Ctrl + E
Delete from cursor to start of lineCtrl + U / ⌘ + U / ⌘ + Backspace / ⌘ + DeleteCtrl + UCtrl + U
Delete from cursor to end of lineCtrl + K / ⌘ + KCtrl + KCtrl + K
Delete previous wordCtrl + W / ⌘ + WCtrl + W / Ctrl + BackspaceCtrl + W / Ctrl + Backspace
Delete a characterBackspace / DeleteBackspace / DeleteBackspace / Delete
Stop your own running turn and exitCtrl + CCtrl + CCtrl + C

On macOS, ⌘ is the Command key; Windows and Linux use Ctrl as the primary modifier. Shift + Enter never inserts a newline on any platform — it submits the current message. Backspace and Delete both delete the character before the cursor.

You can also exit by typing any of the following. These commands leave the TUI and do not stop a running turn, including the turn this TUI is running:

exit
quit
/exit
/quit
:q

When the current turn belongs to this TUI, Ctrl + C stops that turn and then exits. When another channel owns the turn, Ctrl + C only exits the TUI.

Slash Commands

Slash command menu

The TUI has a slash-command suggestion menu. Type / in the input area to open it, and keep typing a command name (for example /go) to filter the suggestions. The menu closes once you type a space to enter an argument or subcommand.

  • ↑ / ↓ — move between suggestions.

  • Tab — complete the selected command entry; it does not complete subcommands or arguments.

  • Enter — if the current input is a command prefix, completes it first; if the command entry is already complete, runs the command.

  • Esc — close the suggestion menu.

If Enter only completed the command, press Enter again to run it.

  • The menu shows the commands currently available, along with hints for that command's arguments or subcommands.

  • Arguments and subcommands do not get their own suggestions — for example, with /model list you complete /model first and then type list manually.

  • /stop appears only when the current turn is being executed by this TUI.

  • /new is hidden while another channel owns the current turn.

  • /restart is not shown and cannot be run from the TUI.

  • exit, quit, /exit, /quit, and :q all exit, but only /quit appears in the menu. None of them stop a running turn.

  • Whether /history-dag appears depends on sessionDag.enabled, which is on by default.

  • /dream, /dream-log, and /dream-restore appear only when fileMemory.enabled is true. That switch is off by default.

  • Up to 8 suggestions are shown initially; keep typing a command prefix to filter down to others.

CommandArgumentsPurpose
/helpnoneShow help for the available commands
/statusnoneShow runtime status, provider, and channel status
/modelnoneShow the current model configuration
/model listnoneList model presets
/model <name>a preset name, or a model name that matches one available modelSwitch the model for this session. If the name matches more than one preset, use the preset name. The menu does not list preset identifiers; type the name after completing /model
/historynoneShow session history
/history <n>number of messagesShow the last n history messages
/history-dagnoneShow the session history DAG
/newnoneStop the current task and start a new conversation. Hidden from the menu while another channel owns the current turn
/stopnoneStop the turn currently executed by this TUI; does not stop tasks on other channels
/restartnoneNot accepted by the TUI; exit and restart the Gateway instead
/last-compactionnoneShow the most recent context-compaction summary for this session
/quitnoneExit the TUI without stopping the running turn
/goalnoneShow the current persistent goal
/goal statusnoneShow persistent goal status
/goal helpnoneShow help for the goal subcommands
/goal <objective>goal textShorthand for creating a persistent goal
/goal create <objective>goal textCreate a persistent goal
/goal pausenonePause the goal and stop its current turn
/goal resumenoneResume a paused, blocked, or usage-limited goal
/goal edit <objective>new goal textEdit the goal. An active or completed goal cannot be edited
/goal budget <n|none>a number or noneSet or clear the goal budget
/goal clearnoneClear the goal
/dreamnoneConsolidate memory now. Shown only when fileMemory.enabled is true
/dream-lognoneShow what the latest Dream changed
/dream-restorenoneRestore memory to the previous Dream snapshot
/pairingnoneView or manage channel pairings
/pairing listnoneList channel pairing requests
/pairing approve <code>pairing codeApprove a pairing request
/pairing deny <code>pairing codeDeny a pairing request
/pairing revoke <user_id>user ID, or revoke <channel> <user_id>Revoke a user's pairing

Whether /history-dag is available depends on sessionDag.enabled. It is on by default.

FAQ

memmy: command not found

  • macOS: make sure Memmy has been moved into /Applications and launched at least once, then open a new terminal or run source ~/.zshrc.

  • Windows: open a new PowerShell or Windows Terminal window.

  • Linux: confirm the installer completed successfully, and check that ~/.local/bin is on your PATH.

No model available

memmy onboard
memmy status

Confirm that the model, provider, and credentials have been saved, then run memmy.

Gateway unavailable

  • Desktop app: make sure the Memmy desktop app is running.

  • Linux CLI: check memmy-gateway.service.

  • Running the CLI from source or manually: run memmy gateway in another terminal.

The default Gateway WebSocket port is 18980. On Linux you can check the logs:

journalctl --user -u memmy-gateway.service

Why doesn't memmy agent open the full-screen interface?

That's expected. memmy agent is the single-turn / conventional terminal entry point. For the full-screen TUI, run:

memmy

On this page