GitHub - christopherkarani/Wax: Single-file memory layer for AI agents, sub mili-second RAG on Apple Silicon. Metal Optimized On-Device. No Server. No API. One File. Pure Swift

Give your AI agent a memory that never forgets.
One file. Zero cloud. Blazing fast recall on Apple Silicon.

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

What is Wax?

Wax is a Swift-native memory engine for AI agents. It stores documents, embeddings, and structured knowledge in a single .wax file that lives entirely on your device.

No servers. No API keys. No Docker. Just one file you can AirDrop, sync, or back up like any other document.

import Wax

let memory = try await Memory(at: url)
try await memory.save("The user prefers dark mode and uses Vim keybindings.")
let results = try await memory.search("What editor does the user like?")
// → "The user prefers dark mode and uses Vim keybindings."

What you can build

Persistent chatbots — Your assistant remembers every conversation, preference, and decision across sessions.
Coding agents with long-term memory — Claude Code or Cursor that recalls your codebase patterns, architectural decisions, and TODOs from last week.
Personal knowledge bases — Semantic search over your notes, documents, and web clips. Ask "What did I read about HNSW?" and get the exact paragraph.
On-device RAG — Ship AI features in your iOS or macOS app without calling the cloud.

Choose Your Path

Wax meets you where you are. Pick the path that matches what you're building:

🛠️ Swift Developer	⌨️ CLI Power User	🤖 AI Agent Setup
You want: Embed memory in your iOS/macOS app or Swift tool.	You want: A command-line memory store you can script against.	You want: Your AI assistant (Claude Code, Cursor, etc.) to remember context across sessions.
Get started: Swift Quick Start ↓	Get started: CLI Quick Start ↓	Get started: Agent Quick Start ↓

Swift Quick Start

1. Add Wax to your project

Swift Package Manager

// Package.swift
dependencies: [
    .package(url: "https://github.com/christopherkarani/Wax.git", from: "0.1.8")
]

Or in Xcode: File → Add Package Dependencies → https://github.com/christopherkarani/Wax.git

Note

Requirements: Wax builds for iOS 17/macOS 14 and later. Built-in semantic embeddings (MiniLM) auto-configure on iOS 18/macOS 15+ when the default MiniLMEmbeddings package trait is enabled; on older OS versions, Memory runs text-only unless you pass a custom EmbeddingProvider. Foundation Models tools require iOS 26/macOS 26.

2. Copy-paste this into your app

import Foundation
import Wax

let url = URL.documentsDirectory.appending(path: "agent.wax")

// Open a memory store
let memory = try await Memory(at: url)

// Save something
try await memory.save("The user is building a habit tracker in SwiftUI.")

// Recall it later — works even if the app was killed
let results = try await memory.search("What is the user building?")
if let best = results.items.first {
    print("Found: \(best.text)")
    // → "Found: The user is building a habit tracker in SwiftUI."
}

try await memory.close()

SwiftUI example

import SwiftUI
import Wax

struct ContentView: View {
    @State private var result = "Searching…"

    var body: some View {
        Text(result)
            .task {
                do {
                    let url = URL.documentsDirectory.appending(path: "agent.wax")
                    let memory = try await Memory(at: url)

                    try await memory.save("The user is building a habit tracker in SwiftUI.")
                    let context = try await memory.search("What is the user building?")

                    result = context.items.first?.text ?? "Nothing found"
                    try await memory.close()
                } catch {
                    result = "Error: \(error.localizedDescription)"
                }
            }
    }
}

CLI tool (main.swift)

import Foundation
import Wax

@main
struct AgentMemory {
    static func main() async throws {
        let url = URL.documentsDirectory.appending(path: "agent.wax")
        let memory = try await Memory(at: url)

        try await memory.save("The user is building a habit tracker in SwiftUI.")

        let results = try await memory.search("What is the user building?")
        if let best = results.items.first {
            print("Found: \(best.text)")
        }

        try await memory.close()
    }
}

Prefer a checked-in harness over pasting snippets? Run the demo — Resources/WaxDemo exercises the public Memory APIs on macOS 26.

Looking to store persistent facts and long-term reasoning? Structured memory (entities and facts) is available today through the MCP server tools (entity_upsert, fact_assert, facts_query, …) described in the Agent Quick Start. The Swift-level structured memory API is package-internal for now; see Structured Memory (contributor documentation).

Run the demo

Resources/WaxDemo is a small Swift package that stress-tests the public Wax APIs (save/search durability, embeddings, Foundation Models, error paths).

