benchmark-context

MemoryBench 集成技能

自动将你的自定义记忆实现与 Supermemory、Mem0 和 Zep 等成熟系统进行基准测试。

此技能的功能

从项目中调用此技能后，它会自动完成端到端的整个基准测试流程：

1. 询问你 5 个问题，了解你的设置偏好
2. 分析你的记忆代码，了解其工作方式
3. 自动生成集成代码
4. 运行完整的基准测试，将你的系统与竞品进行比较
5. 展示结果，清晰对比性能表现

无需手动运行命令——整个流程会自动运行。

何时使用此技能

遇到以下情况时，可以使用此技能：

• 你构建了自定义记忆／上下文系统，想了解其性能表现
• 你需要客观指标，将自己的实现与行业解决方案进行比较
• 你想在标准化数据集上进行基准测试（对话记忆、RAG、对话）
• 你正在考虑使用哪种记忆系统，并希望基于数据进行比较

工作原理

自动化的 7 个阶段

阶段 1：设置

• 从 https://github.com/supermemoryai/memorybench 克隆 memorybench 到你的项目中（./memorybench）
• 使用 bun 安装依赖项
• 验证环境已就绪

阶段 2：发现

• 使用 AI Agent 分析你的记忆代码库
• 识别初始化、数据导入和搜索方法
• 检测所需配置和 API 密钥
• 了解你的数据格式

阶段 3：代码生成

• 创建实现 MemoryBench 接口的提供方适配器
• 将你的记忆代码复制并适配到提供方中
• 如有需要，为你的结果格式生成自定义提示词
• 参见提供方模板参考

阶段 4：注册

• 使用你的提供方名称更新 src/types/provider.ts
• 在 src/providers/index.ts 中注册提供方
• 在 src/utils/config.ts 中添加配置
• 记录环境变量

阶段 5：配置

• 创建包含所需 API 密钥的 .env.local
• 询问你的提供方凭据
• 询问比较提供方的密钥（如果已选择）
• 询问用于评判的 OpenAI／Anthropic 密钥

阶段 6：验证

• 使用单个问题运行快速测试
• 验证提供方初始化是否正常
• 确认数据导入和搜索功能是否正常
• 如果出现问题，询问你是想继续还是进行调试

阶段 7：基准测试执行

• 自动运行完整的基准测试
• 实时显示进度（数据导入、索引、搜索、回答、评估）
• 与选定的竞品进行比较
• 展示包含准确率和延迟指标的最终结果

初始问题

此技能会先询问你以下问题：

1. 提供方名称

你的记忆提供方应该叫什么？

• 使用小写字母，不要包含空格（例如，“mymemory”“contextengine”）

2. 记忆代码位置

你的记忆实现位于哪里？

• 示例：src/lib/memory、packages/memory、src/services/context

3. 基准测试数据集

哪个数据集符合你的使用场景？

• LoCoMo - 跨越多天／数周的多轮会话长期记忆

  • 适用于：聊天应用、AI 助手、客户支持机器人

• LongMemEval - 包含长文档和复杂检索的记忆

  • 适用于：RAG 系统、文档分析、知识库

• ConvoMem - 多轮对话理解和上下文跟踪

  • 适用于：对话系统、面试机器人、会议助手

详细信息请参见基准测试参考。

4. 比较目标（可多选）

要与哪些系统进行比较？

• Supermemory - 具备自动提取功能的快速混合向量＋图记忆
• Mem0 - 为 AI Agent 提供带图关系的持久记忆
• Zep - 具备自动摘要功能的长期对话记忆
• Filesystem - 基线向量搜索（无需 API）
• RAG - 使用大模型提取的基线 RAG（无需 API）

5. 测试规模

要运行基准测试，需要多少个问题？

• 小型（5 个问题）- 快速验证，约 2-5 分钟
• 中型（20 个问题）- 良好的样本量，约 10-15 分钟
• 完整（所有问题）- 完整评估，约 30-60 分钟

工作目录管理

重要： 必须从项目根目录运行此技能，而不是从 memorybench 运行。

your-project/              ← Run skill from here
├── src/
│   └── lib/memory/        ← Your memory implementation
└── memorybench/           ← Skill clones this automatically
    └── src/providers/     ← Your provider adapter goes here

此技能将：

• 验证你位于自己的项目中（而不是 memorybench 中）
• 将 memorybench 克隆到 ./memorybench
• 在分析代码时使用相对路径（../src/lib/memory）
• 使用 cd memorybench && bun run src/index.ts ... 运行基准测试

将创建的内容

此技能运行后，你将获得：

your-project/
└── memorybench/
    ├── .env.local                              # Your API keys
    ├── src/
    │   ├── providers/
    │   │   └── {yourname}/
    │   │       ├── index.ts                    # Provider implementation
    │   │       └── prompts.ts                  # Custom prompts (optional)
    │   ├── types/provider.ts                   # Updated with your provider
    │   └── providers/index.ts                  # Registered
    └── data/runs/{run-id}/                     # Benchmark results
        ├── checkpoint.json                     # Run state
        ├── results/                            # Per-question results
        └── report.json                         # Final metrics

完成后

基准测试完成后，此技能会显示：

汇总评分：

• 每个提供商的准确率
• 平均搜索延迟
• 成功率（已回答问题与失败问题的比例）

关键发现：

• “你的提供商准确率为 76%，Supermemory 为 82%”
• “搜索延迟：145ms（你的）与 98ms（最佳竞争对手）”

