安装与设置

安装并接入 WhiteMagic。

日常使用请选择稳定的第二代版本，然后验证安装、接入 MCP 客户端并运行首次就绪检查。第三代预览版为可选项，使用独立的二进制目录与存储。

选择发布通道

第二代稳定版 · v9.3.4 · 安装命令固定到此发布版本。

curl -fsSL "https://www.whitemagic.dev/install.sh?ref=install-a" | sh -s -- --version v9.3.4 --dir "$HOME/.local/bin" --ref install-a

无需 sudo · 安装到用户空间

检查安装脚本 ↗·校验码 (SHA-256) ↗·查看你的客户端设置指南 ↓

无需注册账户 · 记忆与会话保留在你的机器上 · 默认无设备外使用遥测

最快路径

让你的 AI 来完成设置。

把一段提示词粘贴给能执行 shell 命令的编程智能体。它会先询问你选择哪个通道，再按操作系统选择对应命令，并回报准确版本与就绪结果。默认是第二代稳定版；只有你明确选择时才安装预览版。

提示词

找到 WhiteMagic MCP 服务器（whitemagic.dev；官方 MCP 注册表 ID：io.github.lbailey94/whitemagic-mcp）。请先询问我选择哪个发布通道；除非我明确选择，否则不要安装实验预览。默认是第二代稳定版。
请按操作系统选择安装命令：
Linux（POSIX shell）：curl -fsSL "https://www.whitemagic.dev/install.sh?ref=ask-ai" | sh -s -- --version v9.3.4 --dir "$HOME/.local/bin" --ref ask-ai
macOS（POSIX shell）：curl -fsSL "https://www.whitemagic.dev/install.sh?ref=ask-ai" | sh -s -- --version v9.3.4 --dir "$HOME/.local/bin" --ref ask-ai
Windows（PowerShell）：& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/lbailey94/whitemagic/v9.3.4/scripts/install.ps1'))) -Version 'v9.3.4' -Dir (Join-Path $env:LOCALAPPDATA 'WhiteMagic\bin') -Ref 'ask-ai'
不要在 PowerShell 中运行 POSIX curl 命令。如果某个平台/通道没有已发布目标，请停止并说明，不要替换成其他二进制。
只有我明确选择第三代实验预览时，才使用当前支持的 Linux 或 Apple Silicon macOS 命令：
Linux：curl -fsSL "https://www.whitemagic.dev/install.sh?ref=ask-ai" | WM_STORE="$HOME/.local/share/whitemagic/gen3-preview" sh -s -- --version v10.3 --dir "$HOME/.local/bin/whitemagic-gen3" --ref ask-ai --no-path
macOS：curl -fsSL "https://www.whitemagic.dev/install.sh?ref=ask-ai" | WM_STORE="$HOME/.local/share/whitemagic/gen3-preview" sh -s -- --version v10.3 --dir "$HOME/.local/bin/whitemagic-gen3" --ref ask-ai --no-path
Gen 3 安装到 $HOME/.local/bin/whitemagic-gen3 并使用 --no-path，另用 $HOME/.local/share/whitemagic/gen3-preview 作为独立存储。当前通道记录中没有 Windows 或 Intel Mac 目标。
下方编号的就绪检查与客户端配置流程仅适用于 Gen 2。请勿对 Gen 3 运行 Gen 2 的 `wm grimoire`、`wm connect`、`wm setup`、备份或更新流程。配置预览版 MCP 服务器前，请查看该已安装二进制自身的 `wm --help` 与 `wm serve --help`；使用其完整绝对路径，并在 `serve` 前传入独立存储路径。MCP 客户端不会展开 JSON 中的 shell 变量：请把示例主目录前缀替换成已展开的绝对路径。配置形状示例：command "/absolute/home/.local/bin/whitemagic-gen3/wm"，args ["--store", "/absolute/home/.local/share/whitemagic/gen3-preview", "serve"]。写入前先向我展示拟议客户端配置，仅在我批准后应用改动，保存后重启客户端。
对稳定版 Gen 2，先运行 `wm --version`，再按下方稳定版就绪步骤操作。请报告选择的世代与版本、诊断结果；不要分享私有记忆内容。

哪些客户端可以这样做