Requires macOS 26 (the demo package declares that platform; Foundation Models mode needs Apple Intelligence where available).

cd Resources/WaxDemo
swift run WaxDemo --mode all

Useful modes:

Mode	What it runs
`memory`	Save → search → close → reopen → search
`framestore`	Low-level frame create/put/read/delete
`embeddings`	Built-in MiniLM + hybrid/vector search
`fm`	Foundation Models memory session (or a clear unavailable message)
`errors`	Validation / `WaxError` paths
`all`	Everything above (default)

swift run WaxDemo --mode memory
swift run WaxDemo --mode fm --keep --store /tmp/wax-demo.wax

--keep leaves the .wax file on disk; --store PATH picks the file location.

Source: Resources/WaxDemo.

CLI Quick Start

1. Install

# Build from source (requires Swift 6+)
git clone https://github.com/christopherkarani/Wax.git
cd Wax
swift build -c release

# The binary is now at .build/release/wax-cli
cp .build/release/wax-cli /usr/local/bin/

2. Remember and recall from the terminal

# Save a memory
wax-cli remember "An automobile needs periodic maintenance."

# Search it back
wax-cli search "car service" --mode hybrid --topK 3

# Simple text-only search (no setup required)
wax-cli search "car service" --mode text

# Linux / cloud TUI demo + public-API stress (text-only; no MiniLM claim)
wax-cli demo --run
wax-cli demo --stress --run

The dashboard tracks retrieval time live (last / p50 / p95 / n) on every successful Memory.search.

