Skip to content
docsGitHub ↗
Documentation

Search the docs

Loading search…

    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.