·在大多数能执行 shell 命令的客户端里都可用——Claude Code、Codex CLI、opencode 以及类似的终端型智能体可以完整执行这条提示词。
·能浏览官方 MCP 注册表的客户端，可以直接搜索 io.github.lbailey94/whitemagic-mcp 并添加，无需 shell 步骤。
·偏爱终端路径的话，一次配置一个客户端：wm setup <client>（claude · cursor · windsurf · codex · opencode）先展示改动，加 --write 应用并保留带时间戳的备份。
·完全没有终端？从下方的客户端标签页手动粘贴对应配置——通用 mcpServers 条目在多数客户端都能用。
·不想安装二进制文件？npm 启动器 npx -y whitemagic-mcp@9.3.4 serve 运行的是稳定版 Gen 2 服务器。

下方的各客户端标签页仍是手动配置的兜底方案；若客户端自带添加命令，那一条命令同样可用（Claude Code：claude mcp add whitemagic -- wm serve）。

首次运行

首次运行，按步骤来。

以下步骤仅适用于第二代稳定版：确认版本、运行就绪检查、审阅客户端改动，再测试会话。导入与维护是下方的可选章节。请勿将这套第二代流程用于第三代实验预览。

01
确认稳定版二进制
wm --version
确认此命令报告的是第二代稳定版 v9.3.4。本流程后续就绪检查与维护命令均针对 PATH 中的稳定版二进制。如果你选择了 Gen 3，请在此停止，并仅使用下方独立的预览服务器说明。
02
验证就绪
wm grimoire
在第二代稳定版中，此命令会检查主机、记忆层与发布版本，预览检测到的客户端配置，校准记忆并演示重启连续性。请查看各项就绪结果；只有明确添加 --write 才会应用客户端配置改动。
03
接入你的客户端
wm connect
这是预演：只列出检测到的客户端与拟议改动，不会写入配置。请先审阅显示的路径与二进制。只有你确认要应用这些改动后，才使用 wm connect --write 重新运行；它会先创建带时间戳的备份。
04
开启会话，然后恢复
wm session start --title "first run"
接入客户端不会自动保存每段对话。需要留存时，请用 WhiteMagic 记忆或会话工具明确记录一项决定或对话轮次；数据保存在本机。开启新会话并检索该条目，以确认连续性。wm quickstart 会在隔离存储上演示停止/重启；wm selftest 在一次性存储上运行本地诊断，不是完整的不变量认证。第三代预览版的 wm selftest 不同：它是针对该预览二进制的宿主机健康诊断（见下方预览章节）。

使用第三代实验预览版

这是独立的服务器路径，不是 Gen 2 的就绪检查或维护流程。请先查看此预览二进制自身的帮助信息。它有独立二进制目录（$HOME/.local/bin/whitemagic-gen3）与独立存储（$HOME/.local/share/whitemagic/gen3-preview），不会替换 PATH 中的稳定版命令。请勿让它指向 Gen 2 存储。当前发布记录没有 Windows 或 Intel Mac 预览产物。macOS 上的源码构建或源码测试结果不等于已验证发布安装包。在 Linux 上，该预览版自身的 wm selftest 在持久性探测之外还做宿主机健康检查：磁盘余量、可用内存、内核 PSI memory/io 压力、swap/zram 饱和、crash-loop 的 systemd 用户单元与内存占用最高的进程。宿主机检查为 critical 时 --strict 以非零码退出；--json 在持久性结果之外附加 host_status 与 host_health。它是本地诊断，不是完整的不变量认证。

仅在支持的预览目标上运行此版本检查：

"/absolute/home/.local/bin/whitemagic-gen3/wm" --version

继续前先检查该二进制及其服务器参数：

"/absolute/home/.local/bin/whitemagic-gen3/wm" --help
"/absolute/home/.local/bin/whitemagic-gen3/wm" serve --help

仅供 Linux 与 Apple Silicon macOS 使用的 MCP 配置形状（示例占位路径；保存前必须替换为真实绝对路径。不要把 $HOME 原样写入客户端 JSON）：

"command": "/absolute/home/.local/bin/whitemagic-gen3/wm",
"args": ["--store", "/absolute/home/.local/share/whitemagic/gen3-preview", "serve"]

就绪状态，不靠单一绿灯

