Troubleshooting#

Start at the layer that failed: service, client connection, stored memory, retrieval, or automatic delivery. A success at one layer does not establish the next.

Service won't start#

Run ormah server status and open http://localhost:8787/. If stopped, start it with ormah server start -d. The graph is at /; /ui is reserved for API routes.

Check ~/.local/share/ormah/logs/ormah.log for startup, port conflict, model download or provider errors. Don't kill an unrelated process occupying the port. If the CLI is missing, check the installation's executable path and shell PATH; app/uv installs normally provide ~/.local/bin/ormah.

On first run, model downloads may delay readiness. If the reranker failed, the service may still be available with conservative embedding-only Whisper. Restart retries provisioning. See Setup.

Tools are missing#

Open Agents and check detection/wiring for your client, then use its reload recipe. Claude Code users should inspect /mcp; Pi users should inspect /ormah:status and pi list. Restart a CLI from the intended project directory after environment/configuration changes.

MCP connectivity depends on the configured executable path. HTTP integrations also need the expected local base URL. A desktop app installation, extension package and Python runtime can be updated independently; see Upgrade and reconnect.

Memory is missing#

1. Inspect the actual remember tool result for an error and node ID.
2. Open that ID in the graph or call recall_node. If it exists, the write worked even if a search ranked it poorly.
3. Compare the node's stored space with the query's filters and default project. CLI --space prioritizes; tool/API spaces can filter.
4. Check both clients use the same running service/store. A shell's .env and a background service may select different data locations.

A direct Markdown edit is picked up by indexing; it is not a live file-watcher write to the graph. Wait for the index update or restart after a controlled offline edit. Use the supported HTTP update/delete operations for ordinary corrections; the graph is read-only. Storage and portability.

Whisper is quiet#

First complete explicit recall. Then check whether your client has a supported hook/extension at all: Claude Desktop setup is MCP only. For Codex CLI, inspect warnings about the hooks feature and the configured events; other Codex surfaces are not covered by that contract.

In a fresh related conversation, inspect the actual pre-prompt hook/extension request and returned context. Correlate the node and event ID when present with the client's delivered prompt. A direct server request or an agent's assertion does not prove injection.

Quiet output can be deliberate: no relevant candidate, an unchanged topic, session deduplication, a conservative fallback gate, or preference inapplicability. Server logs can help distinguish a retrieval miss from a gate rejection; newer runtimes include richer candidate diagnostics. Keep logs local unless redacted. Do not lower every threshold to make a demo speak. Whisper explains the pipeline.

Sessions or files aren't captured#

Check the capture path you enabled. Hook capture, the opt-in session watcher and watched files are distinct. Raw-text extraction requires an available configured provider; choosing agent maintenance alone leaves that provider disabled. Minimum-turn rules, exclusions, closed-turn handling and deduplication can also produce no new memory.

Use a small synthetic session/file and inspect the resulting nodes. An extractor dry run still processes text with the provider, even though it does not store nodes. See Capture from sessions and files.

Duplicate hooks or stale tools#

Check whether Claude Code has both plugin and old CLI-managed registrations. The plugin should own its hooks/MCP in plugin mode. Use /ormah:setup and reload the plugin. On newer runtimes, setup also reconciles redundant global maintenance agents/commands; an older installed runtime may not include all of that cleanup.

If upgrading/re-running setup does not fix an older installation, inspect only the Ormah-owned entries in global client configuration before changing them. Preserve unrelated client settings. Report the install mode, runtime version and exact tool prefix that failed; do not delete an entire client configuration directory.

For Pi, /ormah:upgrade updates the backend, while the package manager updates the extension. Reload after either changes the integration.

Restore or update failed#

Keep the current app/runtime and all snapshots/recovery material. A desktop update check can fail while offline without proving the installed version is current. Use the versioned download if the native updater cannot complete; then reconnect and repeat the retrieval check.

For local restore, keep clients stopped, inspect the reported safety snapshot and error, and use Back up and recover. Don't infer cloud recoverability from a successful upload or invent a sync/export command.

Report a useful issue#

Include the OS/architecture, install path, Python/desktop/extension versions, page/step, synthetic reproduction and exact redacted error. Distinguish what you observed from what remains unverified. Remove memory content, transcripts, account tokens, provider keys and recovery kits from attachments.

Use Ormah issues for runtime/integration problems or a documentation issue for documentation. Contributing explains source development and evaluation.