@mtl/sdk — 接入中立记忆评测榜单 / Integrate with the Neutral Memory Benchmark

实现 9 个原语 → 跑真实基准 → 提交上榜。同一套基准、同一套标准,公平可比。

这是什么 / What is this

中立第三方 Agent 记忆评测榜单的官方 SDK。你(记忆系统厂商/开发者)用它:

1. 把你的记忆系统对接到统一的 9 原语接口
2. 跑同一套公开基准(LongMemEval 真实 500 题 / synthetic-qa)
3. 产出标准 RunResult JSON,提交到榜单,经我们复现验证后上榜

榜单用固定的基准 + 公开的方法学 + 一致的评分算法,所有系统可比。详见 methodology。

安装 / Install

npm install @mtl/sdk

TS 适配器推荐用 tsx 直接跑:npm install -D tsx(也可编译成 JS)。

5 分钟上手 / Quick start (5 min)

# 1. 生成适配器模板
npx mtl init my-adapter
#   → 生成 my-adapter.ts(实现 9 原语的骨架)

# 2. 实现 9 个原语(把你的记忆系统接进去)—— 见下方"适配器指南"

# 3. 跑基准,产出可提交的 JSON
npx tsx --tsconfig=tsconfig.json node_modules/@mtl/sdk/dist/cli.js run \
  --adapter ./my-adapter.ts --benchmark synthetic-qa --out result.json

# 或装好后直接:npx mtl run --adapter ./my-adapter.ts --benchmark synthetic-qa --out result.json

# 4. 校验格式
npx mtl validate result.json
#   → ✓ 格式正确

# 5. 提交到榜单:把 result.json 上传到榜单网站的"接入你的系统"表单

跑出来长这样(result.json 节选):

{
  "benchmarkId": "synthetic-qa",
  "adapterId": "my-system",
  "timestamp": "2026-07-24T...",
  "metrics": {
    "recallAt5": 0.83, "precisionAt5": 0.40, "mrr": 0.91, "ndcgAt10": 0.88,
    "latencyP95Ms": 12.4, "totalTokenCost": 0
  },
  "queryResults": [ ... ]
}

综合得分 / Composite score = (recall@5 + ndcg@10) / 2,榜单按此排序。

可用基准 / Available benchmarks

| id | 说明 | 数据 | 跑法 | |---|---|---|---| | synthetic-qa | 合成基线(快速验证用) | 内置 | 累积模式 | | longmemeval | 真实长期记忆 500 题(业界标准,MIT) | 内置 | 隔离模式(每题独立) |

跑 longmemeval(真考卷):

npx mtl run --adapter ./my-adapter.ts --benchmark longmemeval --out result.json

命令参考 / CLI reference

| 命令 | 作用 | |---|---| | mtl init <name> | 生成适配器模板 | | mtl run --adapter <path> --benchmark <id> [--out <file>] [--judge f1\|exact-match\|substring] | 跑基准,出 RunResult JSON | | mtl validate <result.json> | 校验提交格式 |

下一步 / Next

• 适配器指南 / Adapter Guide —— 9 个原语每个怎么实现、哪些是评测必需、哪些是治理必需
• 提交指南 / Submit Guide —— RunResult 格式、提交流程、验证机制、信任分级

许可证 / License

MIT。基准数据 LongMemEval 为 MIT(可随 SDK 分发);LoCoMo 等其它基准受各自许可约束(见各基准说明)。