内容
-memory-rs
[](https://github.com/DioNanos/mcp-memory-rs/actions/workflows/ci.yml)
[](https://github.com/DioNanos/mcp-memory-rs/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.rust-lang.org)
[](#本地优先的MCP，纯Rust实现。持久化、版本化、可查询的AI代理使用——由，而非平台。
状态存储上，以纯JSON类别基础，支持SQLite（5）。每次写入都会版本化和备份。一组设备通过可选的HTTP端点，使用Merkle manifest和乐观并发性进行同步。默认模式下，无需云账户，无需嵌入式服务，无需网络依赖。
## 为什么
与供应商绑定的代理内存会在供应商会话结束时丢失。该服务器将代理的长期状态——身份、项目、基础设施笔记、每个设备的workflow——您可以读取、grep、diff和备份的文件中。任何MCP客户端（Claude Code、Codex或任何支持MCP stdio的客户端）都可以访问；更换模型不会导致状态丢失。
设计选择：
- **本地优先**：stdio服务器完全离线，支持本地存储。同步是一个独立的显式步骤——而非隐藏的依赖。
存储**：每个类别一个JSON文件，加上一个SQLite索引。数据库可以从文件中重建；文件是事实来源。
-版本化**：每次写入都会保留历史记录；删除操作会先创建备份。`memory_history`和`memory_compact`管理历史记录的尾部 **并发安全的写入**：`expected_hash`将并发代理之间的冲突转换为显式冲突。
- **核心零ML**：全文搜索使用SQLite FTS525；`memory_search`添加可选的TF混合搜索。无需模型下载。
> **配对**：语料库*召分段文档、BM原始文本注入），配套服务器 [mcp-msa-rs](https://github.com/DioNanos/ml-msa-rs)。该服务器持有精选的代理状态；另一个服务器持有可查询的语料库。
```mermaid
flowchart LR
A["<br/>(任意M"]
A -->状态<br/>读取 / 同步"| M["mcp-memory-rs<br/><笔记本</i>"]
A -->|"语料库召索引 / 搜索"| V["mcp-msa-rs<br/><库</i>"]
--- D1[("<br/>SQLite FTS5")]
V --- D2[("tantivy BM25<br/>集合")]
```
## 安装
**预编译二进制文件**（推荐）—— 从 [最新发布](https://github.com/DioNanos/mcp-memory-rs/releases/latest) 下载适用于您平台的存档，解压后，将MCP客户端指向二进制文件：
```bash
tar xzf mcp-memory-rs-x86_64-unknown-linux-gnu.tar.gz
install -m755 mcp-memory-rs-*/mcp-memory-rs ~/.local/bin/
```
预编译目标（Linux + Android）：`x64-unknown-linux-gnu`x86_64-unknown-linux-musl`，`aarch64-unknown-linux-gnu`，`aarch64-unknown-linux-musl`（边缘 / ARM / Termux），`aarch64-linux-android`。
**macOS**：不编译二进制文件（需要Apple代码签名）。请从源——`cargo install` 在一行命令中编译它，无需签名：
```bash
cargo install --git https://github.com/DioNanos/mcp --locked
```
`--locked` 使用已提交的 `Cargo.lock`（可复制构建）。
## 快速开始
```bash
cargo build --release
# stdio MCP服务器，离线模式（默认）
./target/release/mcp-memory-rs
```
Claude Code (`~/.claude.json`) 或任意MCP客户端:
```json
{
"mcpServers": {
"memory": {
"command": "/path/to/mcp-memory-rs",
"env "MCP_DEVICE": "my-laptop" }
}
}
```
Codex (`~/.codex/config：
```tomlcp_servers.memory]
command = "/path/to/mcp-memory-rs"
env = { MCP_DEVICE = "my-laptop" }
# 自动批准只读工具（/list/search/...）；写入批准
default_tools_ = "approve"
```
配置使用TOML——复制 [`config/example.toml`](config/example.toml) 并调整。环境文件值（`MCP_DEVICE`，`MCP`，`MCP_MEMORY_DIR`，...）；示例所有这些。
## 内存模型
内存组织成 **类别**：命名JSON文档（`base`，`projects`my-laptop`，`workflow_my-laptop...）。读取返回文档和元数据（内容哈希，大小，最后写入者，时间戳替换类别或使用 `` 按顶级键进行补丁。
### 访问控制
多设备舰队使用小型显式ACL（配置文件中的 `[acl]`）：
| 规则 | 效果 |
|---|---|
| `admin_devices` | 列出的设备可以写入所有内容| `device_categories 设备 `name` 可以写入类别 `name` 和 `workflow_name` — 仅限其自己的命名空间。 |
| 代理范围 | 设备 `foo-agent` 可以写入 `foo_*` 类别。 |
| 所有人 | 所有设备都可以读取所有内容。 |
未知类别被非管理员写入者拒绝——关闭失败。
### 舰队同步
每个节点运行本地优先；一个节点（或任意数量）将HTTP API作为同步远程端点公开。`sync_manifest` 构建所有类别的Merkle根哈希指纹；`sync_diff` 比较哈希指纹；_sync` 推送脏类别或拉取远程更改。节点之间的冲突由配置的 `conflict_strategy` （默认为最后写入者获胜；`expected_hash` 前置条件保护直接写入（和HTTP），但不保护同步信封。
HTTP API是一个 **admin/sync 平面**：承载令牌授予对所有类别的完全访问权限。每个类别的ACL在MCP stdio表面应用，在那里本地已知设备身份；HTTP调用者仅通过共享令牌识别，因此在那里不强制执行每个设备的ACL。
HTTP服务器 **需要** `MCP_MEMORY_TOKEN` 并且在没有它时拒绝启动。将其绑定到环回地址（默认）并在节点之间进行隧道传输；不要将其暴露给公共互联网。
```bash
MCP_MEMORY_TOKEN=<secret> ./target/release/mcp-memory-rs --http
```
## 工具表面
| 工具 | 描述 |
|---|---|
| `memory_read` | 读取类别（可选字段过滤）。 |
| `memory_write` | 替换或合并补丁类别；版本化；`expected_hash` 前置条件。 |
| `memory_append` | 向有界仅追加 **日志** 类别追加时间戳条目；自动按 `max_entries`/`max_age_days` 清理。为事件流/会话日志，以便它们不会使内存类别膨胀。 |
| `memory_delete` | 删除类别（首先创建备份）。 |
| `memory_list` | 所有类别及其哈希/大小/最后更新元数据。 |
| `memory_search` | FTS5全文搜索，BM25排名，类别/日期/执行者过滤，摘要。 |
| `memory_search_semantic` | 混合TF-IDF + FTS5搜索。 |
| `memory_history` | 类别版本历史。 |
| `memory_delta` | 自已知哈希以来的更改（廉价轮询）。 |
| `memory_context` | 多类别预热读取，面向令牌预算。 |
| `memory_compact` | 清理旧版本和备份。 |
| `memory_status` | 本地优先状态：脏队列，哈希指纹，最后同步。 |
| `memory_doctor` | 诊断：路径，数据库，类别，同步配置。 |
| `sync_manifest` | 所有类别的Merkle根哈希指纹。 |
| `sync_diff` | 比较本地和远程哈希指纹：推送/拉取/冲突集。 |
| `sync_push` / `sync_pull` | 导出/导入同步信封。 |
| `memory_sync` | 针对配置的远程执行同步步骤（`push_dirty` / `pull_remote`）。 |
相同的表面可通过HTTP（`/api/v1/*`）供非MCP消费者使用；`/health` 是未经身份验证的，其他所有操作都需要承载令牌。
### AI客户端兼容性
服务器设计为对弱客户端模型自解释：
- 在 `initialize` 时，它返回一个 **instructions** 字符串，描述内存模型和入口工具。一些轻量级客户端忽略此字段；如果您的客户端从未显示它，请改用工具描述——它们带有相同的指导（例如 `memory_read` 需要 `category`，而非 `key`）。
- 只读工具用 `readOnlyHint` 注释，因此Codex等客户端可以自动批准它们。在Codex中，`unsupported call` / `user cancelled` 结果通常意味着工具批准门控触发，而非服务器故障——请设置 `default_tools_approval_mode = "approve"` （参见上面的Codex代码段）。
- 服务器使用标准MCP握手。客户端必须完成 `initialize` 并像任何MCP客户端一样发送 `notifications/initialized`。
## 存储布局
默认 `base_dir` 为 `~/.memory`；示例配置使用 `~/.local/state/mcp-memory-rs` （XDG样式）。无论哪种方式，布局都是：
```
<base_dir>/
├── categories/ # 每个类别一个.json文件 — 真实来源
├── backups/ # 自动预删除/预覆盖备份
└── memory.db # SQLite：FTS5索引，版本，同步状态（可重建）
```
## 构建和测试
```bash
cargo build --release # 单个静态友好二进制文件
cargo test # 单元 + 集成测试
cargo clippy --all-targets -- -D warnings
```
无需构建时网络访问，无需C依赖项（除了捆绑的SQLite）。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
