Wax 是为 Apple 平台 AI Agent 打造的高性能单文件记忆层。
设备端、私有且便携 —— 无需服务器，无需云端，零基础设施。
[English](../README.md) | [Español](README.es.md) | [Français](README.fr.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [中文](README.zh-CN.md)
Wax 是一款专为下一代 AI Agent 设计的 Swift 原生持久化引擎。它将文档、高维嵌入（embeddings）和结构化知识封装到单个便携的 .wax 文件中。
与需要复杂设置或依赖云端的传统数据库不同，Wax 提供了一个完全运行在设备端的统一记忆层，利用 Metal 加速推理，实现低于 10ms 的检索延迟。
| 特性 | Wax | SQLite (FTS5) | 云端向量数据库 |
|---|---|---|---|
| 搜索 | 混合（文本 + 向量） | 仅文本* | 仅向量* |
| 延迟 | ~6ms (p95) | ~10ms (p95) | 150ms - 500ms+ |
| 隐私 | 100% 本地 | 100% 本地 | 云端托管 |
| 设置 | 零配置 | 低 | 复杂（需要 API 密钥） |
| 架构 | Apple 芯片原生支持 | 通用 | 各异 |
大多数 RAG 系统需要数据库、向量存储和文件服务器。Wax 将所有内容（文档、元数据和高维索引）捆绑到一个便携的二进制文件中。
- 零基础设施： 无需 Docker，无需数据库设置，无云端账单。
- 真正便携： 通过 AirDrop 将 Agent 的记忆发送到另一台 Mac，或通过 iCloud 进行同步。
- 原子化： 一个文件用于备份，一个文件用于版本控制，一个文件即可删除。
Wax 针对 M 系列芯片架构进行了优化，即使在大规模本地索引下也能提供近乎瞬时的检索。
越低越好。以毫秒为单位。
Wax (混合) |██ 6.1ms
SQLite (文本) |████ 12ms
云端 RAG |██████████████████████████████████████████████████ 150ms+
越低越好。以毫秒为单位。
Wax |███ 9.2ms
传统方式 |██████████████████████████████████████ 120ms+
Tip
注入吞吐量： 在 M3 Max 上，Wax 在开启完整混合索引的情况下，处理速度达到 85.9 docs/s。 完整基准测试报告：docs/benchmarks/2026-03-06-performance-results.md
Wax 采用**“数据库中的数据库”**模型。它管理自己的基于帧（frame-based）的存储格式，同时将专用搜索引擎（SQLite FTS5 和 Metal 加速的 HNSW）作为序列化 blob 嵌入到主文件中。
┌──────────────────────────────────────────────────────────────────────────┐
│ 双 Header 页面 (A/B) │
│ (Magic, 版本, 世代, 指向 WAL 和 TOC 的指针, 校验和) │
├──────────────────────────────────────────────────────────────────────────┤
│ WAL (预写日志) │
│ (用于防崩溃的未提交变更的原子环形缓冲区) │
├──────────────────────────────────────────────────────────────────────────┤
│ 压缩数据帧 │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 帧 0 (LZ4) │ │ 帧 1 (LZ4) │ │ 帧 2 (LZ4) │ ... │
│ │ [原始文档] │ │ [元数据/JSON] │ │ [系统信息] │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ 混合搜索索引 │
│ ┌──────────────────────────────┐ ┌──────────────────────────────┐ │
│ │ SQLite FTS5 Blob │ │ Metal HNSW 索引 │ │
│ │ (文本搜索 + EAV 事实) │ │ (向量搜索) │ │
│ └──────────────────────────────┘ └──────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ TOC (目录) │
│ (所有帧的索引、父子关系及引擎配置清单) │
└──────────────────────────────────────────────────────────────────────────┘
- 原子韧性：双 Header 和 WAL 确保即使进程在写入中途崩溃，存储仍保持一致。
- 统一检索：单个查询即可触发 BM25（文本）和 HNSW（向量）引擎的并行执行。
- 结构化知识：内置 EAV（实体-属性-值）存储，用于持久化事实和长期推理。
将以下代码粘贴到 main.swift 文件中即可立即开始。
import Foundation
import Wax
import WaxVectorSearchMiniLM
@main
struct AgentMemory {
static func main() async throws {
let url = URL(fileURLWithPath: "agent.wax")
// 1. 初始化记忆存储（设备端 MiniLM 嵌入）
let memory = try await MemoryOrchestrator.openMiniLM(at: url)
// 2. 存入一条新记忆
try await memory.remember("用户正在使用 SwiftUI 开发一个习惯追踪器。")
// 3. 执行语义检索
let context = try await memory.recall(query: "用户正在开发什么？")
if let bestMatch = context.items.first {
print("检索结果：\(bestMatch.text)")
// 输出："检索结果：用户正在使用 SwiftUI 开发一个习惯追踪器。"
}
}
}想要存储持久化事实和长期推理？请参阅 结构化记忆。
dependencies: [
.package(url: "https://github.com/christopherkarani/Wax.git", from: "0.1.8")
]Wax 提供一流的 Model Context Protocol (MCP) 服务。将您的本地记忆连接到 Claude Code 或任何兼容 MCP 的 Agent。
npx -y waxmcp@latest mcp install --scope user针对 git 历史记录的语义搜索 TUI。索引任何代码库，并使用自然语言查找代码或提交记录。
# 在任何 git 代码库中运行
wax-repo index
wax-repo search "我们在哪里实现了 WAL？"Wax 采用 Apache License 2.0 发布。详见 LICENSE。