@mtl/evaluation — 中立记忆评测包 / Neutral Memory Benchmark Harness

Memory Trust Layer 的 Product B。中立、寄生、可复现的 agent 记忆评测。 The neutral, parasitic, reproducible evaluation harness for AI agent memory — "the MLPerf / LMSYS for agent memory."

这是什么 / What it is

一个不偏向任何记忆架构的基准执行器。任何 agent 记忆系统(Mem0 / Letta / Graphiti / 裸向量库 / …)只要实现 @mtl/contract 的三个评测原语(retrieve / write / telemetry),即可被本包中立地评测,并与其他系统在同一榜单上公平排名。

中立性是护城河。 我们既不存数据、也不替代任何记忆库 —— 只通过公开、冻结、可复算的方法学(methodology.md)对记忆系统提出相同的问题。

快速开始 / Quick start

# 构建 / build
npm run build --workspace @mtl/evaluation

# 跑单个适配器 / run one adapter
node packages/evaluation/dist/cli.js run --adapter mock --benchmark synthetic-qa

# 生成榜单(mock vs noop)/ generate leaderboard
node packages/evaluation/dist/cli.js leaderboard

# 测试 / test
npx vitest run packages/evaluation

编程用法 / Programmatic usage

import { MockAdapter } from '@mtl/contract'
import { runBenchmark, generateLeaderboard, SYNTHETIC_QA } from '@mtl/evaluation'

// 1. 评测单个适配器 / evaluate one adapter
const run = await runBenchmark(new MockAdapter(), SYNTHETIC_QA)
console.log(run.metrics.recallAt5, run.metrics.ndcgAt10)

// 2. 多适配器榜单 / leaderboard across adapters
const runs = [{ ...run, adapterLabel: 'MockAdapter' }]
console.log(generateLeaderboard(runs))   // markdown 表(双语)

测什么 / What we measure

| 维度 | 指标 | 说明 | |---|---|---| | 检索质量 | recall@{1,5,10} | 召回完整度 | | 检索质量 | precision@{1,5,10} | top-k 纯度 | | 检索质量 | MRR | 首个相关项倒数排名 | | 检索质量 | nDCG@10 | 排序质量(二值相关性) | | 效率 | latency P50/P95 | 延迟百分位(ms) | | 效率 | totalTokenCost | token 成本之和 |

综合得分 / Composite score: score = (recall@5 + ndcgAt10) / 2 —— 见 methodology.md §3 为何选这两个互补指标。

不崩溃契约 / No-crash contract

runBenchmark() 永不抛错。不支持某原语的适配器(如 NoopAdapter)产生零指标 RunResult,照常上榜垫底 —— 缺席不是中立,垫底才是。

包结构 / Package layout

src/
├── types.ts                 # Benchmark / Scenario / Query / RunResult / ComputedMetrics
├── benchmarks/              # synthetic-qa (真实) + locomo/longmemeval/babilong (桩) + REGISTRY
├── metrics/
│   ├── retrieval.ts         # recall/precision/mrr/ndcg  (纯函数,手算验证)
│   └── efficiency.ts        # latencyPercentile / totalTokenCost
├── harness.ts               # runBenchmark (NoopAdapter-safe)
├── leaderboard/generator.ts # generateLeaderboard (markdown 表)
├── cli.ts                   # mtl-evaluation CLI
└── index.ts                 # barrel
docs/
├── methodology.md           # ⭐ 中立方法学(核心文档,双语)
├── architecture.md
└── plan.md                  # 0→1 路线图

基准状态 / Benchmark status

| id | 状态 | 用途 | |---|---|---| | synthetic-qa | ✅ 真实,确定性 | 管道验证 / 回归测试 | | locomo | 🟡 结构桩 | 接入缝见 src/benchmarks/locomo.ts | | longmemeval | 🟡 结构桩 | 同上 | | babilong | 🟡 结构桩 | 同上 |

桩的存在是为了让方法学先冻结、先发布,真实数据集接入是独立工作流(plan.md)。

设计原则 / Design principles

1. 寄生而非替代 / Parasitic, not replacement — 只评测,不存数据,不替代任何记忆库
2. 契约即通道 / Contract as channel — 只调 retrieve/write/telemetry,不感知记忆系统内部结构
3. 中立即护城河 / Neutrality is the moat — 方法公开冻结,任何厂商可复算质疑
4. 缺席不是中立 / Absence is not neutral — 能力缺失的系统照常上榜垫底,不被剔除

文档 / Docs

• 评测方法学 / Methodology ⭐ 核心
• 架构 / Architecture
• 路线图 / Roadmap