On Linux, build wax-cli without -DGRDBCUSTOMSQLITE (that flag breaks GRDB's system SQLite overlay):

swift build --product wax-cli --traits default,MCPServer
BIN="$(swift build --product wax-cli --show-bin-path --traits default,MCPServer)/wax-cli"
"$BIN" demo --run
"$BIN" demo --stress --run
# Hold each TUI frame for a recording or live walkthrough
"$BIN" demo --run --pace-ms 1500 --hold-ms 4000

For long-running sessions, start the daemon:

wax-cli daemon --store-path ~/.wax/memory.wax

Then send JSON-line commands:

{"id":"1","command":"remember","content":"An automobile needs periodic maintenance."}
{"id":"2","command":"search","query":"car service","mode":"hybrid","topK":3}
{"id":"3","command":"shutdown"}

Note

Vector search requires the embedder. If it's unavailable, hybrid/vector commands fail loudly instead of silently falling back to text-only mode.

Agent Quick Start

Give your AI coding assistant (Claude Code, Cursor, Windsurf) a persistent memory that survives across sessions.

1. Install the MCP server (and stage the operator skill)

npx -y waxmcp@latest mcp install --scope user

This stages the Wax runtime locally, registers wax-mcp with Claude Code, and stages the wax-mcp operator skill under ~/.local/share/waxmcp/skills/wax-mcp (then attempts claude install-skill when available). npx is only used for the one-time install.

The MCP server also ships lifecycle instructions with every tools connection, so agents receive the remember/recall/handoff playbook even without a separate skill install.

2. Install the wax-mcp skill (if install did not auto-register it)

# Preferred: staged local copy after mcp install
claude install-skill ~/.local/share/waxmcp/skills/wax-mcp

# Or from GitHub
claude install-skill https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax-mcp

This is the agent operator skill (session lifecycle, remember/recall, handoffs).

Writing Swift apps with the Wax framework? That is a different skill: claude install-skill https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax

3. Or paste project rules into CLAUDE.md / AGENTS.md

Wax MCP project rules (click to expand, then copy)

Use the Wax MCP server for persistent memory in this repo.

Workflow rules:
- At session start, call `handoff_latest` first to load prior context, then call `session_start` once and keep the returned `session_id`.
- Use `remember` to store decisions, discoveries, and short factual notes. If the memory is session-scoped, pass `session_id` as a top-level argument. Do not put `session_id` inside `metadata`.
- Use `recall` for assembled context and `search` for raw ranked hits.
- Prefer `mode: "hybrid"` when semantic retrieval helps. Use `mode: "text"` when I want a fast or deterministic lexical lookup.
- Do not manage `SESSION_STORE`, `--store-path`, or `flush` in normal agent flows. The broker owns long-term memory and virtual session stores.
- Use `handoff` near the end of the session with `content`, optional `project`, and `pending_tasks`, then call `session_end`.
- Use `corpus_search` only when you need cross-session retrieval across broker-managed session history with provenance metadata.
- Use structured memory tools (`entity_upsert`, `fact_assert`, `fact_retract`, `facts_query`, `entity_resolve`) for stable entities and facts, not transient debugging notes.

Behavior expectations:
- Read existing handoffs and recall results before asking me to restate prior context.
- Keep memory writes concise, factual, and scoped to the task.
- When a cross-session result looks relevant, cite the provenance metadata so we know which session store it came from.

For the full Claude Code setup flow, see Resources/docs/wax-mcp-setup.md.

Why Wax?

Feature	Wax	SQLite (FTS5)	Cloud Vector DBs
Search	Hybrid (Text + Vector)	Text Only*	Vector Only*
Latency	~6ms (p95)	~10ms (p95)	150ms - 500ms+
Privacy	100% Local	100% Local	Cloud-hosted
Setup	Zero Config¹	Low	Complex (API Keys)
Architecture	Apple Silicon Native	Generic	Varies

¹ Text search works out of the box everywhere. Semantic (vector) search auto-configures the on-device MiniLM embedder on iOS 18/macOS 15+; on older OS versions, pass a custom EmbeddingProvider or search text-only. results.diagnostics and memory.stats() always report which retrieval mode actually ran — Wax never silently pretends a text-only result is semantic.

Why a single `.wax` file?

Most RAG setups end up with a database, a vector store, and a file server. Wax keeps the moving pieces smaller by bundling documents, metadata, and indexes into one binary.

Less setup — no Docker stack and no separate database to babysit.
Portable — move the file with AirDrop, iCloud, or whatever sync layer you already use.
Atomic — backup, copy, or delete one file instead of chasing state across services.

Performance

Wax is tuned for M-series hardware and local recall.

Recall Latency (p95)

Lower is better. Measured in milliseconds.

Wax (Hybrid)  |██ 6.1ms
SQLite (Text) |████ 12ms
Cloud RAG     |██████████████████████████████████████████████████ 150ms+

Cold Open Time (p95)

Lower is better. Measured in milliseconds.

Wax           |███ 9.2ms
Traditional   |██████████████████████████████████████ 120ms+

Cold open measures store open only. The built-in embedder's first-ever CoreML compile is a separate one-time cost; later launches reuse the cached compiled model.

Tip

Ingest Throughput: Wax handles 85.9 docs/s with full hybrid indexing on an M3 Max. Full benchmark report: Resources/docs/benchmarks/2026-03-06-performance-results.md

Architecture

How Wax works under the hood (click to expand)

Wax uses a frame-based container format and embeds the search engines it needs inside the main file: SQLite FTS5 for text and a Metal-accelerated HNSW index for vectors. The Metal HNSW engine activates automatically once an index holds 10,000+ vectors; smaller indexes use an exact Accelerate/CPU flat index with identical recall.

Internal File Layout

┌──────────────────────────────────────────────────────────────────────────┐
│                          Dual Header Pages (A/B)                         │
│   (Magic, Version, Generation, Pointers to WAL & TOC, Checksums)         │
├──────────────────────────────────────────────────────────────────────────┤
│                          WAL (Write-Ahead Log)                           │
│   (Atomic ring buffer for crash-resilient uncommitted mutations)         │
├──────────────────────────────────────────────────────────────────────────┤
│                          Compressed Data Frames                          │
│   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐       │
│   │ Frame 0 (LZ4)    │  │ Frame 1 (LZ4)    │  │ Frame 2 (LZ4)    │ ...   │
│   │ [Raw Document]   │  │ [Metadata/JSON]  │  │ [System Info]    │       │
│   └──────────────────┘  └──────────────────┘  └──────────────────┘       │
├──────────────────────────────────────────────────────────────────────────┤
│                          Hybrid Search Indices                           │
│   ┌──────────────────────────────┐  ┌──────────────────────────────┐     │
│   │ SQLite FTS5 Blob             │  │ Metal HNSW Index             │     │
│   │ (Text Search + EAV Facts)    │  │ (Vector Search)              │     │
│   └──────────────────────────────┘  └──────────────────────────────┘     │
├──────────────────────────────────────────────────────────────────────────┤
│                          TOC (Table of Contents)                         │
│   (Index of all frames, parent-child relations, and engine manifests)    │
└──────────────────────────────────────────────────────────────────────────┘

Atomic resilience: dual headers and the WAL keep the store consistent even if the process dies mid-write.
Unified retrieval: one query fans out to both the BM25 text index and the HNSW vector index.
Structured knowledge: built-in EAV (Entity-Attribute-Value) storage handles durable facts and long-term reasoning. (Exposed today via the MCP server tools; the Swift-level API is package-internal.)

Ecosystem Tools

🤖 MCP Server

Wax provides a first-class Model Context Protocol (MCP) server. Connect your local memory to Claude Code or any MCP-compatible agent.

npx -y waxmcp@latest mcp install --scope user

For the recommended Claude Code prompt and setup flow, see Resources/docs/wax-mcp-setup.md. For the OpenClaw adapter verification pass used in this repo, run scripts/verify-openclaw-adapter.sh. For the native-memory operator guide, verifier, and benchmark sweep, see docs/openclaw-native-memory.md.

The MCP surface now supports managed Markdown round-trips with markdown_export / markdown_sync, including MEMORY.md, daily notes, and DREAMS.md promotion review. markdown_sync also supports dry_run, and OpenClaw-oriented promotion thresholds can be overridden on session_synthesize / memory_promote or via environment variables.

For remote or team-hosted deployments, wax-mcp also supports HTTP transport:

./.build/debug/wax-mcp --no-embedder --transport http --http-host 127.0.0.1 --http-port 3000

🔍 WaxRepo

A semantic search TUI for your git history. Index any repository and find code or commits using natural language.

# From within any git repo
wax-repo index
wax-repo search "where did we implement the WAL?"

FAQ

Q: Do I need an internet connection?
A: No. Wax is 100% on-device. No cloud APIs, no network calls.

Q: How big does the .wax file get?
A: It depends on your data, but the file stays compact thanks to LZ4 compression. Typical usage: a few MB for thousands of documents.

Q: Can I sync the .wax file across devices?
A: Yes. It's a single file. iCloud Drive, Dropbox, AirDrop — whatever you already use.

Q: What happens if the app crashes during a write?
A: Wax uses a write-ahead log (WAL) and dual headers. The store recovers automatically on the next open.

Q: Does Wax work on Intel Macs?
A: Wax is optimized for Apple Silicon (M-series). It may run on Intel via Rosetta but vector acceleration requires Metal performance shaders best supported on Apple Silicon.

Q: I get "embedder unavailable" when using hybrid search.
A: Hybrid and vector search require a local embedding model. In Swift, Memory(at:) auto-configures the built-in MiniLM embedder on iOS 18/macOS 15+ (default MiniLMEmbeddings trait), or you can select any custom EmbeddingProvider via Memory.Config.embedding = .custom(...). On older OS versions, use text-only search or provide a custom embedder. The CLI/MCP server fail loudly when the embedder is unavailable; the Swift SDK reports the effective retrieval mode via results.diagnostics and memory.stats().

Community & Support

💬 Discussions & Q&A: GitHub Discussions
🐛 Bug reports: GitHub Issues
⭐ Star the repo to follow releases
📖 Full documentation: iOS developer docs · DocC sources

License

Wax is released under the Apache License 2.0. See LICENSE for details.

_{Built for developers who believe user data belongs on the user's device}

Name		Name	Last commit message	Last commit date
Latest commit History 710 Commits
.github/workflows		.github/workflows
.pi/extensions/wax-agents		.pi/extensions/wax-agents
Resources		Resources
Sources		Sources
Tests		Tests
scripts		scripts
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md

Navigation Menu

Repository files navigation

What is Wax?

What you can build

Choose Your Path

Swift Quick Start

1. Add Wax to your project

2. Copy-paste this into your app

Run the demo

CLI Quick Start

1. Install

2. Remember and recall from the terminal

Agent Quick Start

1. Install the MCP server (and stage the operator skill)

2. Install the wax-mcp skill (if install did not auto-register it)

3. Or paste project rules into CLAUDE.md / AGENTS.md

Why Wax?

Why a single `.wax` file?

Performance

Recall Latency (p95)

Cold Open Time (p95)

Architecture

Internal File Layout

Ecosystem Tools

🤖 MCP Server

🔍 WaxRepo

FAQ

Community & Support

License

About

Releases

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

What is Wax?

What you can build

Choose Your Path

Swift Quick Start

1. Add Wax to your project

2. Copy-paste this into your app

Run the demo

CLI Quick Start

1. Install

2. Remember and recall from the terminal

Agent Quick Start

1. Install the MCP server (and stage the operator skill)

2. Install the wax-mcp skill (if install did not auto-register it)

3. Or paste project rules into CLAUDE.md / AGENTS.md

Why Wax?

Why a single .wax file?

Performance

Recall Latency (p95)

Cold Open Time (p95)

Architecture

Internal File Layout

Ecosystem Tools

🤖 MCP Server

🔍 WaxRepo

FAQ

Community & Support

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages

Why a single `.wax` file?