mnemo uses a CodeGraph-style split:
mnemo binary and global agent setup once.mnemo init only in projects that should use mnemo.Global hooks are intentionally inert outside projects with a valid .mnemo marker.
The mnemo binary must be in your PATH before any agent integration will work. This applies to Claude Code, Cursor, Windsurf, Codex, OpenCode, fx and Pi regardless of how the integration is installed.
The hooks that fire on session start, session end and passive capture call mnemo directly. The MCP server is also the mnemo binary. Without it in PATH, hooks and MCP cannot start.
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash
The installer defaults to --agent=auto: it detects compatible agents from known binaries/directories and falls back to Claude Code when nothing is detected.
Explicit targets are supported:
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=codex
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=opencode
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=fx
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=pi
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash -s -- --agent=all
Environment overrides:
MNEMO_AGENT=cursor bash install.sh
MNEMO_VERSION=v0.35.0 bash install.sh
MNEMO_DRY_RUN=true bash install.sh
MNEMO_INSTALL_DIR="$HOME/.local/bin" bash install.sh
Released binaries check GitHub Releases during interactive CLI use. If a newer release exists, mnemo itself shows the installed/latest versions and asks before installing.
You can also run the update flow explicitly:
mnemo update
mnemo update --yes --agent=all
mnemo update --check --json
mnemo update downloads the official installer, sets MNEMO_VERSION to the
latest detected release, installs the matching binary and refreshes mnemo’s
agent integration files. --agent=all refreshes every supported integration;
--agent=auto refreshes integrations detected in the current system;
--agent=<name> limits the refresh to one integration. This does not update the
agent applications themselves. Restart active agent sessions after updating so
they reload refreshed hooks, MCP config and skills.
This is separate from agent skill guidance: the skill only tells agents how to respond to update notices; it is not the update mechanism.
Claude Code users may install through the plugin marketplace:
claude plugin marketplace add jmeiracorbal/mnemo
claude plugin install mnemo@mnemo
The plugin still requires the mnemo binary in PATH. Restart Claude Code after installing, then run:
mnemo init --agent=claudecode
Update the plugin with:
claude plugin update mnemo@mnemo
If that reports up to date while the binary is newer, reinstall to clear marketplace cache:
claude plugin uninstall mnemo
claude plugin install mnemo@mnemo
install.sh configures Claude Code through MCP and global instructions. Claude plugin hooks are optional in that path, so a fresh install without a plugin registry is valid.
Pi support installs global guidance into ~/.pi/agent/APPEND_SYSTEM.md so mnemo extends Pi’s default prompt instead of replacing it with .pi/SYSTEM.md. It also writes a standard mcpServers entry to ~/.pi/agent/mcp.json for Pi environments that have an MCP extension such as pi-mcp-adapter, pi-mcp-extension, or pi-mcp installed.
Pi does not expose a stable declarative hook surface for mnemo, so setup does not install hooks for Pi.
git clone https://github.com/jmeiracorbal/mnemo
cd mnemo
go build -o ~/.local/bin/mnemo ./cmd/mnemo/
export PATH="$HOME/.local/bin:$PATH"
mnemo --version
From the project root:
mnemo init --agent=claudecode # or cursor, windsurf, codex, opencode, fx, pi, all
# optional: --no-project-rules for .mnemo marker only
This creates a .mnemo marker and records the selected agent. Agent hooks, MCP configuration and global protocol live globally after installation; they activate only when a project has a valid .mnemo file.
install.sh and mnemo setup refresh embed the mnemo-memory skill at ~/.agents/skills/mnemo-memory/. Claude Code, Windsurf and Pi receive agent-specific symlinks to that canonical folder. Codex, Cursor, OpenCode and fx use the canonical ~/.agents/skills/ path directly according to their current skill discovery docs. You normally do not need a separate skill install step.
If you prefer the skills CLI or need to refresh manually:
npx skills add jmeiracorbal/mnemo --skill mnemo-memory --global
Optional project maintenance skill:
npx skills add jmeiracorbal/mnemo --skill mnemo-project-maintenance --global
This installs only the skill and agent links. It does not install the mnemo binary, hooks, MCP configuration or Claude Code plugin. Install mnemo first and ensure mnemo is available in PATH.
Optional memory curation skill:
npx skills add jmeiracorbal/mnemo --skill mnemo-memory-curation --global
Use it when an agent should notice likely memory conflicts during normal work, warn the user and apply only explicitly approved repairs through mnemo commands.
mnemo setup status --agent=all
mnemo setup print-config codex
mnemo setup refresh --agent=codex
mnemo setup uninstall --agent=codex
mnemo setup <agent> is an alias for mnemo setup refresh --agent=<agent>.