On this page
Setup#
Setup prepares the local runtime and connects detected clients. You can keep its retrieval-only configuration, then enable capture or a maintenance provider when you need them.
What setup changes#
ormah setup detects supported clients, asks about maintenance, prepares the global config, preloads local models, starts the service and wires detected clients. Client wiring adds hooks/tools and shared guidance; it does not install the coding agents themselves. The app's Agents panel lets you connect or disconnect individual detected clients.
| Choice | Effect |
|---|---|
| Local retrieval | Default embedding_provider=local; stores/searches memories without a separate Ormah generation provider. First startup may download model weights. |
| Agent-driven maintenance | A supported agent performs classification when maintenance is due. Choosing this mode in setup sets the server LLM provider to none. It does not provide transcript extraction. |
| Server LLM provider | Optional ollama or litellm provider for extraction and model-dependent maintenance. Needs an available model and, where applicable, a deliberately selected credential. |
| Autostart | Setup registers/starts a local background service using the platform's service manager or supported fallback. |
| Client connections | Claude Code and Codex CLI use hooks plus MCP; Pi uses its native extension; Claude Desktop setup is macOS MCP only. |
No separate generation provider is needed for your first explicit remember/recall. Automatic transcript extraction needs a configured provider or a caller supplying pre-extracted memories. Installing hooks or enabling agent maintenance alone does not enable extraction.
Setup modes#
ormah setup
| Mode | Use it for |
|---|---|
--update |
Reapply setup without interactive questions, including detected-client wiring. |
--skip-client-setup |
Prepare runtime/models/service while letting a plugin manage the client. |
--json |
Noninteractive agent wiring with a structured result; used by the desktop app. |
--ci |
Noninteractive setup for controlled environments; not a guarantee of a disposable store. |
These modes change local files and services. For an existing plugin installation, follow the plugin workflow.
Change a provider#
Settings live in ~/.config/ormah/.env. Environment variables override dotenv values; a .env in the process working directory can override the global dotenv. Use Configuration for exact names and defaults.
Example for a separately installed, running local Ollama model:
ORMAH_LLM_PROVIDER=ollama
ORMAH_LLM_MODEL=llama3.2
ORMAH_LLM_BASE_URL=http://localhost:11434
This is configuration text, not a command that starts or downloads Ollama. If using a remote provider through LiteLLM, deliberately choose the model and credential environment variable. ORMAH_LLM_INHERIT_API_KEY defaults to false; don't assume an unrelated shell credential is automatically used by the service. Provider data boundaries.
After changing settings, quit the desktop app if it controls the service, then restart the runtime:
ormah server stop
ormah server start -d
Reopen the app and reconnect your client. The stop command removes autostart; the daemon start re-establishes the managed start path.
Models and readiness#
The defaults are BAAI/bge-base-en-v1.5 for local embeddings and Xenova/ms-marco-MiniLM-L-6-v2 for Whisper reranking. Startup attempts to provision model weights. A failed reranker download can leave retrieval available with a more conservative Whisper path, and provisioning is retried on the next server start.
Check service status and its log for download or model errors. A running service, successful explicit recall, and automatic-context delivery are separate Quickstart checks.
Reconnect an agent#
Open the Agents panel after installing a client or changing its executable location. Connect that client and restart/reload it using its recipe. A “connected” wiring status indicates configuration exists; it does not prove that the client actually ran a hook.
For CLI-managed integrations, ormah setup --update refreshes wiring. For Claude Code plugin mode, use /ormah:setup; for Pi, /ormah:setup followed by /reload. See Upgrade and reconnect when binaries or packages also changed.