christopherkarani Wax MCP
The MCP server instructions field is the playbook. Do not restate a second
lifecycle here.
Daily tools: remember, recall, stats. The server auto-opens one
transport-scoped session. 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.
Do not call memory_promote or memory-maintain in the agent loop. Never
invent a session_id or put it in metadata. Do not close on Stop, idle,
or compaction.
Recall defaults to the current project after project/repo resolution. Empty
project recall is a miss, not “I have no memory.” Supplying both project
and repo requires both exact tags. Pass scope=global only for
cross-project retrieval (person facts, standing preferences). For person
facts pass memory_types: ["user_preference"] so project lessons do not
crowd the lane. Global searches the entire local store with no
current-project rank boost. It is not an authorization boundary.
recall is self-contained. Do not close between turns or after compaction.
Pasteable host rules: 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 | HTTP URL in ~/.codex/config.toml + copy this skill to ~/.codex/skills/wax-mcp |
| Cursor | 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 | 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. |
| 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 doctor
npx -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 doctor
hermes 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 source
claude 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