wm grimoire 报告五个独立事实，而不是一个布尔值：记忆层就绪、智能体已接入、连续性已验证、语义召回可用、完全激活。“记忆层可用”与“你已连上它”是不同的结论，因此分开呈现。

客户端配置 ↓查看已捕获的重启示例 →不想安装？托管评估通道 →

稳定版 Gen 2 客户端设置

选择你的客户端。

以下客户端选项卡用于配置稳定的第二代服务器。预览版 MCP 配置是独立的；请使用上文隔离的二进制与存储说明。

把 WhiteMagic 注册为本地 MCP 服务器。此后的会话可以从上次中断处继续——文件检查点、决定与下一步都能跨重启保留。

2 · 接入此客户端bash

claude mcp add whitemagic -- wm serve

在终端运行一次即可；Claude Code 会替你保存这条服务器条目。 Claude Code MCP 文档 ↗

或让 WhiteMagic 自动写入：运行 wm setup claude 先查看具体改动；加上 --write 才会应用（带时间戳备份）。JSONC/TOML 配置仅打印，不写入。

WhiteMagic 作为本地 stdio MCP 服务器运行。Cursor 就能回忆此前的会话、决定与项目状态，无需重新粘贴上下文。

2 · 接入此客户端json

{
  "mcpServers": {
    "whitemagic": {
      "command": "wm",
      "args": ["serve"]
    }
  }
}

项目配置在 .cursor/mcp.json，全局配置在 ~/.cursor/mcp.json（Cursor 设置 → Features → MCP 也会编辑该文件）。 Cursor MCP 文档 ↗

或让 WhiteMagic 自动写入：运行 wm setup cursor 先查看具体改动；加上 --write 才会应用（带时间戳备份）。JSONC/TOML 配置仅打印，不写入。

Codex 在 ~/.codex/config.toml 中保存 MCP 服务器。把 WhiteMagic 添加为 stdio 服务器，会话就能带着之前的状态恢复。

2 · 接入此客户端toml

[mcp_servers.whitemagic]
command = "wm"
args = ["serve"]

~/.codex/config.toml（项目级：受信任项目中的 .codex/config.toml）。 Codex CLI MCP 文档 ↗

或让 WhiteMagic 自动写入：运行 wm setup codex 先查看具体改动；加上 --write 才会应用（带时间戳备份）。JSONC/TOML 配置仅打印，不写入。

Devin Desktop 是更名后的 Windsurf 编辑器。它从 mcp_config.json 读取 MCP 服务器——添加一次 WhiteMagic，智能体就能在本地回忆此前的会话。

2 · 接入此客户端json

{
  "mcpServers": {
    "whitemagic": {
      "command": "wm",
      "args": ["serve"]
    }
  }
}

~/.codeium/mcp_config.json（旧版 Cascade 配置 ~/.codeium/windsurf/mcp_config.json 仍会被读取），或设置 → Cascade → MCP Servers。 Devin Desktop MCP 文档 ↗

或让 WhiteMagic 自动写入：运行 wm setup windsurf 先查看具体改动；加上 --write 才会应用（带时间戳备份）。JSONC/TOML 配置仅打印，不写入。

Antigravity 从全局 mcp_config.json 读取 MCP 服务器。添加一次 WhiteMagic，智能体就能跨会话回忆此前的工作——全程在本机。

2 · 接入此客户端json

{
  "mcpServers": {
    "whitemagic": {
      "command": "wm",
      "args": ["serve"]
    }
  }
}

~/.gemini/config/mcp_config.json（全局；适用于所有会话）。 Antigravity MCP 文档 ↗

VS Code 在 mcp.json 中配置 MCP 服务器。把 WhiteMagic 添加为 stdio 服务器，智能体即可回忆此前的会话。

2 · 接入此客户端json

{
  "servers": {
    "whitemagic": {
      "type": "stdio",
      "command": "wm",
      "args": ["serve"]
    }
  }
}

工作区中的 .vscode/mcp.json，或用户级 MCP 配置（命令面板 → MCP: Open User Configuration）。 VS Code MCP 文档 ↗

opencode 在 opencode.json 中接收 MCP 服务器。WhiteMagic 通过 stdio 在本地运行，并在多次 opencode 运行之间保持会话连续性。

