内容
# 内存工具一致性测试
[](https://pypi.org/project/memory-tool-conformance/)
> **填补空白的测试基础设施。** 目前已有 33+ 个内存 MCP 服务器；**但没有一个** 发布他们所依赖的一致性测试套件来验证 [内存工具 API 规范](https://platform.claude.com/docs/en/build-with-claude/context-editing)。本项目提供了一个可供其他服务器作者集成的测试基础设施，用于验证规范的一致性 —— 同时提供了一个文件系统支持的参考实现，通过了全部 10 项测试。
> 插件兼容：任何内存实现（文件系统、SQLite、向量数据库、Obsidian vault、分布式 KV）—— 如果它满足 6 操作契约（`view` / `create` / `str_replace` / `insert` / `delete` / `rename`），测试套件就会对其进行评分。
[](https://github.com/M00C1FER/memory-tool-conformance/actions)
## 为什么这个空白尚未被填补
内存工具 API 规范发布在 [platform.claude.com/docs/en/build-with-claude/context-editing](https://platform.claude.com/docs/en/build-with-claude/context-editing)；[内存 cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb) 是一个教程；但**没有一个** 是 *测试基础设施*。awesome-claude-skills 索引列出了 33+ 个内存 MCP 服务器（mcp-memory-service、mem0、letta-style adapters 等）—— 但没有一个发布了针对已发布规范的一致性检查。本项目填补了这一空白，成为每个内存服务器作者都可以集成的 CI 依赖项，以显示“通过 7/7”的徽章。
## 功能
- **一致性测试框架** —— 运行 10 个场景契约针对任何候选实现，返回通过/失败报告：
- `op:create+view`
- `op:create-overwrite`
- `op:str_replace`
- `op:insert` （后行语义）
- `op:insert-head` （行=0 头插入）
- `op:insert-append` （行>EOF 追加）
- `op:rename`
- `op:rename-cross-dir` （跨目录，自动创建父目录）
- `op:delete`
- `op:view-directory`
- **参考实现** —— `FilesystemMemory`，一个基于路径的文件系统支持的服务器，通过了 10/10 项测试。你可以直接使用它，或将其用作规范的“应该如何行为”的基准。
- **命令行界面** —— `memory-conformance --target your_module:factory` 运行套件针对任何已安装的实现。
## 为什么这个空白
awesome-claude-skills 索引列出了 33+ 个内存 MCP 服务器。**没有一个** 发布了针对已发布规范的一致性测试框架。本项目成为其他所有内存服务器作者信任的 CI 依赖项。
## 快速开始
```bash
pip install git+https://github.com/M00C1FER/memory-tool-conformance.git # 待发布到 PyPI
# 运行一致性测试针对内置参考实现
memory-conformance
# → 10/10 操作通过（100%）
# 运行针对您自己的实现
memory-conformance --target my_pkg.memory:make_server --name "my-server"
```
```python
# 以编程方式使用
from memory_tool_conformance import FilesystemMemory
from memory_tool_conformance.conformance import run_conformance
server = FilesystemMemory("~/.memory-api")
report = run_conformance(server, server_name="my-server")
print(report.render())
print(f"all_pass: {report.all_pass}")
```
## 6 操作契约
根据 [内存工具规范](https://platform.claude.com/docs/en/build-with-claude/context-editing):
| 操作 | 签名 | 语义 |
|---|---|---|
| `view` | `(path, view_range?)` → `str` | 返回文件内容或目录列表。可选 1-indexed `[start, end]`。 |
| `create` | `(path, file_text)` → `ack` | 按需创建父目录；如果存在则覆盖。 |
| `str_replace` | `(path, old_str, new_str)` → `ack` | 替换第一个出现。如果 `old_str` 不存在则抛出。 |
| `insert` | `(path, insert_line, text)` → `ack` | 在 1-indexed 行 N 后插入。 |
| `delete` | `(path)` → `ack` | 删除文件或目录。 |
| `rename` | `(old_path, new_path)` → `ack` | 原子重命名。创建父目录。 |
所有路径以 `/memories` 开头。路径遍历（`..` 跳出根目录）被拒绝。
## 比较
MCP 内存生态系统中尚不存在“参考实现 + 一致性测试套件”模式。
| | 一致性测试框架 | 参考实现 | 路径遍历保护 | 符合规范 |
|---|:-:|:-:|:-:|:-:|
| `mcp-memory-service` | ❌ | ✅ | 取决于实现 | 部分 |
| 其他 33+ 内存服务器 | ❌ | 各自实现 | 取决于实现 | 取决于实现 |
| **memory-tool-conformance** | **✅** | **✅** | **✅** | **✅ 10/10** |
## 将您的服务器添加到排行榜
1. 实现一个工厂函数，返回一个具有 6 操作契约的实例：
```python
def make_server():
return MyMemoryServer(...)
```
2. 运行：`memory-conformance --target mypkg.memory:make_server --name "my-server"`
3. 打开一个 PR，将您的结果添加到 `LEADERBOARD.md`。
## FastMCP 服务器（可选）
如果您想直接将 `FilesystemMemory` 插入到 Claude Desktop 或任何 MCP 客户端：
```bash
pip install -e .[mcp]
python -m memory_tool_conformance.server # stdio （默认）
python -m memory_tool_conformance.server --transport sse --port 8765
```
设置 `MEMORY_ROOT` 以选择内存存储位置（默认：`~/.memory-api`）。
Claude Desktop 配置：
```json
{
"mcpServers": {
"memory": {
"command": "python",
"args": ["-m", "memory_tool_conformance.server"],
"env": { "MEMORY_ROOT": "~/.memory-api" }
}
}
}
```
## 测试
```bash
pip install -e .[dev,mcp]
pytest
```
75 个测试涵盖所有 6 个操作，跨越四个测试模块：
- **`test_fs_memory.py`** （37 个测试）—— 核心 happy-path、边缘情况、路径遍历保护（包括符号链接逃逸）、视图范围验证、原子写入崩溃语义、一致性测试套件。
- **`test_pyfakefs.py`** （18 个测试）—— 与完全在内存中的伪文件系统（无实际磁盘 I/O）运行相同的场景；更快且完全隔离。
- **`test_property.py`** （9 个测试）—— 基于假设的属性测试，探索所有 6 个操作的任意输入，检查不变式。
- **`test_server.py`** （11 个测试）—— 使用进程内 `fastmcp.client.Client` + `FastMCPTransport` 的 FastMCP 服务器层测试（需要 `[mcp]` 额外依赖）。
## 平台支持
该软件包是纯 Python 的，需要 **Python 3.10+**。它可以在 Python 支持的任何平台上运行。
| 平台 | 状态 | 备注 |
|---|:-:|---|
| Linux (Debian/Ubuntu/Arch/Fedora) | ✅ | 主要目标；在 CI 中进行完整测试 |
| macOS | ✅ | 在 CI 中进行测试（macos-latest） |
| Alpine (musl libc) | ✅ | 通过 `python:3.12-alpine` 容器在 CI 中进行测试 |
| WSL2 (Ubuntu 基础) | ✅ | 与 Linux 相同；无 systemd/proc 假设 |
| **Termux** (Android, arm64) | ✅ | 参见下面的 [Termux](#termux) 部分 |
| Windows (原生) | ⚠️ | 路径 API 有效；`fcntl` 文件锁定是 no-op。单进程使用是安全的。 |
### Windows 文件锁定决策
`fcntl.flock` 是 POSIX-only 的，在 Windows 上不可用。**虚拟路径 API (`/memories/…`) 和路径遍历保护在 Windows 上正确工作** —— 所有路径按约定使用正斜杠。文件锁定降级为 no-op，因为 Windows 在 OS 级别强制执行强制锁定语义，而典型的用法模式是单进程。Windows 上的并发多进程写入不保证安全；如果您需要在 Windows 上进行跨进程安全，请使用线程锁包装 `FilesystemMemory`。
## Termux
`pkg install python` 是唯一的先决条件。
```bash
# Termux 上的一次性安装
pkg install python git
pip install git+https://github.com/M00C1FER/memory-tool-conformance.git
# 冒烟测试
memory-conformance --force
# → 10/10 操作通过（100%）
```
或者，从本地克隆安装：
```bash
bash scripts/install-termux.sh # 安装开发额外依赖 + 运行冒烟测试
```
**Termux 备注：**
- `fcntl.flock` 可用（Android/Bionic 提供）；文件锁定正常工作。
- 无 `/etc/passwd`、systemd 或其他 Linux 特定假设。
- `mcp` 可选额外依赖（`fastmcp`）需要编译轮；安装可能需要更长时间或在旧设备上需要构建环境。核心一致性测试框架和参考实现无需它即可工作。
## 许可证
MIT。
MCP 市场