Wax 是一款高性能、单文件的内存层，专为 Apple 平台上的 AI 代理设计。
在设备端运行，私密且可移植。无需服务器，也无云端依赖。

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

Wax 是什么？

Wax 是一个 Swift 原生的持久化引擎，专为 AI 代理设计。它将文档、嵌入向量和结构化知识存储在一个单一的可移植 .wax 文件中。

目标很简单：让记忆保留在本地，设置尽可能轻量化，并确保检索速度足够快，从而能够持续参与交互过程。

为什么选择 Wax？

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

大多数 RAG 架构最终都会包含数据库、向量存储和文件服务器。而 Wax 通过将文档、元数据和索引打包到一个二进制文件中，大大简化了系统组件。

• 减少设置复杂度： 无需 Docker 环境，也无需单独维护数据库。
• 可移植性： 只需通过 AirDrop、iCloud 或其他同步方式即可轻松传输文件。
• 原子性： 备份、复制或删除整个文件即可，无需在多个服务之间追踪状态。

性能

Wax 针对 M 系列芯片硬件和本地检索进行了优化。

检索延迟（p95）

• 数值越低越好，单位为毫秒。

Wax（混合）  |██ 6.1ms
SQLite（文本） |████ 12ms
云端 RAG     |██████████████████████████████████████████████████ 150ms+

冷启动时间（p95）

• 数值越低越好，单位为毫秒。

Wax           |███ 9.2ms
传统方法   |██████████████████████████████████████ 120ms+

[!提示] 吞吐量： Wax 在 M3 Max 芯片上以全混合索引模式可处理 85.9 篇文档/秒。 完整基准测试报告：Resources/docs/benchmarks/2026-03-06-performance-results.md

架构

Wax 使用基于帧的容器格式，并将所需的搜索引擎直接嵌入主文件中：SQLite FTS5 用于文本检索，Metal 加速的 HNSW 索引则用于向量检索。

文件内部布局

┌──────────────────────────────────────────────────────────────────────────┐
│                          双重头部页（A/B）                         │
│   （魔数、版本、生成号、指向 WAL 和 TOC 的指针、校验和）         │
├──────────────────────────────────────────────────────────────────────────┤
│                          WAL（预写日志）                           │
│   （用于防止崩溃时未提交变更丢失的原子环形缓冲区）         │
├──────────────────────────────────────────────────────────────────────────┤
│                          压缩的数据帧                          │
│   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐       │
│   │ 帧 0（LZ4）    │  │ 帧 1（LZ4）    │  │ 帧 2（LZ4）    │ ...   │
│   │ [原始文档]   │  │ [元数据/JSON]  │  │ [系统信息]    │       │
│   └──────────────────┘  └──────────────────┘  └──────────────────┘       │
├──────────────────────────────────────────────────────────────────────────┤
│                          混合搜索索引                           │
│   ┌──────────────────────────────┐  ┌──────────────────────────────┐     │
│   │ SQLite FTS5 Blob             │  │ Metal HNSW 索引             │     │
│   │ （文本搜索 + EAV 事实）    │  │ （向量搜索）              │     │
│   └──────────────────────────────┘  └──────────────────────────────┘     │
├──────────────────────────────────────────────────────────────────────────┤
│                          TOC（目录）                         │
│   （所有帧的索引、父子关系以及各引擎的清单）    │
└──────────────────────────────────────────────────────────────────────────┘

1. 原子级容错： 双重头部和 WAL 日志确保即使进程在写入过程中意外终止，数据存储仍能保持一致。
2. 统一检索： 单一查询即可同时访问 BM25 文本索引和 HNSW 向量索引。
3. 结构化知识： 内置的 EAV（实体-属性-值）存储机制可以高效地管理持久性事实和长期推理任务。

快速入门

Swift

import Wax

// 使用沙盒安全的可写位置（适用于应用程序和 CLI 工具）
let url = URL.documentsDirectory.appending(path: "agent.wax")

// 1. 打开一个内存存储
let memory = try await Memory(at: url)

// 2. 保存一条记忆
try await memory.save("用户正在使用 SwiftUI 构建习惯追踪器。")

// 3. 使用混合召回（文本 + 向量）进行搜索
let results = try await memory.search("用户在构建什么？")

if let best = results.items.first {
    print("找到：\(best.text)")
    print("文档 ID：\(best.metadata["id"] ?? "未知")")
    // → "找到：用户正在使用 SwiftUI 构建习惯追踪器。"
}

try await memory.close()

import SwiftUI
import Wax

struct ContentView: View {
    @State private var result = "搜索中…"

    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("用户正在使用 SwiftUI 构建习惯追踪器。")
                    let context = try await memory.search("用户在构建什么？")

                    result = context.items.first?.text ?? "未找到任何内容"
                    try await memory.close()
                } catch {
                    result = "错误：\(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("用户正在使用 SwiftUI 构建习惯追踪器。")

        let results = try await memory.search("用户在构建什么？")
        if let best = results.items.first {
            print("找到：\(best.text)")
        }

        try await memory.close()
    }
}

想要存储持久化的事实和长期推理吗？请参阅 结构化记忆。

对于重复的 CLI 向量操作，Wax CLI 现在会自动启动并重用本地代理，该代理负责管理长期存储以及由代理管理的会话存储，以支持诸如 remember、recall 和 search --mode hybrid 等命令。

如果您需要显式且长期存在的会话，仍然可以直接运行代理：

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

您可以发送 JSON 行，例如：

{"id":"1","command":"remember","content":"汽车需要定期维护。"}
{"id":"2","command":"search","query":"汽车保养","mode":"hybrid","topK":3}
{"id":"3","command":"shutdown"}

