Wax: one .wax file as shared memory for Claude, Codex, Cursor and Hermes
Shared Single-file memory layer for all your agents, sub mili-second RAG over text, photo and video on Apple Silicon.. No Server. No API. One File. Pure Swift
At a glance
- What is it?
- Wax is a Swift memory layer that puts documents, FTS5 text search, CoreML vectors and a WAL inside a single local file, exposed to agents over MCP or a native Hermes provider. The design is coherent and the single-writer constraint is the part most teams will trip over.
- Who is it for?
- Adopt Wax if you run several MCP-capable coding hosts on one Apple Silicon machine and want them reading the same memories without a hosted vector database, and if you accept that one process owns ~/.wax/memory.wax at a time. Do not adopt it if your agents run on separate machines that cannot share a filesystem, or if you need per-user authorization on memory reads, since the README states that global scope is not an authorization boundary.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Wax targets: memory that dies with the chat session
Each coding agent keeps its own context. Claude Code, Codex, Cursor, Hermes and OpenClaw do not read one another's transcripts, so a correction you make in one host has to be repeated in the next. The README states the case bluntly: chat dies, Wax does not. The intended audience is someone running more than one MCP-capable host on a single Apple Silicon machine who wants a shared, searchable record on disk instead of a hosted vector database behind an account and an API key. The unit of storage is a .wax file, by default at ~/.wax/memory.wax. The README describes that file as containing documents, FTS5 text search, CoreML vectors and a write-ahead log, and notes that you can copy it to another Mac or iPhone with iCloud or AirDrop. That portability is the concrete difference from a managed vector store: the memory is a file you can move, back up or delete, not a remote index tied to a project ID.
How the pieces fit: MCP hosts, one HTTP writer, one file
The architecture in the README is a fan-in. Claude Code, Codex, Cursor, Grok and OpenClaw connect over MCP; Hermes connects through a native wax-memory provider; iPhone and Mac apps reach the same store through Memory and Foundation Models tools. All of those paths converge on one writer that owns ~/.wax/memory.wax. The README is explicit that a second MCP process on the same path will lock, which is why two or more clients are told to share a single HTTP server at http://127.0.0.1:3000/mcp. That is the whole design constraint in one sentence: concurrency is handled by serializing writes through one process, not by a multi-writer storage engine. On the write path, the README says remember does not call an LLM to extract facts. You store a sentence and hybrid search finds it later. That choice keeps writes cheap and deterministic, and it pushes the burden onto the caller to write something worth retrieving. Retrieval combines FTS5 text search with CoreML vectors, which is why the README points at vector-health as a separate diagnostic from doctor.
Getting it running: install, host config, and the skill files
The staged install is one command: npx -y waxmcp@latest install. According to the README, that places the MCP server, the MiniLM runtime and an operator skill on Apple Silicon. Wiring then differs per host. Claude Code uses swift run --traits MCPServer wax-cli mcp install --scope user followed by claude install-skill ~/.local/share/waxmcp/skills/wax-mcp. Codex takes an [mcp_servers.wax] block with url = "http://127.0.0.1:3000/mcp" in ~/.codex/config.toml plus a skill copied to ~/.codex/skills/wax-mcp. Cursor takes a JSON mcpServers entry pointing at the same URL in ~/.cursor/mcp.json. Hermes is the odd one out: it is native provider only, installed with npx -y waxmcp@latest install-hermes-plugin and switched on with hermes config set memory.provider wax-memory. The README warns twice about Hermes configuration: do not add wax-memory to plugins.enabled, and do not also register mcp_servers.wax. Keeping the HTTP endpoint alive is handled by ~/.local/share/waxmcp/bin/start-wax-mcp-http.sh or the LaunchAgent ai.wax.mcp-http. Verification commands named in the README are npx -y waxmcp@latest vector-health, npx -y waxmcp@latest doctor, hermes wax-memory doctor and hermes plugins doctor wax-memory. One caveat the README raises directly: installing the server is not enough, because hosts ignore MCP tool descriptions unless an always-on file states when to write. That is what the AGENTS.md, CLAUDE.md or .cursor/rules block is for.
The single-writer lock is a design boundary, not a bug to route around
The most consequential constraint in the material is the locking behaviour. The README states that a second MCP process on ~/.wax/memory.wax will lock, and it repeats the point in the quick start. For a solo developer on one Mac this is invisible, because one HTTP server serves every host. For a team it is a real boundary. Two laptops cannot point at the same file over a network share and expect both writers to work, and the README's portability story is about copying the file, not about concurrent access from multiple machines. There is a second limitation stated just as plainly: native recall defaults to the current project, and passing scope=global retrieves person facts, but the README says global is not an authorization boundary. In practice that means the store has no per-user read isolation. If several people share a machine and a .wax file, any connected host can recall what any other host wrote. Treat scope as a retrieval hint, not a permission system, and do not put anything in the file that you would not want every connected agent to surface.
Where Wax is the wrong tool
Wax assumes Apple Silicon and local execution. The install stages a MiniLM runtime and CoreML vectors, and the README's platform badges list macOS, iOS and Linux, but the vector path it describes is CoreML. If your agents run in containers on Linux CI with no Metal or CoreML available, the vector half of hybrid search is not the part you are getting, and the README does not describe a fallback embedding backend. The second case is multi-tenant or server-side use. A hosted vector database with per-tenant namespaces and an auth layer is the right shape when many users' memories must stay separated and audited; a single local file with a documented note that global scope is not an authorization boundary is the wrong shape for that. The third case is a single-host, single-agent setup where the host's own scratchpad is already sufficient. The README itself says the value is that Claude, Codex, Cursor and Hermes read and write the same memories. With one host there is no sharing to do, and you have added an HTTP server, a LaunchAgent and a skill file to maintain for no cross-host benefit.
Compared with a hosted vector database plus an MCP wrapper
The obvious alternative is a hosted vector store (or a local server such as a general-purpose vector database) with a thin MCP server in front of it. The difference is not speed, it is where the index lives and who owns the write path. A hosted store gives you concurrent writers from many machines, per-tenant isolation and a query API you can call from anywhere, at the cost of an account, an API key, network round trips and a service that can be unavailable. Wax inverts all of that: no server to operate beyond a localhost process, no API key, and the index is a file you can AirDrop. What you give up is multi-writer concurrency and any notion of per-user access control. A second alternative the README itself points at is the host's own MEMORY.md curation, which Hermes can drop in favour of the native wax-memory provider. That is a fair comparison to make: MEMORY.md is a text file an agent edits, with no FTS5 index and no vector search, so recall depends on the agent reading the whole file. Wax trades that simplicity for an indexed store you query with wax_remember and wax_recall on Hermes, or remember and recall over MCP.
Maintenance cost, release cadence and licence
The release list shows waxmcp 0.1.41, 0.1.40 and 0.1.39, with the two most recent published one day apart in September 2026. A patch cadence that tight on a 0.1.x line means you should pin the version you install rather than tracking @latest in a script that runs unattended, and re-run the doctor commands after any bump. There are two skills with different audiences, and the README distinguishes them explicitly: wax-mcp is the operator playbook, wax is Swift framework integration. If you are wiring hosts, you want the first. The repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirements around notice and attribution; that is a description of the licence text, not legal advice, and if you redistribute a modified build you should read the LICENSE file yourself. Nothing in the supplied material describes a paid tier, a hosted control plane or a telemetry endpoint, so the operational surface appears to be the local HTTP process and the file itself. The maintenance question that matters is not the licence but the lock: every host you add is another client that must be pointed at the shared HTTP endpoint rather than at the file.
Editorial conclusion
Adopt Wax if you run several MCP-capable coding hosts on one Apple Silicon machine and want them reading the same memories without a hosted vector database, and if you accept that one process owns ~/.wax/memory.wax at a time. Do not adopt it if your agents run on separate machines that cannot share a filesystem, or if you need per-user authorization on memory reads, since the README states that global scope is not an authorization boundary. Before wiring anything, run npx -y waxmcp@latest doctor and npx -y waxmcp@latest vector-health against a scratch .wax file, then confirm that your second host connects to http://127.0.0.1:3000/mcp rather than opening the file itself.
Community notes