mnemo is designed to be diagnosable without mutating state.
After installing globally, confirm the binary is accessible:
mnemo --version
Run the read-only doctor:
mnemo doctor --agent=all --path=.
mnemo doctor --json --agent=codex --path=.
Check the compact global setup table:
mnemo setup status --agent=all
setup status is read-only:
Detected means the agent’s user-level configuration directory exists.MCP reports whether mnemo’s MCP server is configured.Hooks reports hook/plugin runtime files, or n/a when that agent has no runtime surface to validate.Instructions reports whether global mnemo instructions are installed.Project activation:
cat .mnemo # must contain id + agents list
Global instructions:
grep "mnemo:start" ~/.codex/AGENTS.md ~/.claude/CLAUDE.md 2>/dev/null
head -3 ~/.cursor/rules/mnemo.mdc # should have: alwaysApply: true
grep "mnemo:start" ~/.codeium/windsurf/memories/global_rules.md 2>/dev/null
grep "mnemo:start" ~/.config/opencode/AGENTS.md 2>/dev/null
grep "mnemo:start" ~/.fx/AGENTS.md 2>/dev/null
Global hooks/config:
grep "mnemo" ~/.cursor/hooks.json ~/.codeium/windsurf/hooks.json ~/.codex/hooks.json 2>/dev/null
ls ~/.config/opencode/plugins/mnemo.ts ~/.config/opencode/plugins/mnemo-protocol.md
grep "mnemo" ~/.fx/mcp.json ~/.pi/agent/APPEND_SYSTEM.md ~/.pi/agent/mcp.json 2>/dev/null
Canonical Agent Skill and symlinks:
test -f ~/.agents/skills/mnemo-memory/SKILL.md
ls -l ~/.claude/skills/mnemo-memory \
~/.codeium/windsurf/skills/mnemo-memory \
~/.pi/agent/skills/mnemo-memory
Only symlinks for selected agent-specific consumers are expected to exist. Codex, Cursor, OpenCode and fx use the canonical .agents/skills path directly. Pi uses a symlink under ~/.pi/agent/skills.
claude plugin validate plugin/claude-code
Claude Code can also be configured by install.sh through MCP and global instructions without an installed plugin registry. In that case setup status shows Hooks as n/a and should not warn.
Running setup commands repeatedly must not duplicate managed blocks or marker entries:
mnemo install-instructions --agent=codex
mnemo install-instructions --agent=codex # second run: no duplicate block
mnemo init --agent=claudecode
mnemo init --agent=claudecode # second run: no duplicate agent entry
| Symptom | Check | Fix |
|---|---|---|
| Agent cannot find mnemo MCP | mnemo --version from the same shell/editor environment |
Add ~/.local/bin to PATH or reinstall with MNEMO_INSTALL_DIR. |
| Agent ignores memory | cat .mnemo |
Run mnemo init --agent=<agent> in the project root. |
| Duplicate project identities | mnemo projects list --json |
Run mnemo projects merge --auto-by-path --dry-run and approve only safe merges. |
| Conflicting memories | mnemo memories review --project=<project> |
Mark stale/reviewed, supersede, or consolidate topic keys after review. |
| Setup drift | mnemo setup status --agent=all |
Run mnemo setup refresh --agent=all. |
| Outdated mnemo binary | mnemo update --check |
Run mnemo update and approve the prompt, or mnemo update --yes --agent=all in an already-approved automation. Restart active agent sessions afterwards so they reload refreshed hooks, MCP config and skills. |