简单的纯文本用法仍然是单次执行。如果向量搜索不可用，混合/向量命令现在会明确报错，而不是静默降级为纯文本模式。

AI 编程助手

如果您使用像 Claude Code、Cursor 或 Windsurf 这样的 AI 编程助手，有两种不错的设置方式：

• 当您需要持久化记忆、会话交接以及助手内部的跨会话搜索时，可以使用 Wax MCP 服务器。
• 当您希望助手直接根据 Swift API 编写正确的 Wax 框架代码时，可以使用捆绑的 Wax 技能。

安装 MCP 服务器（Claude Code）：

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

此安装流程会将捆绑的 Wax 运行时暂存到一个稳定的本地目录，并将暂存的 wax-mcp 二进制文件注册到 Claude Code 中。npx 仅用于安装/引导。

安装技能（Claude Code）：

# 从您的项目目录中
claude install-skill https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax

安装完成后，您的助手无需额外的提示支架，即可直接与 Memory、VideoRAGOrchestrator、PhotoRAGOrchestrator、混合搜索、结构化记忆以及 MCP 服务器协同工作。

或者粘贴以下提示以从头开始：

在此仓库中使用 Wax MCP 服务器来实现持久化记忆。

工作流程规则：
- 在会话开始时，首先调用 `handoff_latest` 加载先前的上下文，然后调用一次 `session_start` 并保留返回的 `session_id`。
- 使用 `remember` 存储决策、发现和简短的事实性笔记。如果记忆是会话范围的，请将 `session_id` 作为顶级参数传递。不要将 `session_id` 放入 `metadata` 中。
- 使用 `recall` 获取整合后的上下文，使用 `search` 获取原始的排名结果。
- 当语义检索有帮助时，优先选择 `mode: "hybrid"`。当您需要快速或确定性的词汇查找时，使用 `mode: "text"`。
- 在正常的代理流程中，不要管理 `SESSION_STORE`、`--store-path` 或 `flush`。长期记忆和虚拟会话存储由代理负责。
- 在会话结束时，使用 `handoff` 传递 `content`、可选的 `project` 和 `pending_tasks`，然后调用 `session_end`。
- 仅在需要跨会话检索代理管理的会话历史记录及其出处元数据时，才使用 `corpus_search`。
- 对于稳定的实体和事实，而非临时调试笔记，请使用结构化记忆工具（`entity_upsert`、`fact_assert`、`fact_retract`、`facts_query`、`entity_resolve`）。

行为期望：
- 在要求我重新陈述先前的上下文之前，先阅读现有的交接记录和召回结果。
- 保持记忆的简洁、事实性和任务相关性。
- 当跨会话的结果看起来相关时，请引用出处元数据，以便我们知道它来自哪个会话存储。

安装

Swift 包管理器

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

生态系统工具

🤖 MCP 服务器

Wax 提供一流的 模型上下文协议 (MCP) 服务器。将您的本地记忆连接到 Claude Code 或任何兼容 MCP 的代理。

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

发布的安装程序会将捆绑的运行时暂存到一个稳定的本地目录，并直接注册 wax-mcp，这样稳定的 MCP 会话就不需要通过原始的 npx 来启动。有关推荐的 Claude Code 提示和设置流程，请参阅 Resources/docs/wax-mcp-setup.md。

🔍 WaxRepo

一款用于 Git 历史记录的语义搜索 TUI。索引任何仓库，并使用自然语言查找代码或提交。

# 从任何 Git 仓库中
wax-repo index
wax-repo search "我们在哪里实现了 WAL？"

许可证

Wax 根据 Apache License 2.0 发布。详细信息请参阅 LICENSE。

Wax 快速上手指南

Wax 是一个专为 Apple 平台设计的高性能、单文件 AI 代理内存层。它完全在本地运行，无需服务器或云端依赖，支持混合搜索（文本 + 向量），并将文档、元数据和索引打包在一个便携的 .wax 文件中。

环境准备

• 操作系统：macOS 或 iOS (需 Apple Silicon M 系列芯片以获得最佳性能，兼容 Intel Mac)。
• 开发工具：Xcode 15.0+ 或 Swift 5.9+。
• 前置依赖：无额外系统级依赖，Wax 内部集成了 SQLite FTS5 和 Metal 加速的 HNSW 索引。

安装步骤

方式一：Swift Package Manager (推荐)

在你的 Swift 项目 Package.swift 中添加以下依赖：

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

然后在你的代码文件中导入模块：

import Wax

方式二：AI 编程助手集成 (可选)

如果你使用 Claude Code 等助手并希望其具备持久化记忆能力，可安装 MCP 服务器：

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

若需让助手直接生成正确的 Wax 代码，可安装技能包：

claude install-skill https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax

基本使用

以下示例展示了如何创建内存存储、保存数据以及执行混合搜索（文本 + 向量）。

1. 基础 Swift 用法

import Wax

// 1. 指定存储路径 (沙盒安全位置，适用于 App 或 CLI)
let url = URL.documentsDirectory.appending(path: "agent.wax")

// 2. 打开内存存储
let memory = try await Memory(at: url)

// 3. 保存一条记忆
try await memory.save("The user is building a habit tracker in SwiftUI.")

// 4. 执行混合搜索 (同时匹配文本语义和向量相似度)
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.
}

// 5. 关闭连接
try await memory.close()

2. SwiftUI 集成示例

在 SwiftUI 视图中直接使用：

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

3. 命令行工具 (CLI) 用法

对于需要长期运行的会话，可以启动后台守护进程：

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

通过标准输入发送 JSON 指令进行交互：

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

提示：如果不启动守护进程，简单的文本操作也可以作为一次性命令直接运行。如果设备不支持向量搜索，混合模式命令将明确报错，而不会静默降级为纯文本模式。