内容
# 塞拉夫记忆 MCP
一个独立的 **MCP 服务器**，为 AI 助手（Claude Code 或任何 MCP 客户端）提供持久的、自我组织的记忆，支持 **SERAPH** 几何知识底层 — 通过其 **C ABI** 与引擎通信，并通过规范的 [`seraph`](https://github.com/Tree-D-Interactive-LLC/seraph) 安全包装器 crate。不需要 Python 运行时，不需要 PyO3。
一个全局存储，引擎自身的设备编码器，以及一套精选的底层工具：*记住 / 回忆*，推理 **链**，三群体 **邻域**，**矛盾** 检测，**血统** / 来源，**扭曲** 导航，声明的 **类型关系**，以及诊断。
## 工具
| 分组 | 工具 |
|-------|-------|
| 编写 | `remember`，`remember_batch`，`add_seed`，`promote_frame` |
| 回忆 | `recall`，`get_frame`，`eigenframes_list` |
| 链 | `chain`，`chain_to`，`chain_between` |
| 上下文 / 来源 | `neighborhood`，`lineage`，`evolution` |
| 扭曲（导航） | `recall_with_warp`，`warp_chain_to`，`warp_chain_between`，`warp_seed_margin`，`warp_steerability`，`warp_calibration` |
| 声明结构 | `declare_relation`，`list_relations`，`assert_relation`，`retract_relation`，`structural_neighbors` |
| 诊断 | `stats`，`contradictions`，`density`，`region_health`，`drift_report`，`verify` |
**扭曲注意：** 在使用命名幅度（`routing`，`saturation`，...）之前，请每会话运行一次 `warp_calibration` — 默认值假设为 1024-d，在 384-d 默认编码器上是错误的。请保持 `profile=bounded`。
## 需求
- **Windows x86_64**，配备 **MSVC 工具链** (`x86_64-pc-windows-msvc`)。引擎自带 MSVC 导入库，因此 GNU 工具链无法链接。
- **Rust**（稳定版）和网络访问（在首次构建时，请参见下文）。
- **SERAPH 许可证**，位于 `%APPDATA%\SERAPH\license.key`，仅在创建新存储时需要 — 使用 `seraph license activate` 激活一次（与 pip 软件包使用的相同许可证）。打开/读取现有存储不需要许可证。
## 构建
```powershell
cargo build --release
```
`build.rs` 会自行获取引擎 — 无需托管二进制文件，无需源代码访问：
1. 如果设置了 `SERAPH_LIB_DIR`，则在该目录中链接 `seraph.dll` + `seraph.dll.lib`（用于离线构建或未发布的引擎）。
2. 否则，它会查询 [`Tree-D-Interactive-LLC/seraph`](https://github.com/Tree-D-Interactive-LLC/seraph) 的 **最新 GitHub 版本**，下载自包含的 candle-GPU FFI 构建（`*-ffi-windows-x86_64-gpu.zip`），并在 `target/` 下缓存，键名为发布标签。CUDA 在运行时通过驱动程序加载，自动 fallback 到 CPU — 构建具有零原生 GPU 依赖项。
安全的 Rust 接口（`seraph` crate）从同一个引擎存储库中作为 **git 依赖项** 拉取，因此绑定层不能与引擎不同步。
> **链接注意：** 如果构建失败并出现 `link.exe` 错误，则 Git 的 `C:\Program Files\Git\usr\bin\link.exe` 正在遮蔽 MSVC 链接器 — 从 *Developer PowerShell for VS* 构建，或从 `PATH` 中删除 Git `usr\bin` 条目。
服务器二进制文件是 `target\release\seraph-memory-rs.exe`，`seraph.dll` 复制到其旁边 — 如果移动二进制文件，请保持两者在一起。
## 存储位置
按以下顺序解析：
1. `--store <path>` 参数
2. `SERAPH_MEMORY_STORE` 环境变量
3. 默认值： `%APPDATA%\seraph-memory\memory.sfg`
缺少的存储会使用默认模型 **自动创建** `BAAI/bge-small-en-v1.5`（384-d），这需要如上所述的许可证。
## 注册到 Claude Code（用户范围）
将 MCP 注册指向已构建的可执行文件：
```powershell
claude mcp add seraph-memory -s user -- C:\path\to\seraph-memory-rs.exe
```
或手动将其添加到用户 MCP 配置文件（`~/.claude.json`）：
```json
{
"mcpServers": {
"seraph-memory": {
"command": "C:\\path\\to\\seraph-memory-rs.exe",
"env": { "SERAPH_MEMORY_STORE": "C:\\Users\\you\\AppData\\Roaming\\seraph-memory\\memory.sfg" }
}
}
}
```
用户范围使工具在 **每个** 项目中都可用。
## 进程模型 — 跨会话共享一个存储
SERAPH 按设计是 **单写入器**，但 Claude Code 启动一个_stdio 服务器进程/会话。为了避免 N 个进程每个都打开同一个 `.sfg`，服务器运行一个 **共享守护进程** 模型（Windows）：
- 启动的第一个会话会启动一个 **分离的守护进程**，该进程打开存储一次（唯一的写入器，预热编码器，一个共享的内存状态）。
- 包括第一个会话在内的每个会话进程都会作为一个薄 **客户端** 运行，将其 stdio 中继到守护进程，通过命名管道 (`\\.\pipe\seraph-memory-<store-hash>`)。守护进程通过每个连接提供相同的工具集，序列化所有访问到一个引擎互斥锁上。
- 守护进程在 **空闲期间** 后自行退出（无连接会话），默认为 **3600s** — 使用 `SERAPH_MEMORY_IDLE_SECS` 覆盖。
- 守护进程日志记录到 `%APPDATA%\seraph-memory\daemon.log`（客户端日志记录到 stderr）。
- 如果守护进程无法访问或启动，会话 **fallback** 到进程内打开存储（降级 — 无跨会话共享）。
不需要配置更改：已注册的命令是相同的 exe；它在启动时决定客户端还是守护进程。
## 许可证
此存储库中的 MCP 服务器根据 **MIT** 许可证（参见 [LICENSE](LICENSE)）许可 — 使用它，派生它，构建于它。
下载并链接的 **SERAPH 引擎** (`seraph.dll`) 是一个单独的专有组件，位于 SERAPH 软件许可协议下；MIT 仅涵盖此服务器代码，不涵盖引擎二进制文件。
