# evals/ — 记忆插件评测(方法学,非打榜)

> 定位声明:本评测**不参与 LoCoMo 类打榜**(金标/judge 争议大,同系统分差 ±20)。
> 我们发布的是"轻量文件型记忆的**确定性指标层**":无 LLM、无 API key、结果
> 100% 可复现,随 `npm test` 在 CI 中作为回归护栏运行。
> 背景与完整调研见 [docs/landscape-2026-09.md](../docs/landscape-2026-09.md)。

## 分层

| 层 | 内容 | 依赖 | 状态 |
|---|---|---|---|
| **L0 确定性指标** | 注入预算曲线 / 信噪比 / 淘汰零误杀 / 链接展开边界 | 无(纯计算) | ✅ `l0/`,随 CI 跑 |
| L1 检索层 | 召回命中率 / 误召回率(合成会话 + 免 judge) | 固化一次(离线) | 计划 |
| L3 固化精度 | precision / recall / 污染率 / 去重率 | API key | 计划 |
| L2 端到端 | 三模式 QA 对比 + 分阶段 token/耗时 | DSH + API key | 计划(可选) |

## L0 指标定义

### ① index-budget(注入预算曲线)

固定 `maxBytes=4096`,注入 N 条合成记忆(确定性 seed)后测量整段注入体积。

**Baseline(2026-09-25,CI 持续回归)**:

| N(记忆数) | 注入字节 | 断言 |
|---|---|---|
| 20 | 4065 | ≤ 4096,全量保留 |
| 50 | 4048 | ≤ 4096,截断生效 |
| 100 | 4018 | ≤ 4096 |
| 200 | 3940 | ≤ 4096,截断标记存在 |

附带:软淘汰使过半超龄零引用记忆出局后注入体积相应回落;空库输出 0 字节(零占用硬保证)。
**本指标已驱动一次真实修复**:预算语义从"仅索引"改为"索引+指导文本整段"(旧实现在拼接 policy 尾巴后可超预算 ~800B)。

### ② injection-snr(注入信噪比,characterization)

探针集(每第 4 条标记)在预算截断后的保留率。

| 场景 | 探针保留 | 解读 |
|---|---|---|
| 预算充足(N=20) | 5/5 = 100% | 全量注入,信噪比=结构占比 |
| 半量预算(N=50) | 5/13 ≈ 38% | 位置式截断 |
| N=100 | 5/25 = 20% | 同上 |
| N=200 | 5/50 = 10% | 同上 |
| **半量预算 + 探针置顶(0.3.0)** | **≥ 80%** | **pinned 优先截断:评测驱动迭代的第一次数字移动** |

**已知局限(有意钉板)**:未置顶时截断按索引行序(name 字典序),与相关性无关;
预算恒定 → 保留条数恒定(~20 条),探针均匀分布时保留绝对数也恒定。
**0.3.0 的 pinned 优先排序已在同预算下把置顶探针保留率提升至 ≥80%**
(同一 seed、同一批记忆、同一预算的对照断言,见 injection-snr.spec.ts);
完整的三因子相关性排序仍在路线图,届时更新本表。

### ③ eviction-correctness(淘汰零误杀)

四类混合(超龄零引用 / 超龄已读 / 新写入 / 无元数据旧文件):
只有第一类从注入索引隐藏;**文件层面零丢失**;被读一次即复活且此后豁免。
断言误杀数 = 0(等价 MemoryBank R=e^(−t/S) 的"召回重置强度"语义)。

### ④ link-expansion(链接展开边界)

`[[name]]` 一层展开:上限 3 条并标记 truncated、自链排除、坏链接安全跳过、
单次展开体积 ≤ 3×660 UTF-8 字节(有界性)。

## 复现

```sh
npm test          # L0 随全量测试运行(vitest 自动拾取 evals/l0/*.spec.ts)
```

构造器(`helpers.ts` 的 seededRandom/makeMemories/seedStore)是未来
L1/L3 合成数据集(harness-sessions:虚拟开发者多会话剧本)的地基。