Troubleshooting

Troubleshooting

Start with read-only checks in an activated project:

mnemo --version
mnemo setup status --agent=all
mnemo doctor --agent=all --path=.
mnemo db migrate --check

setup status reports whether integrations, MCP, runtime hooks and instructions are installed. Codex Hooks: review means Codex has not yet trusted its installed hooks: open Codex and approve its interactive prompt, then rerun status and doctor. Do not copy trust hashes between machines.

Symptom	Check	Action
Agent ignores mnemo	.mnemo has a nonempty id; run mnemo doctor --agent=<agent> --path=.	Activate with mnemo init --agent=<agent>.
MCP or publisher cannot reach controller	mnemo setup status --agent=all, ~/.mnemo/config.toml	Run mnemo setup refresh --agent=all and restart the agent. Check the per-user service manager if it still fails.
Memory write fails after hook start	Native execution ID carrier and controller availability	Inspect agent hook/plugin errors; do not bypass the controller with direct SQLite writes.
Agent cannot find mnemo	Run mnemo --version in the environment that launches the agent	Put the binary on that environment's PATH or reinstall with MNEMO_INSTALL_DIR.
Duplicate project identities	mnemo projects list --json	Preview mnemo projects merge --auto-by-path --dry-run before approving.
Conflicting memories	mnemo memories review --project=<project>	Review, mark stale or supersede deliberately.
Migration health error	mnemo db migrate --check	Stop the controller before explicit migration or repair; back up the database first.

The controller is managed as com.jmeiracorbal.mnemo.controller (macOS launchd), mnemo-controller.service (Linux systemd user), or MnemoController (Windows Task Scheduler). Its event port is configured in ~/.mnemo/config.toml and binds only to localhost. Repeated setup refreshes should be idempotent. See Installation and Durable Events.