2 · 接入此客户端json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "whitemagic": {
      "type": "local",
      "command": ["wm", "serve"],
      "enabled": true
    }
  }
}

opencode.json（项目）或 ~/.config/opencode/opencode.json（全局），位于 mcp 键下。 opencode MCP 文档 ↗

或让 WhiteMagic 自动写入：运行 wm setup opencode 先查看具体改动；加上 --write 才会应用（带时间戳备份）。JSONC/TOML 配置仅打印，不写入。

把 WhiteMagic 加入桌面应用的 MCP 服务器。对话就能接着此前的脉络与已记住的上下文继续。

2 · 接入此客户端json

{
  "mcpServers": {
    "whitemagic": {
      "command": "wm",
      "args": ["serve"]
    }
  }
}

claude_desktop_config.json – macOS: ~/Library/Application Support/Claude/；Linux: ~/.config/Claude/；Windows: %APPDATA%\Claude\。 Claude Desktop MCP 文档 ↗

WhiteMagic 完全与客户端无关：只要支持 MCP，就能使用。客户端运行 wm serve 即可获得记忆工具；记忆存放在你的磁盘上，切换编辑器或模型都不会丢失历史。大多数客户端接受下面的 mcpServers 条目；上方标签页列出了各客户端读取的确切文件。

2 · 接入此客户端json

{
  "mcpServers": {
    "whitemagic": {
      "command": "wm",
      "args": ["serve"]
    }
  }
}

你的客户端存放 MCP 服务器条目的位置——只要接受 mcpServers 结构，此条目即可直接使用。任意 MCP 客户端 MCP 文档 ↗

运行一次，然后问你的客户端它记得什么。

在你的客户端里可用，在你的系统上能跑。

客户端支持是文档列表，不是集成矩阵：每个条目都链接到按该客户端配置结构核对过的设置路径。下方平台安装门槛状态由各通道的发布清单标记，并不证明已在你的主机上完成新安装。

客户端

平台

Linux arm64: Gen 2 稳定 v9.3.4: 发布清单标记安装门槛
Linux arm64 musl: Gen 2 稳定 v9.3.4: 已发布产物 · 清单未标记安装门槛
Linux x86-64: Gen 2 稳定 v9.3.4: 发布清单标记安装门槛
Linux x86-64 musl: Gen 2 稳定 v9.3.4: 已发布产物 · 清单未标记安装门槛
macOS arm64: Gen 2 稳定 v9.3.4: 发布清单标记安装门槛
macOS x86-64: Gen 2 稳定 v9.3.4: 发布清单标记安装门槛
Windows x86-64: Gen 2 稳定 v9.3.4: 发布清单标记安装门槛
Linux arm64: Gen 3 预览 v10.3: 发布清单标记安装门槛
Linux x86-64: Gen 3 预览 v10.3: 发布清单标记安装门槛
macOS arm64: Gen 3 预览 v10.3: 发布清单标记安装门槛

Gen 3 预览版没有 Windows 或 Intel macOS 发布产物；第二代稳定版仍提供这些目标。

故障排查

先做安全检查。

这些检查用于查看第二代稳定版安装，不会应用配置改动。如果你选择了第三代，请仅使用上方独立的服务器说明与预览版自身帮助信息。

如果 shell 找不到 wm

POSIX shell：command -v wm · PowerShell：Get-Command wm -ErrorAction SilentlyContinue

版本不对或找不到命令

找不到命令，或客户端启动的世代与所选版本不一致。

wm --version

此命令显示 PATH 中找到的二进制版本。稳定命令应报告 Gen 2。Gen 3 安装在独立目录中，按设计不会加入 PATH。

在“安装”中选择对应的操作系统标签与通道。安装后请打开新的终端。不要为解决 PATH 不一致而删除另一世代。

架构不匹配或目标不受支持

二进制在显示版本前就报告可执行格式或架构错误。

uname -m

此命令仅用于 Linux/macOS 的 POSIX shell，请将结果与所选发布资产核对。Apple Silicon 上的 Rosetta 终端可能报告 x86_64，请使用原生 arm64 终端。Windows PowerShell 请查看 $env:PROCESSOR_ARCHITECTURE；它描述当前进程环境，可能反映模拟环境。

