Wax

Chat dies. Wax does not. One local .wax file for Claude, Codex, Hermes, Cursor, and Apple Foundation Models. Searchable memory on disk. No account. No hosted vector DB.

English · Español · Français · 日本語 · 한국어 · Português · 中文

npx -y waxmcp@latest install

That stages the MCP server, MiniLM runtime, and operator skill on Apple Silicon. Wire one host, paste the playbook, and the next session can remember / recall. If this is the memory layer you wanted, star the repo so other agents find it.

---

What Wax is

Wax is a shared memory file for agents and on-device models.

Claude Code ─┐
Codex ───────┤
Cursor ──────┼─ MCP ─→  one HTTP writer  ─→  ~/.wax/memory.wax
Grok ────────┤
OpenClaw ────┘
Hermes ──────── native wax-memory provider ─↗
iPhone / Mac app ── Memory + Foundation Models tools ─↗

The store is one file. Documents, FTS5 text search, CoreML vectors, and a WAL live inside it. iCloud or AirDrop the file to another Mac or iPhone. Identical MCP servers share one broker daemon automatically; a differently-configured second process fails fast with sharing guidance, so two or more hosts share http://127.0.0.1:3000/mcp.

What you get that a host scratchpad does not:

• Claude, Codex, Cursor, and Hermes read and write the same memories.
• remember does not call an LLM to extract facts. You store a sentence; hybrid search finds it later.
• Apple Foundation Models get waxRemember / waxRecall / waxSearch as on-device tools.
• Hermes can drop MEMORY.md curation and use the native wax-memory provider (handoffs, turn sync, wax_remember / wax_recall).

Host playbook: wax-mcp-hosts.md

---

Agent Quick Start

Give Claude Code, Cursor, Codex, Hermes, OpenClaw, Muse Code, or Windsurf a memory that survives the chat.

Installing the server is not enough. Hosts ignore MCP tool descriptions unless an always-on file says when to write. Paste a block below after you wire the host.

1. Stage the server once

npx -y waxmcp@latest install

Claude-only can use stdio. Two or more clients must share one HTTP server on http://127.0.0.1:3000/mcp. A differently-configured second process on ~/.wax/memory.wax fails fast instead of locking silently.

Host wire-up (Claude, Codex, Cursor, Hermes, OpenClaw, Muse)

Host	Wire-up
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: [mcp_servers.wax] url = "http://127.0.0.1:3000/mcp" in ~/.codex/config.toml
Cursor	wax-cli mcp install merges the stdio entry automatically; manual: { "mcpServers": { "wax": { "url": "http://127.0.0.1:3000/mcp" } } } in ~/.cursor/mcp.json + paste the AGENTS.md block
Hermes	Native memory.provider: wax-memory only. npx -y waxmcp@latest install-hermes-plugin, then hermes config set memory.provider wax-memory. Daily tools: wax_remember / wax_recall (no Wax UUID). Do not add wax-memory to plugins.enabled. Do not also register mcp_servers.wax.
OpenClaw	HTTP + memory plugin + paste the SOUL.md stanza into the workspace SOUL.md; replace an existing ## Memory (Wax) section
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 when two or more clients + paste the AGENTS.md block
Anything else	HTTP URL + paste the AGENTS.md block into project AGENTS.md

Keep HTTP up with ~/.local/share/waxmcp/bin/start-wax-mcp-http.sh or LaunchAgent ai.wax.mcp-http. Prove it with npx -y waxmcp@latest vector-health, npx -y waxmcp@latest doctor (wax-cli mcp doctor), hermes wax-memory doctor, and hermes plugins doctor wax-memory. Native recall defaults to the current project; pass scope=global for person facts. Global is not an authorization boundary.

Full snippets, LaunchAgent ai.wax.mcp-http, vector-health, Hermes doctors, and a smoke test: Resources/docs/wax-mcp-hosts.md.

The wax-mcp skill is install/doctor only. The wax skill is Swift SDK integration. Daily memory follows MCP server instructions, not either skill.

2. Teach the model when to use Wax

Pick the file your host actually loads on every turn.

Paste into AGENTS.md / CLAUDE.md / Cursor rules

Use the project or user AGENTS.md, CLAUDE.md, or .cursor/rules. Same text as Resources/skills/public/wax-mcp/references/project-rules.md.

Follow the live Wax MCP server instructions for `remember`, `recall`, and `stats`. Do not invent a `session_id`. Do not load the `wax` or `wax-mcp` skills at session start. `wax` is Swift SDK only; `wax-mcp` is install/doctor only.

Paste into OpenClaw SOUL.md

OpenClaw: the workspace SOUL.md. Native Hermes already owns session lifecycle. Call wax_remember / wax_recall / wax_stats. Do not pass a Wax session_id. Do not paste the MCP session_open loop. Omit mode unless you need an override. Omit scope for current-project recall; pass scope=global for person facts. Empty project recall is a miss. Do not add wax-memory to plugins.enabled.

SOUL.md is identity. Append this section if missing. If ## Memory (Wax) already exists, replace that section. Do not replace the rest of the soul.

## Memory (Wax)

You have Wax. Follow the live MCP server instructions for `remember`, `recall`, and `stats`. Do not invent a `session_id`. Do not load wax-mcp at session start.
``