# Wax: a shared memory file for Claude, Codex, Cursor and Hermes

> Wax puts one searchable .wax file behind every agent you run on Apple Silicon, so a fact written in Claude Code can be recalled in Cursor. It is a local-first memory layer with a real locking constraint and a Swift-only integration path.

**christopherkarani/Wax** — 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

- Repository: https://github.com/christopherkarani/Wax
- Website: https://christopherkarani.github.io/Wax/
- Stars: 802 · Forks: 54
- Language: Swift
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/christopherkarani-wax

## The problem Wax solves: agents that forget each other

Every MCP host keeps its own scratchpad. Claude Code learns a preference on Monday, Cursor has no idea on Tuesday, and Codex starts from zero on Wednesday. The usual fix is a hosted vector database behind an API key, which means an account, a network round trip, and a copy of your notes on someone else's disk.

Wax takes the opposite position. The store is a single file at ~/.wax/memory.wax. The README describes it as containing documents, FTS5 text search, CoreML vectors, and a write-ahead log in the same file. That means you can iCloud or AirDrop the file to another Mac or an iPhone and keep the memory. There is no account and no hosted vector DB.

The audience is narrow and specific: developers on Apple Silicon who already run several MCP-capable agents and want them to share what they learn. The README names Claude Code, Codex, Cursor, Grok, OpenClaw, Hermes, and Apple Foundation Models as hosts. If you run one agent on one machine, you are paying the setup cost of a shared layer for a problem you do not have.

## One HTTP writer, many readers, one file

The architecture in the README is a fan-in. Claude Code, Codex, Cursor, Grok, and OpenClaw connect over MCP to one HTTP writer listening on http://127.0.0.1:3000/mcp. Hermes and iPhone or Mac apps reach the same store through a native wax-memory provider rather than through the MCP server.

The constraint that shapes everything else: a second MCP process on ~/.wax/memory.wax will lock. So the design assumes exactly one writer per file, and the HTTP server is how multiple hosts share it. Claude-only setups can use stdio instead, which is simpler but gives up sharing.

The write path is deliberately dumb. According to the README, remember does not call an LLM to extract facts: you store a sentence and hybrid search finds it later. That removes the extraction step, the prompt, and the failure mode where a model decides your note was not worth keeping. It also means recall quality depends on how you phrase the sentence, not on a summarizer's judgement.

What the README does not document is rollback, conflict resolution between two writes to the same logical fact, or what happens when the WAL is interrupted mid-write. Those are open questions for anyone treating the file as a system of record.

## Installing Wax and making a first recall

The staging command is a single npx invocation. It places the MCP server, the MiniLM runtime, and the operator skill on the machine. The README notes this targets Apple Silicon.

```bash
npx -y waxmcp@latest install
```

After that, wire one host. For Cursor the README gives a JSON block pointing at the HTTP endpoint:

```json
{ "mcpServers": { "wax": { "url": "http://127.0.0.1:3000/mcp" } } }
```

For Codex the equivalent lives in TOML at ~/.codex/config.toml:

```toml
[mcp_servers.wax]
url = "http://127.0.0.1:3000/mcp"
```

The README is explicit that installing the server is not enough. Hosts ignore MCP tool descriptions unless an always-on file tells them when to write, so you paste a rules block into AGENTS.md, CLAUDE.md, or .cursor/rules. That block defines four categories: user_preference, lesson, fact, and decision or constraint, and tells the model to skip only empty chit-chat.

Keep the HTTP server running with ~/.local/share/waxmcp/bin/start-wax-mcp-http.sh or the LaunchAgent ai.wax.mcp-http. Then verify before trusting it:

```bash
npx -y waxmcp@latest doctor
npx -y waxmcp@latest vector-health
```

The doctor command checks the wiring, and vector-health checks the embedding path. If vector-health fails, recall will fall back to text matching alone, which is a different product experience than the one advertised.

## The single-writer lock is the real limitation

The lock is not a footnote, it is the operating model. Two MCP processes on the same path will conflict, so every additional host has to be routed through the shared HTTP server rather than pointed at the file directly. That is fine on one machine. It is not fine for a team, a CI runner, or a laptop plus a desktop that both expect to write.

The README states plainly that global scope is not an authorization boundary. Native recall defaults to the current project, and scope=global is for person facts. If you were hoping to use Wax to separate what one agent may see from what another may see, that is not what this provides. It is a shared memory, not a permissions layer.