请选择与实际主机及通道匹配的已发布资产，或让安装器选择。当前 Gen 3 没有 Windows 或 Intel Mac 目标。请保留存储与另一世代；替换不匹配的可执行文件不需要删除数据。

客户端未启动所选稳定服务器

客户端无法连接，或 MCP 配置里显示的是旧版/其他二进制。

wm connect

在 Gen 2 中此命令是预演：列出检测到的客户端与拟议配置改动，不会写入。请将显示的二进制与配置路径和上方客户端标签核对。

先审阅拟议改动。只更新你确认要修改的客户端，并按其文档配置流程或显式使用 --write。保存后重启该客户端。Gen 3 必须手动配置其绝对二进制路径与独立存储；不要使用 Gen 2 connect/setup。

服务器启动或 stdio 错误

配置已保存，但客户端仍无法启动或初始化本地服务器。

wm serve --help

此命令查看稳定版二进制的服务器选项，不会启动服务器。客户端必须用预期的二进制和存储路径，通过 stdio 调用 wm serve；不应将 connect 或 grimoire 作为服务器调用。

保存配置后重启客户端，并查看其 MCP 启动日志。确认可执行文件存在，显式存储路径对应预期本地存储。stdio 服务器等待协议输入属于正常行为；诊断信息应与协议流分开。

就绪检查或本地存储告警

稳定版首次运行报告或客户端测试提示主机、存储、索引或发布版本问题。

wm doctor

在第二代稳定版中，此命令诊断当前选定/默认存储。除非明确请求修复选项，否则不会执行修复。

保留诊断输出，并确认客户端使用哪个存储。不要一开始就运行修复或补全 schema 的选项。如果报告数据完整性问题，请先制作并核验备份，再寻求帮助后进行修复。

导入中断或将导入意外文件

预演列出意外文件，或先前的文件夹导入中途停止。

wm ingest --source "/path/to/folder" --galaxy "example-name" --redact --dry-run

请将引号内的示例文件夹与星系名称替换成实际来源和目标。此命令预览它们，不会写入。移除 --dry-run 前请审阅列出的路径、跳过项与目标位置。

如果先前导入中断，已记录的账本允许对未变化文件重跑同一命令以续传。请先再次确认来源与目标；不要删除账本或更换目标来强制重试。

wm report 会在本机写出脱敏支持包，不会传输任何内容。分享前请自行审阅并移除私有信息；不要包含 bearer 凭据、加密密钥或私有记忆文本。

载入你的数据

把笔记、文档与会话记录带进来。

以下导入说明使用第二代稳定版 wm ingest 命令：它会把文件夹读入本机磁盘上的星系——分块、记入账本、可续跑。不上传任何内容；文件始终留在你的机器上。预览版请查看其自身的独立帮助信息。

wm ingest 从你的磁盘读取文件，分块后带来源标签写入存储。它是幂等的：<store>/ingest_ledger.jsonl 记录每个文件的 SHA-256，未变化的文件在重跑时会被跳过；中断的导入只要重跑同一条命令即可续传。

先预演

wm ingest --source ~/Notes --galaxy research --redact --dry-run

只报告将导入、将跳过（及原因）的内容，不写入任何数据，也不创建存储。

再正式导入

wm ingest --source ~/Notes --galaxy research --redact

分块内容带来源标签写入 research 星系；凭据形态的内容在入库前已被替换。继续之前运行 wm status，检查记忆数量。

ingest 参数

--source <dir>: 要遍历的文件夹（必填）。遍历是递归的，并跳过构建/版本控制目录（.git、node_modules、target、.next 等）。
--galaxy <name>: 目标星系。默认：文档进 research，会话记录进 sessions。
--redact: 脱敏凭据形态的内容（PEM 密钥、带前缀的令牌、赋值语句），改为导入该文件而不是跳过。
--dry-run: 只报告，不写入，也不创建存储。
--limit <n>: 只处理遍历顺序中的前 N 个文件。
--include-credential-files: 导入文件名疑似凭据的文件（如 secrets.txt）；必须与 --redact 同时使用，内容入库前会被脱敏。
--store <path> · --wait <n>: 指向指定存储；存储被占用（服务器在线）时最多等待 N 秒，超时才失败。

默认跳过什么

