Wax is a high-performance, single-file memory layer for AI agents on Apple platforms.
On-device, private, and portable. No server and no cloud dependency.

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

Wax is a Swift-native persistence engine for AI agents. It stores documents, embeddings, and structured knowledge in a single portable .wax file.

The goal is simple: keep memory local, keep setup light, and make recall fast enough that it can stay in the loop.

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.

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

Lower is better. Measured in milliseconds.

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

Lower is better. Measured in milliseconds.

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

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.

┌──────────────────────────────────────────────────────────────────────────┐
│                          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)    │
└──────────────────────────────────────────────────────────────────────────┘

1. Atomic resilience: dual headers and the WAL keep the store consistent even if the process dies mid-write.
2. Unified retrieval: one query fans out to both the BM25 text index and the HNSW vector index.
3. Structured knowledge: built-in EAV (Entity-Attribute-Value) storage handles durable facts and long-term reasoning.

import Wax

// Use a sandbox-safe, writable location (works in apps and CLI tools)
let url = URL.documentsDirectory.appending(path: "agent.wax")

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

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

// 3. Search with hybrid recall (text + vector)
let results = try await memory.search("What is the user building?")

if let best = results.items.first {
    print("Found: \(best.text)")
    print("Document ID: \(best.metadata["id"] ?? "unknown")")
    // → "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 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()
    }
}

Looking to store persistent facts and long-term reasoning? See Structured Memory.

For repeated CLI vector work, Wax CLI now auto-starts and reuses a local broker that owns the long-term store and broker-managed session stores for commands such as remember, recall, and search --mode hybrid.

You can still run the broker directly when you want an explicit long-lived session:

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

Send JSON lines such as:

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

Simple text-only usage still runs one-shot. If vector search is unavailable, hybrid/vector commands now fail loudly instead of silently dropping to text-only mode.

If you use an AI coding assistant like Claude Code, Cursor, or Windsurf, there are two good setup paths:

• Use the Wax MCP server when you want persistent memory, session handoffs, and cross-session search inside the assistant.
• Use the bundled Wax skill when you want the assistant to write correct Wax framework code directly against the Swift API.

Install the MCP server (Claude Code):

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

This install flow stages the bundled Wax runtime into a stable local directory and registers the staged wax-mcp binary with Claude Code. npx is only used for install/bootstrap.

Install the skill (Claude Code):

# From within your project directory
claude install-skill https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax

Once installed, your assistant can work against Memory, VideoRAGOrchestrator, PhotoRAGOrchestrator, hybrid search, structured memory, and the MCP server without extra prompt scaffolding.

Or paste this prompt to get started from scratch:

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.

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

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

The published installer stages the bundled runtime into a stable local directory and registers wax-mcp directly, so steady-state MCP sessions do not launch through raw npx. For the recommended Claude Code prompt and setup flow, see Resources/docs/wax-mcp-setup.md.

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?"

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