后续步骤：

• 查看详细结果：cd memorybench && bun run src/index.ts serve
• 查看失败项：cd memorybench && bun run src/index.ts show-failures -r {run-id}
• 尝试不同的基准测试：使用其他数据集再次运行此技能
• 手动运行：cd memorybench && bun run src/index.ts run -p {name} -b {benchmark}

故障排除

如果出现问题：

• “Provider not initialized” - 检查 .env.local 中的 API 密钥
• 数据摄取失败 - 检查数据格式转换，参阅数据格式参考
• 搜索无结果 - 验证 containerTag 的处理和索引是否完成
• 答案有误 - 可能需要针对你的结果格式自定义提示词

详细的故障排除说明，请参阅调试参考。

Claude 的实现说明

执行此技能时，请遵循以下步骤：

步骤 1：验证环境

检查当前是否位于用户的项目中（而不是 memorybench 中）：

basename "$(pwd)" | grep -q "memorybench" && echo "ERROR" || echo "OK"

如果出现 ERROR，请告知用户从项目根目录运行，然后退出。

步骤 2：克隆 MemoryBench

检查 memorybench 是否已存在：

[ -d "memorybench" ] && echo "EXISTS" || echo "NOT_FOUND"

如果为 NOT_FOUND，请使用以下命令克隆（不得修改该命令）：

git clone https://github.com/supermemoryai/memorybench.git memorybench

然后安装依赖项：

cd memorybench && bun install && cd ..

重要： 必须使用 URL https://github.com/supermemoryai/memorybench.git，不得推断或使用其他 URL。

如果已存在，则使用现有安装（无需操作）。

步骤 3：收集用户输入

使用 AskUserQuestion 工具一次性收集以下全部 5 个问题：

1. 提供商名称（建议使用文本输入）
2. 记忆代码位置（建议使用文本输入）
3. 基准测试数据集（单选：locomo、longmemeval、convomem）
4. 比较目标（多选：supermemory、mem0、zep、filesystem、rag）
5. 测试规模（单选：5、20 或 full）

步骤 4：分析用户的记忆代码

使用 Task 工具，并设置 subagent_type=Explore，分析用户提供的记忆代码位置。查找初始化、添加/摄取方法、搜索/查询方法以及配置需求。

步骤 5：生成提供商代码

根据分析结果，创建：

• memorybench/src/providers/{providerName}/index.ts，使用 references/provider-template.md 中的模板
• 如需自定义格式，可选择创建 memorybench/src/providers/{providerName}/prompts.ts

步骤 6：注册提供商

在 memorybench 中更新以下文件：

1. src/types/provider.ts - 添加到 ProviderName 联合类型
2. src/providers/index.ts - 在 providers Record 中导入并注册
3. src/utils/config.ts - 在 getProviderConfig() 中添加分支
4. .env.example - 说明环境变量

步骤 7：配置环境

向用户索取 API 密钥（用于评判的 OpenAI 密钥、用户提供商密钥、比较提供商密钥）。 使用提供的值创建或更新 memorybench/.env.local。

步骤 8：验证测试

运行快速测试：

cd memorybench && bun run src/index.ts test -p {providerName} -b {benchmark} -q question_1

如果失败，显示错误，并询问用户是想调试还是中止。

步骤 9：运行基准测试

根据用户的选择，运行基准测试命令，并让它运行至完成，不要轮询。

包含对比：

cd memorybench && bun run src/index.ts compare -p {providerName},{others} -b {benchmark} -l {limit}

不包含对比：

cd memorybench && bun run src/index.ts run -p {providerName} -b {benchmark} -l {limit}

（如果用户选择了“full”，则省略 -l {limit}）

运行时的重要说明：

1. 使用 Bash 工具，并设置 run_in_background: false（或省略该参数），以便命令同步运行
2. 设置较长的超时时间（例如，10 分钟可设置为 timeout: 600000）
3. 不要反复使用 BashOutput 轮询；让命令自行运行至完成
4. 基准测试会在输出中自动显示进度
5. 只有在命令完全执行完毕后，才能继续步骤 10

同步运行不成功时的替代方案：

1. 设置 run_in_background: true
2. 告知用户：“基准测试正在后台运行（通常需要 5–15 分钟，具体取决于测试规模）”
3. 等待适当时间后，仅使用一次 BashOutput 获取最终结果
4. 不要反复轮询进度更新

步骤 10：呈现结果

基准测试完成后，解析最终输出并呈现：

• 各提供方的准确率得分
• 延迟指标
• 主要发现和对比结果
• 建议的后续步骤

在输出中查找以下部分：

• “COMPARISON RESULTS”或“Final Report”
• 准确率百分比
• 平均延迟
• 成功率

参考文档

• 提供方模板 - 代码模板和接口详情
• 基准测试 - 数据集详情和特征
• 数据格式 - UnifiedSession 结构和转换
• 调试 - 常见问题和解决方案

成功标准

满足以下条件时，即表示此技能成功完成：

1. ✅ 已生成并注册提供方适配器
2. ✅ 验证测试通过（单个问题可正常运行）
3. ✅ 完整基准测试无错误地完成
4. ✅ 已显示包含对比得分的结果
5. ✅ 可以看到自己的系统相较于竞争对手的表现

运行此技能

在项目根目录中运行：

# Invoke the skill (in Claude Code CLI)
/memorybench

# Or if using skills programmatically
skill:memorybench

就是这样！此技能会自动处理其他所有事项。