🕯️ Wax

On-device memory for iOS & macOS AI agents.

No server. No cloud. One file.

Most iOS AI apps lose their memory the moment the user closes them. Wax fixes that — giving your agents persistent, searchable, private memory that lives entirely on-device in a single portable file.

let memory = try WaxMemory(url: .documentsDirectory.appending(path: "agent.wax"))

// Store a memory
try await memory.store("User prefers concise answers and hates bullet points.")

// Retrieve the most relevant context — semantically
let context = try await memory.search("communication preferences", limit: 5)

Why Wax

Building AI agents on Apple platforms means juggling Core Data for persistence, FAISS or Annoy for vector search, and a tokenizer for context budgets — none of which talk to each other. Or you spin up Chroma or Pinecone and suddenly your app has a server dependency, network calls, and a privacy story you can't tell users.

Wax packages all of it into one self-contained file:

Capability	Without Wax	With Wax
Document storage	Core Data / SQLite	✅ Built-in
Semantic search	External FAISS / Annoy	✅ Built-in (HNSW)
Full-text search	Another index	✅ Built-in (BM25)
Token budgeting	Manual	✅ Automatic
Crash safety	You figure it out	✅ WAL + dual headers
Server required	Often	✅ Never

Features

Hybrid retrieval — BM25 keyword search fused with HNSW vector similarity. Gets the right memory, even when wording differs.
On-device embeddings — Powered by MiniLM, running locally. No API calls, no latency, no cost.
Metal acceleration — Embedding and search use Apple Silicon GPU when available.
Token budgets — Set a hard limit. Wax automatically trims and compresses context to fit, every time.
Tiered surrogates — Store full text, a gist, or a micro-summary. Trade recall for speed at query time.
Single portable file — The whole memory store is one .wax file. Back it up, sync it, move it.
Crash-safe by design — Append-only format with write-ahead logging and dual headers. No corruption on unexpected exits.
Swift 6 concurrency — Fully async/await native with Sendable conformances throughout.

Installation

Swift Package Manager

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

Or in Xcode: File → Add Package Dependencies → paste the repo URL.

Quick Start

import Wax

// 1. Open (or create) a memory store
let memory = try WaxMemory(
    url: .documentsDirectory.appending(path: "myagent.wax"),
    tokenBudget: 4096
)

// 2. Store memories
try await memory.store("The user's name is Alex and they live in Toronto.")
try await memory.store("Alex dislikes formal language. Keep responses casual.")
try await memory.store("Alex is building a habit tracker in SwiftUI.")

// 3. Retrieve relevant context for a prompt
let relevant = try await memory.search("how should I address the user?", limit: 3)

// 4. Build your system prompt with budget-aware context
let context = memory.buildContext(from: relevant) // trims to fit tokenBudget

With Apple Foundation Models (iOS 26+)

import Wax
import FoundationModels

let memory = try WaxMemory(url: agentMemoryURL, tokenBudget: 4096)
let model = SystemLanguageModel.default

// Retrieve relevant memories and inject into session
let memories = try await memory.search(userMessage, limit: 5)
let systemPrompt = memory.buildContext(from: memories)

let session = LanguageModelSession(
    model: model,
    instructions: systemPrompt
)
let response = try await session.respond(to: userMessage)

// Store the exchange for future recall
try await memory.store(userMessage)
try await memory.store(response.content)

Use Cases

Conversational agents that remember preferences, history, and facts across sessions
Note-taking apps with semantic search ("find everything I wrote about WWDC")
Photo & video apps that index captions and transcripts for natural-language lookup
Personal assistants that learn user habits without sending data off-device
RAG pipelines built entirely on-device for sensitive or offline-first applications

Requirements

	Minimum
Swift	6.2
iOS	17.0
macOS	14.0
Xcode	16.0

Apple Silicon recommended for GPU-accelerated embedding. Intel Macs fall back to CPU seamlessly.

Comparison

	Wax	ChromaDB	Pinecone	Core Data + FAISS
On-device	✅	❌	❌	✅
No server	✅	❌	❌	✅
Hybrid search	✅	✅	✅	Manual
Token budgeting	✅	❌	❌	❌
Single file	✅	❌	❌	❌
Swift-native API	✅	❌	❌	Partial
Privacy (data stays on device)	✅	❌	❌	✅

Roadmap

CloudKit sync (opt-in, encrypted)
iCloud Drive .wax document support
Memory clustering and deduplication
Quantized embedding models for smaller footprint
Instruments template for memory profiling

Contributing

Issues and PRs are welcome. If you're building something with Wax, open a Discussion — would love to see what you're working on.

License

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

Wax