Platform is the second boundary. The badges list macOS, iOS, and Linux, but the install path stages a MiniLM runtime and the project description says Apple Silicon, with CoreML and Metal among the topics. The README does not document a CUDA or x86 path. If your agents run in a Linux container on AMD hardware, this is the wrong tool, and the documentation does not offer a fallback.

The third cost is the always-on process. If the HTTP server is not running, hosts that point at the URL have nothing to talk to. A stdio setup avoids that for a single Claude user, at the price of sharing.

## Wax versus a hosted vector database

A hosted vector database such as Pinecone or Weaviate puts the index behind an HTTP API, handles concurrent writers, and scales past one machine. You pay for that with an account, a network dependency, and embeddings that leave your machine. Wax inverts every one of those: the index is a file, concurrency is solved by having one writer, and the embeddings run locally through CoreML.

The practical difference shows up in the failure modes. A hosted service degrades when the network does. Wax degrades when the local process is not running, or when a second process grabs the lock. A hosted service gives you multi-tenant isolation. Wax gives you one file per user, and the README says global scope is not an authorization boundary.

There is also a middle option worth naming: an agent host's own memory feature. Claude Code and Cursor both keep some project context. Those stores are per-host, which is exactly the problem Wax exists to solve, but they require no second process and no MCP wiring. If you only ever use one host, the built-in memory is the cheaper answer.

The comparison that matters is not features, it is whether your agents live on one Apple Silicon machine. If they do, a file beats a service. If they do not, the file is a liability.

## Maintenance, licence, and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-09. The release list shows waxmcp 0.1.41 on 2026-09-09, 0.1.40 on 2026-09-08, and 0.1.39 on 2026-09-03, so the npm package is moving in small increments rather than large ones. That cadence is a signal about the shape of the project: frequent patch releases on a 0.1.x line, not a stabilised API.

Upgrade cost is mostly the npx path. Because the install command pins @latest, re-running it pulls the newest waxmcp, and the README's own instructions assume you will do that. The risk sits in the runtime that install stages: MiniLM and the CoreML vector path are shipped alongside the package, so a version bump can change the embedding model behind an existing .wax file. The README does not document a re-embedding or migration step, and it does not document rollback. Treat that as the thing to check before upgrading a file you care about.

Licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. It also requires that you keep the licence and notice files and state significant changes. Nothing in the README suggests a separate commercial tier or a hosted component with different terms. This is a description of the licence text, not legal advice; if you are shipping Wax inside a product, have counsel read the NOTICE obligations.

## Conclusion

Adopt Wax if you run two or more MCP hosts on one Mac and want their memories in a single file you can copy or AirDrop. Do not adopt it if you need a cross-platform server, a multi-writer database, or a memory layer that works without an always-on HTTP process. Before wiring anything, run npx -y waxmcp@latest doctor and npx -y waxmcp@latest vector-health, and confirm that only one process will ever open ~/.wax/memory.wax.

## FAQ

### How do I install Wax and connect it to Claude Code?

Run npx -y waxmcp@latest install to stage the MCP server, the MiniLM runtime, and the operator skill. Claude-only setups can use stdio, which the README gives as swift run --traits MCPServer wax-cli mcp install --scope user followed by claude install-skill ~/.local/share/waxmcp/skills/wax-mcp. Installing the server is not enough on its own; you also paste the rules block into CLAUDE.md so the host knows when to write.

### Why will a second Wax process on the same file lock?

Wax is designed around a single writer per store. The README states that a second MCP process on ~/.wax/memory.wax will lock, so two or more hosts must share the HTTP server at http://127.0.0.1:3000/mcp instead of opening the file themselves. That is why the multi-host setup routes everything through one process.

### Does Wax require an API key or a hosted vector database?

No. The README describes Wax as one local .wax file with no account and no hosted vector DB, and remember does not call an LLM to extract facts. You store a sentence and hybrid search finds it later. The trade-off is that the embedding runtime is staged locally, which the install command handles.

### Can I move a Wax memory between machines?

The README says you can iCloud or AirDrop the file to another Mac or an iPhone, because documents, FTS5 text search, CoreML vectors, and the WAL all live inside the single .wax file. What the README does not document is what happens on a version upgrade that changes the embedding model, or how to roll back.

## Sources

- [christopherkarani/Wax on GitHub](https://github.com/christopherkarani/Wax)
- [License: Apache-2.0](https://github.com/christopherkarani/Wax/blob/main/LICENSE)
- [Project website](https://christopherkarani.github.io/Wax/)
- [README](https://github.com/christopherkarani/Wax/blob/main/README.md)
- [Releases](https://github.com/christopherkarani/Wax/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/christopherkarani-wax