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

[English](README.md) | [Español](locales/README.es.md) | [Français](locales/README.fr.md) | [日本語](locales/README.ja.md) | [한국어](locales/README.ko.md) | [Português](locales/README.pt.md) | [中文](locales/README.zh-CN.md)

Wax is a Swift-native persistence engine designed for the next generation of AI agents. It encapsulates documents, high-dimensional embeddings, and structured knowledge into a single, portable .wax file.

Unlike traditional databases that require complex setups or cloud dependencies, Wax provides a unified memory layer that lives entirely on-device, leveraging Metal-accelerated inference for sub-10ms recall latency.

Most RAG systems require a database, a vector store, and a file server. Wax bundles everything—documents, metadata, and high-dimensional indices—into one portable binary.

• Zero Infrastructure: No Docker, no DB setup, no cloud bill.
• Truly Portable: AirDrop your agent's memory to another Mac, or sync it via iCloud.
• Atomic: One file to backup, one file to version control, one file to delete.

Wax is tuned for the M-series architecture, providing near-instantaneous recall even with large-scale local indices.

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 "Database of Databases" model. It manages its own frame-based storage format while embedding specialized search engines (SQLite FTS5 and Metal-accelerated HNSW) as serialized blobs within the main file.

┌──────────────────────────────────────────────────────────────────────────┐
│                          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 WAL ensure that even if the process crashes mid-write, the store remains consistent.
2. Unified Retrieval: A single query triggers parallel execution across the BM25 (text) and HNSW (vector) engines.
3. Structured Knowledge: Built-in EAV (Entity-Attribute-Value) storage for persistent facts and long-term reasoning.

Copy and paste this into a main.swift file to get started immediately.

import Foundation
import Wax
import WaxVectorSearchMiniLM

@main
struct AgentMemory {
    static func main() async throws {
        let url = URL(fileURLWithPath: "agent.wax")

        // 1. Initialize a memory store (on-device MiniLM embeddings)
        let memory = try await MemoryOrchestrator.openMiniLM(at: url)

        // 2. Commit a new memory
        try await memory.remember("The user is building a habit tracker in SwiftUI.")

        // 3. Perform semantic recall
        let context = try await memory.recall(query: "What is the user building?")

        if let bestMatch = context.items.first {
            print("Recall: \(bestMatch.text)") 
            // Output: "Recall: The user is building a habit tracker in SwiftUI."
        }
    }
}

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

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

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.