[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-christopherkarani--Wax":3,"tool-christopherkarani--Wax":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",157379,2,"2026-04-15T23:32:42",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":77,"owner_twitter":78,"owner_website":79,"owner_url":80,"languages":81,"stars":109,"forks":110,"last_commit_at":111,"license":112,"difficulty_score":32,"env_os":113,"env_gpu":114,"env_ram":115,"env_deps":116,"category_tags":123,"github_topics":125,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":146,"updated_at":147,"faqs":148,"releases":179},7879,"christopherkarani\u002FWax","Wax","Single-file memory layer for AI agents, sub mili-second RAG on Apple Silicon. Metal Optimized On-Device. No Server. No API. One File. Pure Swift","Wax 是一款专为苹果平台打造的高性能 AI 智能体记忆层，旨在让开发者轻松实现完全本地化、隐私安全的知识检索。它解决了传统 RAG（检索增强生成）系统依赖复杂服务器、云端数据库及繁琐配置的问题，将文档、向量索引和元数据全部封装在一个便携的 `.wax` 文件中。\n\n这意味着用户无需搭建 Docker 容器或管理独立的数据库服务，只需通过 AirDrop 或 iCloud 即可同步整个知识库，实现了真正的“零配置”部署。Wax 特别适合需要在 iOS 或 macOS 上开发本地 AI 应用的开发者，尤其是那些对数据隐私有严格要求或希望应用离线运行的场景。\n\n其核心技术亮点在于深度适配 Apple Silicon 芯片：利用 Metal 加速构建向量索引，并结合 SQLite FTS5 进行文本搜索，实现了亚毫秒级的混合检索延迟（p95 约 6ms），速度远超云端方案。作为纯 Swift 编写的单文件引擎，Wax 不仅启动迅速，更让 AI 智能体能够以极低的延迟实时调用记忆，真正将高效的知识检索保留在设备端。","\u003C!-- HEADER:START -->\n\u003Cdiv align=\"center\">\n  \u003Cpicture>\n    \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"Resources\u002Fdocs\u002Fassets\u002Fbanner-dark.svg\">\n    \u003Cimg src=\"Resources\u002Fdocs\u002Fassets\u002Fbanner-light.svg\" width=\"800\" alt=\"Wax Banner\">\n  \u003C\u002Fpicture>\n\u003C\u002Fdiv>\n\n\u003Cdiv style=\"height: 16px;\">\u003C\u002Fdiv>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Wax is a high-performance, single-file memory layer for AI agents on Apple platforms.\u003C\u002Fstrong>\u003Cbr\u002F>\n  On-device, private, and portable. No server and no cloud dependency.\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fchristopherkarani\u002FWax?style=flat-square&logo=swift&logoColor=white&label=Swift\" alt=\"Swift\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdeveloper.apple.com\u002Fios\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-iOS%20%7C%20macOS-lightgrey?style=flat-square\" alt=\"Platforms\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue?style=flat-square\" alt=\"License\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fchristopherkarani\u002FWax?style=flat-square&logo=github\" alt=\"Stars\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"README.md\">English\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.es.md\">Español\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.fr.md\">Français\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.ja.md\">日本語\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.ko.md\">한국어\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.pt.md\">Português\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.zh-CN.md\">中文\u003C\u002Fa>\n\u003C\u002Fp>\n\u003C!-- HEADER:END -->\n\n---\n\n## What is Wax?\n\nWax is a Swift-native persistence engine for AI agents. It stores documents, embeddings, and structured knowledge in a single portable `.wax` file.\n\nThe goal is simple: keep memory local, keep setup light, and make recall fast enough that it can stay in the loop.\n\n### Why Wax?\n\n| Feature          | Wax                    | SQLite (FTS5)          | Cloud Vector DBs       |\n|:-----------------|:-----------------------|:-----------------------|:-----------------------|\n| **Search**       | Hybrid (Text + Vector) | Text Only*             | Vector Only*           |\n| **Latency**      | **~6ms (p95)**         | ~10ms (p95)            | 150ms - 500ms+         |\n| **Privacy**      | 100% Local             | 100% Local             | Cloud-hosted           |\n| **Setup**        | Zero Config            | Low                    | Complex (API Keys)     |\n| **Architecture** | Apple Silicon Native   | Generic                | Varies                 |\n\n### Why a single `.wax` file?\nMost RAG setups end up with a database, a vector store, and a file server. Wax keeps the moving pieces smaller by bundling documents, metadata, and indexes into one binary.\n*   **Less setup:** no Docker stack and no separate database to babysit.\n*   **Portable:** move the file with AirDrop, iCloud, or whatever sync layer you already use.\n*   **Atomic:** backup, copy, or delete one file instead of chasing state across services.\n\n---\n\n## Performance\n\nWax is tuned for M-series hardware and local recall.\n\n### Recall Latency (p95)\n*Lower is better. Measured in milliseconds.*\n\n```text\nWax (Hybrid)  |██ 6.1ms\nSQLite (Text) |████ 12ms\nCloud RAG     |██████████████████████████████████████████████████ 150ms+\n```\n\n### Cold Open Time (p95)\n*Lower is better. Measured in milliseconds.*\n\n```text\nWax           |███ 9.2ms\nTraditional   |██████████████████████████████████████ 120ms+\n```\n\n> [!TIP]\n> **Ingest Throughput:** Wax handles **85.9 docs\u002Fs** with full hybrid indexing on an M3 Max.\n> Full benchmark report: [Resources\u002Fdocs\u002Fbenchmarks\u002F2026-03-06-performance-results.md](Resources\u002Fdocs\u002Fbenchmarks\u002F2026-03-06-performance-results.md)\n\n---\n\n## Architecture\n\nWax uses a frame-based container format and embeds the search engines it needs inside the main file: SQLite FTS5 for text and a Metal-accelerated HNSW index for vectors.\n\n### Internal File Layout\n\n```text\n┌──────────────────────────────────────────────────────────────────────────┐\n│                          Dual Header Pages (A\u002FB)                         │\n│   (Magic, Version, Generation, Pointers to WAL & TOC, Checksums)         │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          WAL (Write-Ahead Log)                           │\n│   (Atomic ring buffer for crash-resilient uncommitted mutations)         │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          Compressed Data Frames                          │\n│   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐       │\n│   │ Frame 0 (LZ4)    │  │ Frame 1 (LZ4)    │  │ Frame 2 (LZ4)    │ ...   │\n│   │ [Raw Document]   │  │ [Metadata\u002FJSON]  │  │ [System Info]    │       │\n│   └──────────────────┘  └──────────────────┘  └──────────────────┘       │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          Hybrid Search Indices                           │\n│   ┌──────────────────────────────┐  ┌──────────────────────────────┐     │\n│   │ SQLite FTS5 Blob             │  │ Metal HNSW Index             │     │\n│   │ (Text Search + EAV Facts)    │  │ (Vector Search)              │     │\n│   └──────────────────────────────┘  └──────────────────────────────┘     │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          TOC (Table of Contents)                         │\n│   (Index of all frames, parent-child relations, and engine manifests)    │\n└──────────────────────────────────────────────────────────────────────────┘\n```\n\n1. **Atomic resilience:** dual headers and the WAL keep the store consistent even if the process dies mid-write.\n2. **Unified retrieval:** one query fans out to both the BM25 text index and the HNSW vector index.\n3. **Structured knowledge:** built-in EAV (Entity-Attribute-Value) storage handles durable facts and long-term reasoning.\n\n---\n\n## Quick Start\n\n### Swift\n\n```swift\nimport Wax\n\n\u002F\u002F Use a sandbox-safe, writable location (works in apps and CLI tools)\nlet url = URL.documentsDirectory.appending(path: \"agent.wax\")\n\n\u002F\u002F 1. Open a memory store\nlet memory = try await Memory(at: url)\n\n\u002F\u002F 2. Save a memory\ntry await memory.save(\"The user is building a habit tracker in SwiftUI.\")\n\n\u002F\u002F 3. Search with hybrid recall (text + vector)\nlet results = try await memory.search(\"What is the user building?\")\n\nif let best = results.items.first {\n    print(\"Found: \\(best.text)\")\n    print(\"Document ID: \\(best.metadata[\"id\"] ?? \"unknown\")\")\n    \u002F\u002F → \"Found: The user is building a habit tracker in SwiftUI.\"\n}\n\ntry await memory.close()\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>SwiftUI example\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```swift\nimport SwiftUI\nimport Wax\n\nstruct ContentView: View {\n    @State private var result = \"Searching…\"\n\n    var body: some View {\n        Text(result)\n            .task {\n                do {\n                    let url = URL.documentsDirectory.appending(path: \"agent.wax\")\n                    let memory = try await Memory(at: url)\n\n                    try await memory.save(\"The user is building a habit tracker in SwiftUI.\")\n                    let context = try await memory.search(\"What is the user building?\")\n\n                    result = context.items.first?.text ?? \"Nothing found\"\n                    try await memory.close()\n                } catch {\n                    result = \"Error: \\(error.localizedDescription)\"\n                }\n            }\n    }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>CLI tool (main.swift)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```swift\nimport Wax\n\n@main\nstruct AgentMemory {\n    static func main() async throws {\n        let url = URL.documentsDirectory.appending(path: \"agent.wax\")\n        let memory = try await Memory(at: url)\n\n        try await memory.save(\"The user is building a habit tracker in SwiftUI.\")\n\n        let results = try await memory.search(\"What is the user building?\")\n        if let best = results.items.first {\n            print(\"Found: \\(best.text)\")\n        }\n\n        try await memory.close()\n    }\n}\n```\n\n\u003C\u002Fdetails>\n\nLooking to store persistent facts and long-term reasoning? See [Structured Memory](Sources\u002FWaxCore\u002FWaxCore.docc\u002FArticles\u002FStructuredMemory.md).\n\nFor repeated CLI vector work, Wax CLI now auto-starts and reuses a local broker that owns\nthe long-term store and broker-managed session stores for commands such as `remember`,\n`recall`, and `search --mode hybrid`.\n\nYou can still run the broker directly when you want an explicit long-lived session:\n\n```bash\nwax-cli daemon --store-path ~\u002F.wax\u002Fmemory.wax\n```\n\nSend JSON lines such as:\n\n```json\n{\"id\":\"1\",\"command\":\"remember\",\"content\":\"An automobile needs periodic maintenance.\"}\n{\"id\":\"2\",\"command\":\"search\",\"query\":\"car service\",\"mode\":\"hybrid\",\"topK\":3}\n{\"id\":\"3\",\"command\":\"shutdown\"}\n```\n\nSimple text-only usage still runs one-shot. If vector search is unavailable, hybrid\u002Fvector\ncommands now fail loudly instead of silently dropping to text-only mode.\n\n### AI Coding Assistants\n\nIf you use an AI coding assistant like **Claude Code**, **Cursor**, or **Windsurf**, there are two good setup paths:\n\n- Use the **Wax MCP server** when you want persistent memory, session handoffs, and cross-session search inside the assistant.\n- Use the bundled **Wax skill** when you want the assistant to write correct Wax framework code directly against the Swift API.\n\n**Install the MCP server (Claude Code):**\n\n```bash\nnpx -y waxmcp@latest mcp install --scope user\n```\n\nThis install flow stages the bundled Wax runtime into a stable local directory and\nregisters the staged `wax-mcp` binary with Claude Code. `npx` is only used for install\u002Fbootstrap.\n\n**Install the skill (Claude Code):**\n\n```bash\n# From within your project directory\nclaude install-skill https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Ftree\u002Fmain\u002FResources\u002Fskills\u002Fpublic\u002Fwax\n```\n\nOnce installed, your assistant can work against `Memory`, `VideoRAGOrchestrator`, `PhotoRAGOrchestrator`, hybrid search, structured memory, and the MCP server without extra prompt scaffolding.\n\n**Or paste this prompt to get started from scratch:**\n\n\u003Cdetails>\n\u003Csummary>Wax starter prompt (click to expand, then copy)\u003C\u002Fsummary>\n\n```text\nUse the Wax MCP server for persistent memory in this repo.\n\nWorkflow rules:\n- At session start, call `handoff_latest` first to load prior context, then call `session_start` once and keep the returned `session_id`.\n- Use `remember` to store decisions, discoveries, and short factual notes. If the memory is session-scoped, pass `session_id` as a top-level argument. Do not put `session_id` inside `metadata`.\n- Use `recall` for assembled context and `search` for raw ranked hits.\n- Prefer `mode: \"hybrid\"` when semantic retrieval helps. Use `mode: \"text\"` when I want a fast or deterministic lexical lookup.\n- Do not manage `SESSION_STORE`, `--store-path`, or `flush` in normal agent flows. The broker owns long-term memory and virtual session stores.\n- Use `handoff` near the end of the session with `content`, optional `project`, and `pending_tasks`, then call `session_end`.\n- Use `corpus_search` only when you need cross-session retrieval across broker-managed session history with provenance metadata.\n- Use structured memory tools (`entity_upsert`, `fact_assert`, `fact_retract`, `facts_query`, `entity_resolve`) for stable entities and facts, not transient debugging notes.\n\nBehavior expectations:\n- Read existing handoffs and recall results before asking me to restate prior context.\n- Keep memory writes concise, factual, and scoped to the task.\n- When a cross-session result looks relevant, cite the provenance metadata so we know which session store it came from.\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## Installation\n\n### Swift Package Manager\n\n```swift\ndependencies: [\n    .package(url: \"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax.git\", from: \"0.1.8\")\n]\n```\n\n---\n\n## Ecosystem Tools\n\n### 🤖 MCP Server\nWax provides a first-class **Model Context Protocol (MCP)** server. Connect your local memory to Claude Code or any MCP-compatible agent.\n\n```bash\nnpx -y waxmcp@latest mcp install --scope user\n```\n\nThe published installer stages the bundled runtime into a stable local directory and\nregisters `wax-mcp` directly, so steady-state MCP sessions do not launch through raw `npx`.\nFor the recommended Claude Code prompt and setup flow, see [Resources\u002Fdocs\u002Fwax-mcp-setup.md](Resources\u002Fdocs\u002Fwax-mcp-setup.md).\n\n### 🔍 WaxRepo\nA semantic search TUI for your git history. Index any repository and find code or commits using natural language.\n\n```bash\n# From within any git repo\nwax-repo index\nwax-repo search \"where did we implement the WAL?\"\n```\n\n---\n\n## License\n\nWax is released under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n\u003Cdiv align=\"center\">\n\u003Csub>Built for developers who believe user data belongs on the user's device.\u003C\u002Fsub>\n\u003C\u002Fdiv>\n","\u003C!-- 头部：开始 -->\n\u003Cdiv align=\"center\">\n  \u003Cpicture>\n    \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"Resources\u002Fdocs\u002Fassets\u002Fbanner-dark.svg\">\n    \u003Cimg src=\"Resources\u002Fdocs\u002Fassets\u002Fbanner-light.svg\" width=\"800\" alt=\"Wax 横幅\">\n  \u003C\u002Fpicture>\n\u003C\u002Fdiv>\n\n\u003Cdiv style=\"height: 16px;\">\u003C\u002Fdiv>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Wax 是一款高性能、单文件的内存层，专为 Apple 平台上的 AI 代理设计。\u003C\u002Fstrong>\u003Cbr\u002F>\n  在设备端运行，私密且可移植。无需服务器，也无云端依赖。\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fchristopherkarani\u002FWax?style=flat-square&logo=swift&logoColor=white&label=Swift\" alt=\"Swift\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdeveloper.apple.com\u002Fios\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-iOS%20%7C%20macOS-lightgrey?style=flat-square\" alt=\"平台\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue?style=flat-square\" alt=\"许可证\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fchristopherkarani\u002FWax?style=flat-square&logo=github\" alt=\"星标\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"README.md\">English\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.es.md\">Español\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.fr.md\">Français\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.ja.md\">日本語\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.ko.md\">한국어\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.pt.md\">Português\u003C\u002Fa> · \u003Ca href=\"Resources\u002Flocales\u002FREADME.zh-CN.md\">中文\u003C\u002Fa>\n\u003C\u002Fp>\n\u003C!-- 头部：结束 -->\n\n---\n\n## Wax 是什么？\n\nWax 是一个 Swift 原生的持久化引擎，专为 AI 代理设计。它将文档、嵌入向量和结构化知识存储在一个单一的可移植 `.wax` 文件中。\n\n目标很简单：让记忆保留在本地，设置尽可能轻量化，并确保检索速度足够快，从而能够持续参与交互过程。\n\n### 为什么选择 Wax？\n\n| 特性          | Wax                    | SQLite (FTS5)          | 云端向量数据库       |\n|:-----------------|:-----------------------|:-----------------------|:-----------------------|\n| **搜索**       | 混合（文本 + 向量）    | 仅文本*             | 仅向量*           |\n| **延迟**      | **~6ms (p95)**         | ~10ms (p95)            | 150ms - 500ms+         |\n| **隐私**      | 100% 本地             | 100% 本地             | 云端托管           |\n| **设置**        | 无需配置              | 较低                   | 复杂（API 密钥）     |\n| **架构** | 苹果芯片原生           | 通用                   | 各不相同             |\n\n### 为什么使用单个 `.wax` 文件？\n大多数 RAG 架构最终都会包含数据库、向量存储和文件服务器。而 Wax 通过将文档、元数据和索引打包到一个二进制文件中，大大简化了系统组件。\n\n*   **减少设置复杂度：** 无需 Docker 环境，也无需单独维护数据库。\n*   **可移植性：** 只需通过 AirDrop、iCloud 或其他同步方式即可轻松传输文件。\n*   **原子性：** 备份、复制或删除整个文件即可，无需在多个服务之间追踪状态。\n\n---\n\n## 性能\n\nWax 针对 M 系列芯片硬件和本地检索进行了优化。\n\n### 检索延迟（p95）\n* 数值越低越好，单位为毫秒。\n\n```text\nWax（混合）  |██ 6.1ms\nSQLite（文本） |████ 12ms\n云端 RAG     |██████████████████████████████████████████████████ 150ms+\n```\n\n### 冷启动时间（p95）\n* 数值越低越好，单位为毫秒。\n\n```text\nWax           |███ 9.2ms\n传统方法   |██████████████████████████████████████ 120ms+\n```\n\n> [!提示]\n> **吞吐量：** Wax 在 M3 Max 芯片上以全混合索引模式可处理 **85.9 篇文档\u002F秒**。\n> 完整基准测试报告：[Resources\u002Fdocs\u002Fbenchmarks\u002F2026-03-06-performance-results.md](Resources\u002Fdocs\u002Fbenchmarks\u002F2026-03-06-performance-results.md)\n\n---\n\n## 架构\n\nWax 使用基于帧的容器格式，并将所需的搜索引擎直接嵌入主文件中：SQLite FTS5 用于文本检索，Metal 加速的 HNSW 索引则用于向量检索。\n\n### 文件内部布局\n\n```text\n┌──────────────────────────────────────────────────────────────────────────┐\n│                          双重头部页（A\u002FB）                         │\n│   （魔数、版本、生成号、指向 WAL 和 TOC 的指针、校验和）         │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          WAL（预写日志）                           │\n│   （用于防止崩溃时未提交变更丢失的原子环形缓冲区）         │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          压缩的数据帧                          │\n│   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐       │\n│   │ 帧 0（LZ4）    │  │ 帧 1（LZ4）    │  │ 帧 2（LZ4）    │ ...   │\n│   │ [原始文档]   │  │ [元数据\u002FJSON]  │  │ [系统信息]    │       │\n│   └──────────────────┘  └──────────────────┘  └──────────────────┘       │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          混合搜索索引                           │\n│   ┌──────────────────────────────┐  ┌──────────────────────────────┐     │\n│   │ SQLite FTS5 Blob             │  │ Metal HNSW 索引             │     │\n│   │ （文本搜索 + EAV 事实）    │  │ （向量搜索）              │     │\n│   └──────────────────────────────┘  └──────────────────────────────┘     │\n├──────────────────────────────────────────────────────────────────────────┤\n│                          TOC（目录）                         │\n│   （所有帧的索引、父子关系以及各引擎的清单）    │\n└──────────────────────────────────────────────────────────────────────────┘\n```\n\n1. **原子级容错：** 双重头部和 WAL 日志确保即使进程在写入过程中意外终止，数据存储仍能保持一致。\n2. **统一检索：** 单一查询即可同时访问 BM25 文本索引和 HNSW 向量索引。\n3. **结构化知识：** 内置的 EAV（实体-属性-值）存储机制可以高效地管理持久性事实和长期推理任务。\n\n---\n\n## 快速入门\n\n### Swift\n\n```swift\nimport Wax\n\n\u002F\u002F 使用沙盒安全的可写位置（适用于应用程序和 CLI 工具）\nlet url = URL.documentsDirectory.appending(path: \"agent.wax\")\n\n\u002F\u002F 1. 打开一个内存存储\nlet memory = try await Memory(at: url)\n\n\u002F\u002F 2. 保存一条记忆\ntry await memory.save(\"用户正在使用 SwiftUI 构建习惯追踪器。\")\n\n\u002F\u002F 3. 使用混合召回（文本 + 向量）进行搜索\nlet results = try await memory.search(\"用户在构建什么？\")\n\nif let best = results.items.first {\n    print(\"找到：\\(best.text)\")\n    print(\"文档 ID：\\(best.metadata[\"id\"] ?? \"未知\")\")\n    \u002F\u002F → \"找到：用户正在使用 SwiftUI 构建习惯追踪器。\"\n}\n\ntry await memory.close()\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>SwiftUI 示例\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```swift\nimport SwiftUI\nimport Wax\n\nstruct ContentView: View {\n    @State private var result = \"搜索中…\"\n\n    var body: some View {\n        Text(result)\n            .task {\n                do {\n                    let url = URL.documentsDirectory.appending(path: \"agent.wax\")\n                    let memory = try await Memory(at: url)\n\n                    try await memory.save(\"用户正在使用 SwiftUI 构建习惯追踪器。\")\n                    let context = try await memory.search(\"用户在构建什么？\")\n\n                    result = context.items.first?.text ?? \"未找到任何内容\"\n                    try await memory.close()\n                } catch {\n                    result = \"错误：\\(error.localizedDescription)\"\n                }\n            }\n    }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>CLI 工具（main.swift）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```swift\nimport Wax\n\n@main\nstruct AgentMemory {\n    static func main() async throws {\n        let url = URL.documentsDirectory.appending(path: \"agent.wax\")\n        let memory = try await Memory(at: url)\n\n        try await memory.save(\"用户正在使用 SwiftUI 构建习惯追踪器。\")\n\n        let results = try await memory.search(\"用户在构建什么？\")\n        if let best = results.items.first {\n            print(\"找到：\\(best.text)\")\n        }\n\n        try await memory.close()\n    }\n}\n```\n\n\u003C\u002Fdetails>\n\n想要存储持久化的事实和长期推理吗？请参阅 [结构化记忆](Sources\u002FWaxCore\u002FWaxCore.docc\u002FArticles\u002FStructuredMemory.md)。\n\n对于重复的 CLI 向量操作，Wax CLI 现在会自动启动并重用本地代理，该代理负责管理长期存储以及由代理管理的会话存储，以支持诸如 `remember`、`recall` 和 `search --mode hybrid` 等命令。\n\n如果您需要显式且长期存在的会话，仍然可以直接运行代理：\n\n```bash\nwax-cli daemon --store-path ~\u002F.wax\u002Fmemory.wax\n```\n\n您可以发送 JSON 行，例如：\n\n```json\n{\"id\":\"1\",\"command\":\"remember\",\"content\":\"汽车需要定期维护。\"}\n{\"id\":\"2\",\"command\":\"search\",\"query\":\"汽车保养\",\"mode\":\"hybrid\",\"topK\":3}\n{\"id\":\"3\",\"command\":\"shutdown\"}\n```\n\n简单的纯文本用法仍然是单次执行。如果向量搜索不可用，混合\u002F向量命令现在会明确报错，而不是静默降级为纯文本模式。\n\n### AI 编程助手\n\n如果您使用像 **Claude Code**、**Cursor** 或 **Windsurf** 这样的 AI 编程助手，有两种不错的设置方式：\n\n- 当您需要持久化记忆、会话交接以及助手内部的跨会话搜索时，可以使用 **Wax MCP 服务器**。\n- 当您希望助手直接根据 Swift API 编写正确的 Wax 框架代码时，可以使用捆绑的 **Wax 技能**。\n\n**安装 MCP 服务器（Claude Code）：**\n\n```bash\nnpx -y waxmcp@latest mcp install --scope user\n```\n\n此安装流程会将捆绑的 Wax 运行时暂存到一个稳定的本地目录，并将暂存的 `wax-mcp` 二进制文件注册到 Claude Code 中。`npx` 仅用于安装\u002F引导。\n\n**安装技能（Claude Code）：**\n\n```bash\n# 从您的项目目录中\nclaude install-skill https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Ftree\u002Fmain\u002FResources\u002Fskills\u002Fpublic\u002Fwax\n```\n\n安装完成后，您的助手无需额外的提示支架，即可直接与 `Memory`、`VideoRAGOrchestrator`、`PhotoRAGOrchestrator`、混合搜索、结构化记忆以及 MCP 服务器协同工作。\n\n**或者粘贴以下提示以从头开始：**\n\n\u003Cdetails>\n\u003Csummary>Wax 入门提示（点击展开后复制）\u003C\u002Fsummary>\n\n```text\n在此仓库中使用 Wax MCP 服务器来实现持久化记忆。\n\n工作流程规则：\n- 在会话开始时，首先调用 `handoff_latest` 加载先前的上下文，然后调用一次 `session_start` 并保留返回的 `session_id`。\n- 使用 `remember` 存储决策、发现和简短的事实性笔记。如果记忆是会话范围的，请将 `session_id` 作为顶级参数传递。不要将 `session_id` 放入 `metadata` 中。\n- 使用 `recall` 获取整合后的上下文，使用 `search` 获取原始的排名结果。\n- 当语义检索有帮助时，优先选择 `mode: \"hybrid\"`。当您需要快速或确定性的词汇查找时，使用 `mode: \"text\"`。\n- 在正常的代理流程中，不要管理 `SESSION_STORE`、`--store-path` 或 `flush`。长期记忆和虚拟会话存储由代理负责。\n- 在会话结束时，使用 `handoff` 传递 `content`、可选的 `project` 和 `pending_tasks`，然后调用 `session_end`。\n- 仅在需要跨会话检索代理管理的会话历史记录及其出处元数据时，才使用 `corpus_search`。\n- 对于稳定的实体和事实，而非临时调试笔记，请使用结构化记忆工具（`entity_upsert`、`fact_assert`、`fact_retract`、`facts_query`、`entity_resolve`）。\n\n行为期望：\n- 在要求我重新陈述先前的上下文之前，先阅读现有的交接记录和召回结果。\n- 保持记忆的简洁、事实性和任务相关性。\n- 当跨会话的结果看起来相关时，请引用出处元数据，以便我们知道它来自哪个会话存储。\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 安装\n\n### Swift 包管理器\n\n```swift\ndependencies: [\n    .package(url: \"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax.git\", from: \"0.1.8\")\n]\n```\n\n---\n\n## 生态系统工具\n\n### 🤖 MCP 服务器\nWax 提供一流的 **模型上下文协议 (MCP)** 服务器。将您的本地记忆连接到 Claude Code 或任何兼容 MCP 的代理。\n\n```bash\nnpx -y waxmcp@latest mcp install --scope user\n```\n\n发布的安装程序会将捆绑的运行时暂存到一个稳定的本地目录，并直接注册 `wax-mcp`，这样稳定的 MCP 会话就不需要通过原始的 `npx` 来启动。有关推荐的 Claude Code 提示和设置流程，请参阅 [Resources\u002Fdocs\u002Fwax-mcp-setup.md](Resources\u002Fdocs\u002Fwax-mcp-setup.md)。\n\n### 🔍 WaxRepo\n一款用于 Git 历史记录的语义搜索 TUI。索引任何仓库，并使用自然语言查找代码或提交。\n\n```bash\n# 从任何 Git 仓库中\nwax-repo index\nwax-repo search \"我们在哪里实现了 WAL？\"\n```\n\n---\n\n## 许可证\nWax 根据 Apache License 2.0 发布。详细信息请参阅 [LICENSE](LICENSE)。\n\n\u003Cdiv align=\"center\">\n\u003Csub>专为相信用户数据应属于用户设备的开发者打造。\u003C\u002Fsub>\n\u003C\u002Fdiv>","# Wax 快速上手指南\n\nWax 是一个专为 Apple 平台设计的高性能、单文件 AI 代理内存层。它完全在本地运行，无需服务器或云端依赖，支持混合搜索（文本 + 向量），并将文档、元数据和索引打包在一个便携的 `.wax` 文件中。\n\n## 环境准备\n\n*   **操作系统**：macOS 或 iOS (需 Apple Silicon M 系列芯片以获得最佳性能，兼容 Intel Mac)。\n*   **开发工具**：Xcode 15.0+ 或 Swift 5.9+。\n*   **前置依赖**：无额外系统级依赖，Wax 内部集成了 SQLite FTS5 和 Metal 加速的 HNSW 索引。\n\n## 安装步骤\n\n### 方式一：Swift Package Manager (推荐)\n\n在你的 Swift 项目 `Package.swift` 中添加以下依赖：\n\n```swift\ndependencies: [\n    .package(url: \"https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax.git\", from: \"0.1.8\")\n]\n```\n\n然后在你的代码文件中导入模块：\n```swift\nimport Wax\n```\n\n### 方式二：AI 编程助手集成 (可选)\n\n如果你使用 **Claude Code** 等助手并希望其具备持久化记忆能力，可安装 MCP 服务器：\n\n```bash\nnpx -y waxmcp@latest mcp install --scope user\n```\n\n若需让助手直接生成正确的 Wax 代码，可安装技能包：\n```bash\nclaude install-skill https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Ftree\u002Fmain\u002FResources\u002Fskills\u002Fpublic\u002Fwax\n```\n\n## 基本使用\n\n以下示例展示了如何创建内存存储、保存数据以及执行混合搜索（文本 + 向量）。\n\n### 1. 基础 Swift 用法\n\n```swift\nimport Wax\n\n\u002F\u002F 1. 指定存储路径 (沙盒安全位置，适用于 App 或 CLI)\nlet url = URL.documentsDirectory.appending(path: \"agent.wax\")\n\n\u002F\u002F 2. 打开内存存储\nlet memory = try await Memory(at: url)\n\n\u002F\u002F 3. 保存一条记忆\ntry await memory.save(\"The user is building a habit tracker in SwiftUI.\")\n\n\u002F\u002F 4. 执行混合搜索 (同时匹配文本语义和向量相似度)\nlet results = try await memory.search(\"What is the user building?\")\n\nif let best = results.items.first {\n    print(\"Found: \\(best.text)\")\n    print(\"Document ID: \\(best.metadata[\"id\"] ?? \"unknown\")\")\n    \u002F\u002F 输出: Found: The user is building a habit tracker in SwiftUI.\n}\n\n\u002F\u002F 5. 关闭连接\ntry await memory.close()\n```\n\n### 2. SwiftUI 集成示例\n\n在 SwiftUI 视图中直接使用：\n\n```swift\nimport SwiftUI\nimport Wax\n\nstruct ContentView: View {\n    @State private var result = \"Searching…\"\n\n    var body: some View {\n        Text(result)\n            .task {\n                do {\n                    let url = URL.documentsDirectory.appending(path: \"agent.wax\")\n                    let memory = try await Memory(at: url)\n\n                    \u002F\u002F 写入数据\n                    try await memory.save(\"The user is building a habit tracker in SwiftUI.\")\n                    \n                    \u002F\u002F 查询数据\n                    let context = try await memory.search(\"What is the user building?\")\n\n                    result = context.items.first?.text ?? \"Nothing found\"\n                    try await memory.close()\n                } catch {\n                    result = \"Error: \\(error.localizedDescription)\"\n                }\n            }\n    }\n}\n```\n\n### 3. 命令行工具 (CLI) 用法\n\n对于需要长期运行的会话，可以启动后台守护进程：\n\n```bash\nwax-cli daemon --store-path ~\u002F.wax\u002Fmemory.wax\n```\n\n通过标准输入发送 JSON 指令进行交互：\n\n```json\n{\"id\":\"1\",\"command\":\"remember\",\"content\":\"An automobile needs periodic maintenance.\"}\n{\"id\":\"2\",\"command\":\"search\",\"query\":\"car service\",\"mode\":\"hybrid\",\"topK\":3}\n{\"id\":\"3\",\"command\":\"shutdown\"}\n```\n\n> **提示**：如果不启动守护进程，简单的文本操作也可以作为一次性命令直接运行。如果设备不支持向量搜索，混合模式命令将明确报错，而不会静默降级为纯文本模式。","一位 iOS 开发者正在为一款面向医疗从业者的本地化 AI 助手应用构建知识库功能，要求所有患者笔记和医学文献必须在设备端处理，严禁上传云端。\n\n### 没有 Wax 时\n- **架构臃肿**：为了同时支持文本关键词搜索和向量语义检索，不得不集成 SQLite 和独立的向量数据库库，导致项目依赖复杂，二进制体积显著增加。\n- **隐私合规风险**：若采用云端向量服务以降低开发难度，敏感医疗数据需传出设备，直接违反 HIPAA 等隐私法规，导致应用无法上架。\n- **响应延迟高**：在旧有的混合架构下，冷启动加载索引耗时超过 120ms，且复杂查询的 p95 延迟波动大，影响医生在查房时快速获取信息的流畅度。\n- **数据同步困难**：用户的多设备间知识备份需要协调数据库文件、向量索引文件和原始文档三个独立部分，极易出现状态不一致导致数据损坏。\n\n### 使用 Wax 后\n- **极简单文件架构**：Wax 将文档、元数据、全文索引和 Metal 加速的向量索引打包进唯一的 `.wax` 文件，无需配置服务器或管理多个存储引擎，代码量大幅减少。\n- **纯本地隐私安全**：所有数据处理均在 Apple Silicon 芯片上通过 Metal 加速完成，无需联网或 API 密钥，天然满足医疗级数据的本地隐私合规要求。\n- **亚毫秒级极速响应**：得益于针对 M 系列芯片的优化，Wax 实现了约 6ms 的混合检索延迟和 9ms 的冷启动时间，让 AI 助手能实时“回忆”起相关病例，体验丝滑。\n- **原子化数据管理**：医生只需通过 AirDrop 或 iCloud 传输单个 `.wax` 文件即可完成全部知识库的迁移与备份，彻底消除了多文件同步的状态一致性难题。\n\nWax 通过单一文件和高性能本地计算，让开发者能在严格隐私限制下，为 Apple 平台打造出响应迅速且架构轻盈的 AI 记忆层。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fchristopherkarani_Wax_c94d9c3b.png","christopherkarani","Christopher Karani","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fchristopherkarani_99801723.jpg","\"Do not underestimate the power of Tafari. He creeps like a mouse but he has jaws like a lion\" -",null,"chrisbkarani@gmail.com","chris_karani","https:\u002F\u002Fchriskarani.xyz","https:\u002F\u002Fgithub.com\u002Fchristopherkarani",[82,86,90,93,97,101,105],{"name":83,"color":84,"percentage":85},"Swift","#F05138",96.8,{"name":87,"color":88,"percentage":89},"JavaScript","#f1e05a",0.8,{"name":91,"color":92,"percentage":89},"CSS","#663399",{"name":94,"color":95,"percentage":96},"Metal","#8f14e9",0.7,{"name":98,"color":99,"percentage":100},"Shell","#89e051",0.5,{"name":102,"color":103,"percentage":104},"Python","#3572A5",0.3,{"name":106,"color":107,"percentage":108},"C","#555555",0.1,701,36,"2026-04-13T19:46:29","Apache-2.0","macOS, iOS","非必需，但针对 Apple Silicon (M-series) 优化，利用 Metal 加速向量索引 (HNSW)","未说明",{"notes":117,"python":118,"dependencies":119},"该工具是专为 Apple 平台设计的原生 Swift 内存层，不依赖云端或服务器。核心功能封装在单个 .wax 文件中，内部集成了 SQLite FTS5 用于文本搜索和基于 Metal 加速的 HNSW 用于向量搜索。推荐使用 M 系列芯片设备以获得最佳性能（基准测试基于 M3 Max）。不支持 Linux 或 Windows。安装主要通过 Swift Package Manager 或作为 CLI 工具使用，也可通过 MCP 服务器与 AI 编码助手集成。","不适用 (基于 Swift)",[120,121,122],"Swift 5+","SQLite FTS5 (内置)","Metal (内置)",[124,52,13,14,16],"其他",[126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145],"ai-agents","data-science","machine-learning","memory","memory-cache","memory-hacking","on-device-ai","rag","coreml","coreml-framework","metal","rag-pipeline","vector-database","vector-embeddings","vector-search","vectordb","mcp","mcp-server","cli","swift","2026-03-27T02:49:30.150509","2026-04-16T08:14:11.441195",[149,154,159,164,169,174],{"id":150,"question_zh":151,"answer_zh":152,"source_url":153},35292,"为什么在 macOS 沙盒应用（如 SwiftUI App）中运行示例代码会报错 \"enableVectorSearch=true requires an EmbeddingProvider\" 或 \"Operation not permitted\"？","这是因为在沙盒应用中，使用 `URL(fileURLWithPath: \"agent.wax\")` 会尝试将文件写入根目录 `\u002Fagent.wax`，而被操作系统阻止。解决方法是使用沙盒安全的可写路径，例如文档目录。请将初始化代码修改为：\n```swift\nlet url = URL.documentsDirectory.appending(path: \"agent.wax\")\nlet memory = try await Memory(at: url)\n```\n维护者已更新 README 和示例以反映此更改。","https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fissues\u002F34",{"id":155,"question_zh":156,"answer_zh":157,"source_url":158},35293,"升级到 Wax 0.1.18 或更高版本后，构建 SwiftUI 应用时出现 \"Sending value risks causing data races\" 编译错误怎么办？","这是 Xcode 26.4\u002FSwift 6 对并发安全性的严格检查导致的。该问题已在 Wax 标签版本 0.1.20 中修复。补丁移除了 CoreML 输出对象在非池化 Swift 延续路径中的发送操作，从而消除了数据竞争风险。请将依赖版本升级到 0.1.20 或更高版本。","https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fissues\u002F61",{"id":160,"question_zh":161,"answer_zh":162,"source_url":163},35294,"Wax 库是否支持 Linux 或 Android 平台？","是的，Wax Core 现已支持 Linux。由于库主要使用 CryptoKit 而非 Swift-Crypto，因此具备跨平台潜力。维护者确认 WaxCore 已迁移至 Linux，并推荐查看相关项目 Zoni (https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FZoni) 以获取更多跨平台支持信息。","https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fissues\u002F22",{"id":165,"question_zh":166,"answer_zh":167,"source_url":168},35295,"如何在项目中正确使用结构化数据（如 Codable 结构体）进行存储和检索，并确保能获取原始 ID？","虽然可以将结构体编码为 JSON 字符串存储，但直接在元数据中传递 ID 可能不会自动包含在搜索结果的 `context.items` 中。建议的做法是：将 JSON 字符串存入内存，同时将唯一标识符（ID）显式放入 `metadata` 字典。在检索时，虽然返回的是文本块，但你可以通过查询时的上下文关联或后续处理，利用保存时设定的 metadata 键值对来重新关联原始对象。目前最佳实践是将 ID 作为 metadata 存储，并在应用层根据召回的片段特征重建对完整对象的引用。","https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fissues\u002F53",{"id":170,"question_zh":171,"answer_zh":172,"source_url":173},35296,"运行 `swift test` 时遇到 \"no such module 'Testing'\" 或 \"no such module 'XCTest'\" 错误如何解决？","这通常是因为开发环境缺少必要的测试模块或 Swift 版本不匹配。确保你使用的是与项目兼容的最新稳定版 Swift 工具链。如果是克隆仓库后直接测试，请检查是否所有子模块已正确初始化，或者尝试清理构建缓存 (`swift package clean`) 后重新构建。维护者已在相关问题中确认并修复了此类配置缺失问题。","https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fissues\u002F24",{"id":175,"question_zh":176,"answer_zh":177,"source_url":178},35297,"在最新 Swift 版本下构建主分支时出现多个并发违规（concurrency violations）错误，提示 \"sending 'output' risks causing data races\"，该如何解决？","这是由于 Swift 6 严格的并发检查机制引起的，特别是在 `ArcticEmbeddings.swift` 和 `MiniLMEmbeddings.swift` 中将任务隔离的输出传递给延续（continuation）时。该问题与 Issue #61 相同，已在版本 0.1.20 中通过重构 CoreML 输出处理逻辑得到解决。请务必升级 Wax 依赖至 0.1.20 或以上版本，不要直接使用未修复的主分支代码。","https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fissues\u002F58",[180,185,190,194,199,204,209,214,219,224,229,234,239,243,247,252,257],{"id":181,"version":182,"summary_zh":183,"released_at":184},280332,"waxmcp-v0.1.19","## 摘要\n- 改进 MCP 启动、锁处理、语料库搜索以及 CLI 守护进程的可靠性\n- 准备 waxmcp \u002F wax-mcp 版本 0.1.19\n- 添加 Wax Teams 产品和 MVP 规划文档\n\n## 验证\n- swift build --product wax-cli --skip-update --disable-automatic-resolution\n- swift build --product wax-mcp --traits default,MCPServer --skip-update --disable-automatic-resolution\n- swift test --filter WaxCLIMemoryTests --skip-update --disable-automatic-resolution\n- 打包后的 wax-cli vector-health 测试通过\n- 打包后的 wax-cli mcp doctor 测试通过\n- npm publish --dry-run --access public 测试通过\n\n## 备注\n由于该环境的 npm 包权限限制，公共 npm 发布仍被阻止。","2026-03-26T23:56:53",{"id":186,"version":187,"summary_zh":188,"released_at":189},280333,"0.1.19","**完整更新日志**: https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.18...0.1.19","2026-03-20T04:00:52",{"id":191,"version":192,"summary_zh":76,"released_at":193},280334,"0.1.18","2026-03-19T01:00:08",{"id":195,"version":196,"summary_zh":197,"released_at":198},280335,"0.1.17","## 变更内容\n* 修复 FTS5SearchEngine 中强制解包的时间范围验证问题，并由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F43 中添加回归测试。\n* 改进 MiniLM 嵌入错误传播相关 API，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F46 中完成。\n* Claude\u002F生产就绪性审计 dh5 j3，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F48 中执行。\n* 移除不安全的强制解包操作，强化 BinaryDecoder 的类型转换，并由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F44 中添加审计报告和测试。\n* 文档：网站更新、本地化 README 文件、CI 质量门控，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F49 中完成。\n* 功能：Wax v2 — 核心引擎、安全性及新功能，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F50 中实现。\n* 杂项：清理仓库展示并更新 README，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F51 中完成。\n* 修复：加固 MCP 会话和向量检索功能，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F52 中完成。\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.9...0.1.17","2026-03-14T09:56:36",{"id":200,"version":201,"summary_zh":202,"released_at":203},280336,"waxmcp-v0.1.16","后续发布，包含 feat\u002Fwax-v2-improvements 分支上的最新提交，截至 ea59ac89。","2026-03-06T02:35:45",{"id":205,"version":206,"summary_zh":207,"released_at":208},280337,"waxmcp-v0.1.15","最大 mxp 发布","2026-03-05T20:08:33",{"id":210,"version":211,"summary_zh":212,"released_at":213},280338,"0.1.9","## 变更内容\n* 杂项：更新 .gitignore，以排除本地代理和 IDE 配置，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F40 中完成\n* 文档：添加架构可视化，并将二进制文件重命名为 wax-cli\u002Fw…，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F41 中完成\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.8...0.1.9","2026-03-03T04:02:23",{"id":215,"version":216,"summary_zh":217,"released_at":218},280339,"waxmcp-v0.1.11","Wax MCP 发布 v0.1.11。","2026-02-27T00:33:00",{"id":220,"version":221,"summary_zh":222,"released_at":223},280340,"0.1.8","## 变更内容\n* 添加 Claude Code GitHub 工作流，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F19 中完成  \n* 修复 VideoRAG 集成测试的确定性及缩略图预算断言…，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F20 中完成  \n* 代码清理，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F21 中完成  \n* Mcp 功能，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F23 中完成  \n* 为测试目标添加 swift-testing 依赖，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F25 中完成  \n* 重写 README，去除 AI 生成的语气，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F27 中完成  \n* 在非 XCTest 构建工具链上保护 XCTest 集成基准测试，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F29 中完成  \n* 提升 Wax 的可靠性和确定性，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F32 中完成  \n* 修复 WAL 故障处理及确定性召回路径，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F31 中完成  \n* 当未提供嵌入器时自动禁用向量搜索，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F36 中完成  \n* 对 Wax MCP 服务器实现进行深度分析，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F35 中完成  \n* 推送 Wax MCP 发布就绪性改进，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F38 中完成  \n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.7...0.1.8","2026-02-25T05:21:58",{"id":225,"version":226,"summary_zh":227,"released_at":228},280341,"0.1.7","## 变更内容\n* 重构：在函数参数中使用不透明的 `some` 类型替代存在类型 `any`，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F17 中完成\n* 研究 WAL 压缩带来的收益，由 @christopherkarani 在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F18 中完成\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.6...0.1.7","2026-02-17T16:04:54",{"id":230,"version":231,"summary_zh":232,"released_at":233},280342,"0.1.6","## 变更内容\n* 修复2，由@christopherkarani在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F14 中完成\n* 修复13，由@christopherkarani在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F15 中完成\n* 问题0214，由@christopherkarani在 https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F16 中解决\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.5...0.1.6","2026-02-14T01:27:34",{"id":235,"version":236,"summary_zh":237,"released_at":238},280343,"0.1.5","## What's Changed\r\n* modi by @christopherkarani in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F12\r\n* Fix2 by @christopherkarani in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F13\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.4...0.1.5","2026-02-12T02:29:42",{"id":240,"version":241,"summary_zh":76,"released_at":242},280344,"0.1.4","2026-02-10T00:46:53",{"id":244,"version":245,"summary_zh":76,"released_at":246},280345,"0.1.3","2026-02-03T03:47:35",{"id":248,"version":249,"summary_zh":250,"released_at":251},280346,"0.1.2","## What's Changed\r\n* Feature\u002Fhierarchical surrogates by @christopherkarani in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F5\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.1...0.1.2","2026-01-31T18:02:15",{"id":253,"version":254,"summary_zh":255,"released_at":256},280347,"0.1.1","## What's Changed\r\n* Feature\u002Fmetal vector search by @christopherkarani in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F1\r\n* coreml by @christopherkarani in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F2\r\n* feat: Add hierarchical surrogates with intelligent tier selection by @christopherkarani in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F3\r\n* fix by @christopherkarani in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F4\r\n\r\n## New Contributors\r\n* @christopherkarani made their first contribution in https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fpull\u002F1\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcompare\u002F0.1.0...0.1.1","2026-01-31T08:17:01",{"id":258,"version":259,"summary_zh":260,"released_at":261},280348,"0.1.0","**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fchristopherkarani\u002FWax\u002Fcommits\u002F0.1.0","2026-01-21T21:51:59"]