Installation

Installation is about getting Ormah onto your machine. For most users, the shell installer is the right path: it installs Ormah and runs the initial setup automatically.

Requirements

• Python 3.11 or later
• macOS, Linux, or Windows (WSL)
• ~500 MB disk space for local embedding models

Shell installer (recommended)

bash <(curl -fsSL https://ormah.me/install.sh)

This is the fastest path. The installer:

1. installs ormah via uv tool install
2. places the binary at ~/.local/bin/ormah
3. adds ~/.local/bin to your PATH if needed
4. runs the initial setup flow automatically

If you install with --no-setup, or if you install manually, run ormah setup afterward.

Manual install with uv

If you manage your own Python tooling:

uv tool install ormah

Or install into an existing environment:

pip install ormah

Manual installation only installs the package. It does not configure Ormah for local use. After a manual install, run:

ormah setup

Claude Code Plugin

If you use Claude Code, you can install Ormah entirely from within Claude Code.

Inside Claude Code:

/plugin marketplace add r-spade/ormah
/plugin install ormah@ormah

Reload when prompted, then run:

/ormah:setup

Claude will guide you through installing the local Ormah runtime. If ormah is not already installed, it will ask permission to run the shell installer with --no-setup, then configure Ormah in plugin-safe mode.

note Plugin-safe mode does not auto-wire other detected clients such as Codex or Claude Desktop. If you use those agents alongside Claude Code, run ormah setup in a terminal afterward to wire them up.

After setup, confirm the MCP server is active via /mcp — enable it there if it is not already.

Data locations

Ormah stores everything locally. No data leaves your machine.

What	Path
Memory files	~/.local/share/ormah/memory/nodes/
SQLite index	~/.local/share/ormah/memory/index.db
Config	~/.config/ormah/.env
Server wrapper	~/.config/ormah/start-server.sh
Logs	~/.local/share/ormah/logs/ormah.log
Whisper cursors	~/.cache/ormah/whisper-cursors.json

Memory files are plain markdown — you can read, edit, or version-control them directly.

Server management

ormah server start       # start in foreground
ormah server start -d    # start as background daemon
ormah server stop        # stop the server
ormah server status      # check health

Auto-start

The setup phase installs auto-start so the server launches on login:

• macOS — launchd agent
• Linux — systemd user service

To check logs:

tail -f ~/.local/share/ormah/logs/ormah.log

Uninstall

ormah uninstall

This removes Ormah integrations, local data, cached state, auto-start configuration, and attempts to uninstall the package itself.

If the package uninstall step fails for any reason, you can remove the binary manually with:

uv tool uninstall ormah