Setup

Setup is the configuration phase that wires Ormah into your environment: auto-start, maintenance mode, integrations, and optional transcript backfill.

If you install Ormah with the shell installer, this setup flow runs automatically unless you use --no-setup. If you install manually, run ormah setup yourself.

If you install via the Claude Code plugin, /ormah:setup runs ormah setup --skip-client-setup instead. This handles the server, models, and auto-start, but deliberately skips auto-wiring other detected clients. Ormah is wired into Claude Code by the plugin itself. Other agents you use — Codex, Claude Desktop — will not be configured automatically. Run ormah setup in a terminal afterward to wire those up.

What setup does

1. Find the binary

Setup resolves the ormah binary path and validates the environment.

2. Detect available integrations

Setup checks for supported local integrations and configures the ones it finds. You can re-run ormah setup at any time to pick up newly installed clients.

3. Choose maintenance mode

You'll be asked whether Ormah should use agent-backed maintenance.

• Agent-backed (recommended) — graph cleanup tasks (linking, conflict detection, deduplication) are delegated to your agent via MCP. No local LLM required. Setup sets ORMAH_LLM_PROVIDER=none.
• Local LLM — maintenance runs on a local model via Ollama or another provider you configure.

note If you pick agent-backed maintenance, Claude Code or Codex will occasionally call run_maintenance as part of normal sessions. This is expected behavior — it keeps the memory graph healthy without you having to think about it.

4. Preload models

Ormah uses local embedding and reranker models for search and whisper:

• Embedding: BAAI/bge-base-en-v1.5 (~420 MB, 768-dim)
• Reranker: cross-encoder/ms-marco-MiniLM-L-6-v2

These download once on first setup and run fully locally after that.

5. Generate server wrapper and install auto-start

Setup writes ~/.config/ormah/start-server.sh and installs a launchd (macOS) or systemd user service (Linux) so the server starts on login.

6. Install integrations

For each detected integration, setup wires in the local MCP server and any supported hooks.

Claude Code

• UserPromptSubmit → ormah whisper inject (surfaces memories before each response)
• PreCompact → ormah whisper store (ingests session on compaction)
• SessionEnd → ormah whisper store (ingests session on close)

Codex

• writes ~/.codex/hooks.json with equivalent hooks
• enables MCP integration

Claude Desktop

• registers the MCP server in Claude Desktop's config

See Supported Agents for the current list of first-class supported clients and upcoming integrations.

7. Transcript backfill (optional)

Setup can discover recent transcript files from Claude Code or Codex sessions and ingest them so your memory graph starts with historical context. You'll be shown an estimate before anything is ingested.

Re-running setup

ormah setup is safe to re-run. It's useful when you:

• install a new client
• want to change your maintenance mode
• need to re-register hooks after updating Ormah

Whisper hook setup only

To install or update only the Claude Code hooks (without the full setup flow):

ormah whisper setup              # local project hooks
ormah whisper setup --global     # global hooks