--- description: Diagnose service, tool, scope, Whisper, capture and upgrade problems using observable checks. --- # 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/](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](/docs/getting-started/setup#models-and-readiness). ## Tools are missing Open Agents and check detection/wiring for your client, then use its [reload recipe](/docs/integrations/supported-agents). 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](/docs/getting-started/installation#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](/docs/reference/web-ui#correct-content-and-scope) for ordinary corrections; the graph is read-only. [Storage and portability](/docs/how-ormah-works/storage-layer). ## 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](/docs/how-ormah-works/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](/docs/operations/hippocampus-and-session-watcher). ## 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](/docs/use-memory/backup-and-recovery). 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](https://github.com/r-spade/ormah/issues) for runtime/integration problems or [a documentation issue](https://github.com/r-spade/ormah/issues/new?title=Docs%3A%20correction) for documentation. [Contributing](/docs/reference/eval-framework) explains source development and evaluation.