Skill v1.0.0
currentAutomated scan100/100version: "1.0.0" name: wax-mcp description: > Operator install and diagnose playbook for waxmcp hosts (HTTP vs stdio, LaunchAgent, Hermes plugin, doctor, vector-health). Use only when installing, repairing, or rewiring a host. Do not use at session start. Do not use when MCP remember/recall/stats are already available — follow the live server instructions instead of loading this skill.
Wax MCP
The MCP server instructions field is the playbook. Do not restate a second lifecycle here. Do not invoke this skill at session start.
Daily tools: remember, recall, stats. Follow the live server instructions instead of restating them here. Aliases stay callable. WAX_MCP_TOOLS=legacy restores the previous eight-tool playbook. WAX_MCP_TOOLS=full lists the rest. WAX_MCP_AUTO_SESSION=0 restores explicit-open.
Recall defaults to the current project after project/repo resolution. Pass scope=global only for cross-project retrieval (person facts, standing preferences). Global searches the entire local store with no current-project rank boost. It is not an authorization boundary.
Pasteable host rules (pointer only): references/project-rules.md.
This is not the Swift framework skill. For embedding Wax in Swift apps, use Resources/skills/public/wax.
Install / Host Setup
Stage binaries once:
npx -y waxmcp@latest install
Then wire the host, not a new prompt:
| Host | What to do | |
|---|---|---|
| Claude Code | swift run --traits MCPServer wax-cli mcp install --scope user then claude install-skill ~/.local/share/waxmcp/skills/wax-mcp | |
| Codex | wax-cli mcp install prints the stdio block (writes it with --write-toml-config) + copies the skill; manual: HTTP URL in ~/.codex/config.toml | |
| Cursor | wax-cli mcp install merges the stdio entry automatically; manual: HTTP URL in ~/.cursor/mcp.json + paste references/project-rules.md | |
| Hermes | Native memory.provider: wax-memory only (npx -y waxmcp@latest install-hermes-plugin). Never plugins.enabled. Never also mcp_servers.wax; do not also register generic MCP or this generic skill. Call wax_remember / wax_recall / wax_stats with no Wax UUID. | |
| OpenClaw | HTTP + memory plugin + paste the SOUL.md stanza into workspace SOUL.md (replace existing ## Memory (Wax)) | |
| Grok CLI | wax-cli mcp install --hosts grok prints the stdio block (writes it with --write-toml-config); daily: HTTP URL http://127.0.0.1:3000/mcp. Do not use GROK_CONFIG / GROK_CONFIG_PATH to retarget Wax. Isolated labs: project .grok/config.toml + --leader-socket (or --no-leader / GROK_HOME) — see Resources/docs/wax-mcp-hosts.md. | |
| OpenCode | wax-cli mcp install --hosts opencode merges the stdio entry automatically (JSONC stays manual); manual: HTTP URL in opencode.json + paste references/project-rules.md | |
| Muse Code | wax-cli mcp install registers Muse automatically (unless --skip-muse); manual: mcp_servers.wax in ~/.config/muse/settings.json (schema_version: 1): stdio wax-cli mcp serve when solo, shared http://127.0.0.1:3000/mcp with two or more clients + paste the AGENTS.md fence from references/project-rules.md | |
| Other | HTTP URL + paste the AGENTS.md fence from references/project-rules.md |
Optional: wax-cli mcp install --write-host-rule PATH writes the generated host-rule blob. It never overwrites a host rule unless that flag is set.
Two or more clients must share one HTTP server on http://127.0.0.1:3000/mcp. Snippets and smoke test: Resources/docs/wax-mcp-hosts.md.
The npm launcher serves MCP. It does not implement mcp install --scope.
Diagnose / recover
npx -y waxmcp@latest doctornpx -y waxmcp@latest vector-health
vector-health is green only when both vectorSearchEnabled and queryEmbeddingAvailable are true. After install, restart HTTP if it is already a service — do not start a second writer:
launchctl kickstart -k "gui/$(id -u)/ai.wax.mcp-http"# or: ~/.local/share/waxmcp/bin/start-wax-mcp-http.sh
Native Hermes, after install-hermes-plugin from this tree:
hermes wax-memory doctorhermes plugins doctor wax-memory
hermes wax-memory registers status, doctor, and config only. If those doctors fail to register or import, reinstall the plugin. Do not add wax-memory to plugins.enabled.
# Claude skill (if wax-cli install did not auto-register)claude install-skill ~/.local/share/waxmcp/skills/wax-mcp# or from sourceclaude install-skill https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax-mcp
References
references/project-rules.md— pasteable project instruction block- Repo setup doc:
Resources/docs/wax-mcp-setup.md