设置指南
设置 WhiteMagic。
安装一次,然后交给你的 AI 接入——或者按首次运行路径与各客户端配置自行完成。记忆与会话保留在本机;服务器通过 stdio 提供本地 MCP。
最快路径
让你的 AI 来完成设置。
把一段提示词粘贴给任何能执行 shell 命令的编程智能体:它会把 WhiteMagic 装好、接入你的 MCP 客户端,并把就绪检查结果回报给你。
找到 WhiteMagic MCP 服务器(whitemagic.dev;官方 MCP 注册表 ID:io.github.lbailey94/whitemagic-mcp)。
用一行安装脚本安装:
curl -fsSL "https://www.whitemagic.dev/install.sh?ref=ask-ai-zh" | sh
然后运行 `wm connect --write` 接入我的客户端,并用 `wm grimoire` 验证。
请汇报就绪检查结果与一条测试记忆。哪些客户端可以这样做
- ·在大多数能执行 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 whitemagic-mcp serve 运行的是同一个服务器。
下方的各客户端标签页仍是手动配置的兜底方案;若客户端自带添加命令,那一条命令同样可用(Claude Code:claude mcp add whitemagic -- wm serve)。
安装
安装 WhiteMagic。
Linux x86-64 一行装好;macOS 与 Windows 已发布二进制,尚未提供安装脚本。无需账户、无需管理员权限,存储留在你的机器上。
curl -fsSL "https://www.whitemagic.dev/install.sh?ref=guide-zh-a" | sh
无需 sudo · 纯用户空间执行 · 2–4 秒 · 兼容 glibc 与 musl
v9.2.1 · 发布于 2026年9月20日 · 15 个 crate · npm · Docker · MCP 注册表 · MIT
无需注册账户 · 记忆与会话保留在你的机器上 · 默认无设备外使用遥测
首次运行
首次运行,按步骤来。
安装 → 验证就绪 → 接入客户端 → 载入数据 → 第一次会话。只有需要真正写入时才加 --write。
- 01
安装
curl -fsSL "https://www.whitemagic.dev/install.sh?ref=guide-step" | shLinux x86-64 支持脚本安装;macOS 与 Windows 已发布二进制,尚未提供安装脚本。无需账户、无需管理员权限——二进制会放到 ~/.local/bin。
- 02
验证就绪
wm grimoire检查主机、验证记忆层与发布版本、配置检测到的智能体(加 --write 才会写入)、校准记忆,并演示重启后的连续性。它报告五个独立就绪事实,而不是一个绿灯;--json 供机器读取。
- 03
接入你的客户端
wm connect --write单独运行 wm connect 是预演,会列出每个检测到的客户端与确切改动;--write 应用改动(先做带时间戳的备份),并以端到端连接测试收尾——对真实服务器执行 initialize + tools/list。
- 04
载入你的数据
wm ingest --source <folder> --dry-run把一个装有笔记或会话记录的文件夹读入本地星系。脱敏、跳过策略与可续跑的账本见下方“载入你的数据”。
- 05
开启会话,然后恢复
wm session start --title "first run"工作时记录决定,在下一个会话里找回——可以通过 MCP(session.start · session.record · session.continuity),也可以直接用终端(wm session start · record · continuity)。wm quickstart 会在隔离的存储上演示完整的停止/重启;wm selftest 则在一次性存储上运行端到端不变量检查。
日常维护
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 二进制与存储目录。这只涉及这两个位置——备份、导出、副本与其他项目存储依然存在,删除也不等于安全擦除。请先清点所有副本。
载入你的数据
把笔记、文档与会话记录带进来。
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 星系;凭据形态的内容在入库前已被替换。
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。重跑时未变化的文件直接跳过;变化的文件会替换其分块。长时间的导入可以中断后重跑续传,预演则会先展示完整计划。
用 `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_PROJECT=<name>,握手中就会标明作用域。
按客户端设置
选择你的客户端。
以下配置均对照各客户端的官方文档核验。如果你的客户端不在列表中,通用 MCP 条目通常可以直接使用。
把 WhiteMagic 注册为本地 MCP 服务器。此后的会话可以从上次中断处继续——文件检查点、决定与下一步都能跨重启保留。
claude mcp add whitemagic -- wm serve在终端运行一次即可;Claude Code 会替你保存这条服务器条目。 Claude Code MCP 文档 ↗
或让 WhiteMagic 自动写入:运行 wm setup claude 先查看具体改动;加上 --write 才会应用(带时间戳备份)。JSONC/TOML 配置仅打印,不写入。
WhiteMagic 作为本地 stdio MCP 服务器运行。Cursor 就能回忆此前的会话、决定与项目状态,无需重新粘贴上下文。
{
"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 服务器,会话就能带着之前的状态恢复。
[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,智能体就能在本地回忆此前的会话。
{
"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,智能体就能跨会话回忆此前的工作——全程在本机。
{
"mcpServers": {
"whitemagic": {
"command": "wm",
"args": ["serve"]
}
}
}~/.gemini/config/mcp_config.json(全局;适用于所有会话)。 Antigravity MCP 文档 ↗
VS Code 在 mcp.json 中配置 MCP 服务器。把 WhiteMagic 添加为 stdio 服务器,智能体即可回忆此前的会话。
{
"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 运行之间保持会话连续性。
{
"$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 服务器。对话就能接着此前的脉络与已记住的上下文继续。
{
"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 条目;上方标签页列出了各客户端读取的确切文件。
{
"mcpServers": {
"whitemagic": {
"command": "wm",
"args": ["serve"]
}
}
}你的客户端存放 MCP 服务器条目的位置——只要接受 mcpServers 结构,此条目即可直接使用。 Any MCP client MCP 文档 ↗
运行一次,然后问你的客户端它记得什么。