Wax

What is Wax?

Wax is a local-first shared memory layer. It allows any AI to have a single file memory engine with access to vector search, photo and video rag, optimized for Apple Silicon

That store is one file: ~/.wax/memory.wax. No hosted vector DB. Memory, Decisions, facts survive the chat, the app, and the reboot.

Same Mac, many agents. For those using multiple different agents, Wax points each host at the file (or at one local HTTP server). They share memory instead of each keeping a private brain.

Another Mac Or iPhone Device Put the file in iCloud Drive and both machines see the same store, or AirDrop memory.wax like any other document.

~/Library/Mobile Documents/com~apple~CloudDocs/Wax/memory.wax   # iCloud
# or
AirDrop  memory.wax  →  ~/.wax/memory.wax

Agent setup: Agent Quick Start · host snippets: wax-mcp-hosts.md

Also a Swift engine

The Engine is Swift Native. Embed it in an iOS or macOS app when you want on-device RAG without standing up a server.

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

• Shared agent memory — one store across every MCP client on the machine.
• Carry it — iCloud the file between Macs, or AirDrop it.
• Personal knowledge — semantic search over notes and clips, still on disk.
• On-device RAG — ship memory inside an app, no cloud dependency.

Choose Your Path

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.2.22")
]

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

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()

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)"
                }
            }
    }
}

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:

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}