文件名命中凭据特征的文件永不导入：.env*、.pem、.key、.p12/.pfx/.crt、id_rsa、id_ed25519、id_ecdsa、credentials、secrets、password、passwd、token。只读取 md、markdown、txt、jsonl、ndjson、llms 文件；二进制、媒体、压缩包、PDF/Office 文档、锁/日志文件与构建产物会被跳过，超过 64 MB 的文件会说明原因后跳过。--include-credential-files 是显式覆盖开关，并且必须绑定 --redact——绝不是生密钥的通道。

记账，可续跑

每个已导入文件的 SHA-256 记录在 <store>/ingest_ledger.jsonl。重跑时未变化的文件直接跳过；变化的文件会替换其分块。长时间的导入可以中断后重跑续传，预演则会先展示完整计划。

让 AI 来导入

用 `wm ingest --source ~/Notes --galaxy research --redact` 把 ~/Notes 递归导入 research 星系，并脱敏凭据形态的内容。先 --dry-run 预演，再正式执行，然后汇报已导入与已跳过的文件。所有内容都留在本机。

不止文件夹

·直接写入记忆——通过 wm 元工具用 memory.create 写一条、memory.batch_create 批量写入、session.record 记录对话轮次。跨存储导入时用 project:<name> 打标签，保持来源可追溯。
·迁移星系——galaxy.export 把一个星系导出为 JSON；galaxy.import 将其导入另一个存储或另一台机器。
·节省台账——`wm ledger` 报告哪些内容没有进入模型上下文：连续性与召回中存储与注入的字节数，以及本地操作构成。仅在本机运行；`--json` 供机器读取，`--calibrate` 设置每存储的字节/token 除数。
·按项目分存储——每个项目一个存储。让项目的客户端配置指向自己的目录，并设置 WM_PROJECT=<name>，握手中就会标明作用域。

日常维护

仅适用于第二代稳定版。第三代预览版有独立 CLI 与存储；以下备份与更新命令不是预览版说明。

wm status面向人的健康摘要：存储、数量、索引、备份与更新状态。
wm stats资源占用与脑波状态；--week 显示最近七个每日汇总。
wm report写出脱敏的本地支持包（report.json + README.txt）。只读操作；不会外传任何内容。
wm backup把完整存储（LMDB + 索引 + 全部 JSON 状态）复制到带时间戳的目录，并写入 SHA256SUMS 清单。请先停止服务器；用 wm restore --backup <dir> 恢复。
wm update check检查是否有更新的签名版本——只通知，不安装。

存储默认位于 ~/.local/share/whitemagic；--store <path> 或按项目的客户端配置可让服务器指向其他存储。每个项目一个存储，并用 WM_PROJECT=<name> 在 MCP 握手中标明项目，智能体在执行前即可确认自己的作用域。

卸载：删除 wm 二进制与存储目录。这只涉及这两个位置——备份、导出、副本与其他项目存储依然存在，删除也不等于安全擦除。请先清点所有副本。

你的磁盘，你的规则。

存储默认位于你的主目录下（初始化后不足 1 MB；LMDB 映射是稀疏的）。记忆、提示词与会话内容不会传出设备，默认也不发送任何设备外使用遥测。本地诊断遥测可能记录在设备上用于自我观察；唯一的共享路径是可选的安装漏斗报告，默认关闭、需明确选择加入（`wm telemetry enable --share` 会先展示完整载荷；标识符可用 reset-id 轮换）。版本更新检查仅在执行时访问 GitHub，离线亦可用。本地存储默认不加密；删除一个存储目录不会移除备份、导出、副本或其他项目存储。完整说明见条款与隐私。

安装并接入 WhiteMagic。

让你的 AI 来完成设置。

首次运行，按步骤来。

确认稳定版二进制

验证就绪

接入你的客户端

开启会话，然后恢复

使用第三代实验预览版

选择你的客户端。

在你的客户端里可用，在你的系统上能跑。

先做安全检查。

如果 shell 找不到 wm

版本不对或找不到命令

架构不匹配或目标不受支持

客户端未启动所选稳定服务器

服务器启动或 stdio 错误

就绪检查或本地存储告警

导入中断或将导入意外文件

把笔记、文档与会话记录带进来。

日常维护

你的磁盘，你的规则。