跳到内容

设置指南

设置 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 已发布二进制,尚未提供安装脚本。无需账户、无需管理员权限,存储留在你的机器上。

下载 Linux x86-64

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。

  1. 01

    安装

    curl -fsSL "https://www.whitemagic.dev/install.sh?ref=guide-step" | sh

    Linux x86-64 支持脚本安装;macOS 与 Windows 已发布二进制,尚未提供安装脚本。无需账户、无需管理员权限——二进制会放到 ~/.local/bin。

    安装详情与下载

  2. 02

    验证就绪

    wm grimoire

    检查主机、验证记忆层与发布版本、配置检测到的智能体(加 --write 才会写入)、校准记忆,并演示重启后的连续性。它报告五个独立就绪事实,而不是一个绿灯;--json 供机器读取。

  3. 03

    接入你的客户端

    wm connect --write

    单独运行 wm connect 是预演,会列出每个检测到的客户端与确切改动;--write 应用改动(先做带时间戳的备份),并以端到端连接测试收尾——对真实服务器执行 initialize + tools/list。

  4. 04

    载入你的数据

    wm ingest --source <folder> --dry-run

    把一个装有笔记或会话记录的文件夹读入本地星系。脱敏、跳过策略与可续跑的账本见下方“载入你的数据”。

    载入你的数据

  5. 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。重跑时未变化的文件直接跳过;变化的文件会替换其分块。长时间的导入可以中断后重跑续传,预演则会先展示完整计划。

让 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_PROJECT=<name>,握手中就会标明作用域。

按客户端设置

选择你的客户端。

以下配置均对照各客户端的官方文档核验。如果你的客户端不在列表中,通用 MCP 条目通常可以直接使用。

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

2 · 接入此客户端bash
claude mcp add whitemagic -- wm serve

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

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

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