Wax

Wax 是一个面向 Apple 平台 AI Agent 的高性能单文件记忆层。 它完全在本地运行，保护隐私且便于移植。无需服务器，无需云端依赖。

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

---

什么是 Wax？

Wax 是一个专为 AI Agent 设计的 Swift 原生持久化引擎。它将文档、Embeddings 和结构化知识存储在一个轻便的 .wax 文件中。

我们的目标很简单：保持本地化存储，简化配置，并让数据召回速度快到足以维持 Agent 的实时推理循环。

为什么选择 Wax？

特性	Wax	SQLite (FTS5)	云端 Vector DBs
搜索	混合搜索 (文本 + 向量)	仅文本*	仅向量*
延迟	~6ms (p95)	~10ms (p95)	150ms - 500ms+
隐私	100% 本地	100% 本地	云端托管
配置	零配置	低	复杂 (API Keys)
架构	Apple Silicon 原生	通用	差异大

为什么要使用单个 .wax 文件？

大多数 RAG 设置通常涉及数据库、向量存储和文件服务器。Wax 通过将文档、元数据和索引打包成一个二进制文件，减少了组件数量。

• 更简单的配置： 无需 Docker 栈，也无需维护独立的数据库。
• 便携： 可以通过 AirDrop、iCloud 或你现有的任何同步方案轻松迁移文件。
• 原子性： 只需备份、复制或删除一个文件，无需在多个服务间同步状态。

---

性能表现

Wax 针对 M 系列硬件和本地召回进行了深度优化。

召回延迟 (p95)

越低越好。单位：毫秒。

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

冷启动时间 (p95)

越低越好。单位：毫秒。

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

[!TIP] 写入吞吐量： 在 M3 Max 上，Wax 在开启完整混合索引的情况下可处理 85.9 篇文档/秒。 完整性能报告：Resources/docs/benchmarks/2026-03-06-performance-results.md

---

架构

Wax 使用基于帧（Frame）的容器格式，并将搜索引擎直接嵌入文件内部：SQLite FTS5 用于文本搜索，Metal 加速的 HNSW 索引用于向量搜索。

内部文件布局

┌──────────────────────────────────────────────────────────────────────────┐
│                          双头部页 (A/B)                                   │
│   (Magic, Version, Generation, 指向 WAL 和 TOC 的指针, 校验和)          │
├──────────────────────────────────────────────────────────────────────────┤
│                          WAL (预写式日志)                                 │
│   (用于崩溃恢复、未提交变更的原子环形缓冲区)                            │
├──────────────────────────────────────────────────────────────────────────┤
│                          压缩数据帧                                      │
│   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐       │
│   │ 帧 0 (LZ4)       │  │ 帧 1 (LZ4)       │  │ 帧 2 (LZ4)       │ ...   │
│   │ [原始文档]       │  │ [元数据/JSON]    │  │ [系统信息]       │       │
│   └──────────────────┘  └──────────────────┘  └──────────────────┘       │
├──────────────────────────────────────────────────────────────────────────┤
│                          混合搜索索引                                    │
│   ┌──────────────────────────────┐  ┌──────────────────────────────┐     │
│   │ SQLite FTS5 Blob             │  │ Metal HNSW Index             │     │
│   │ (文本搜索 + EAV 事实)        │  │ (向量搜索)                   │     │
│   └──────────────────────────────┘  └──────────────────────────────┘     │
├──────────────────────────────────────────────────────────────────────────┤
│                          TOC (目录索引)                                  │
│   (所有帧的索引、父子关系及引擎清单)                                   │
└──────────────────────────────────────────────────────────────────────────┘

1. 原子韧性： 双头部和 WAL 机制确保即便在写入过程中进程意外终止，存储库依然保持一致性。
2. 统一检索： 单次查询可同时分发给 BM25 文本索引和 HNSW 向量索引。
3. 结构化知识： 内置 EAV (Entity-Attribute-Value) 存储，用于处理持久化事实和长期推理。

---

快速入门

Swift

import Wax

// 使用沙盒安全且可写的路径（适用于 App 和 CLI 工具）
let url = URL.documentsDirectory.appending(path: "agent.wax")

// 1. 打开存储空间
let memory = try await Memory(at: url)

// 2. 保存记忆
try await memory.save("The user is building a habit tracker in S