@mtl/contract — 记忆适配器契约 / Memory Adapter Contract

治理(治理)+ 评测(评测)两个产品共同依赖的基石。 任何 agent 记忆系统(Mem0 / Letta / Graphiti / 裸向量库 / …)实现此接口,即可被 中立地审计与评测。

核心思想 / Core idea

契约即评分卡(The contract IS the rubric)。 一个记忆系统实现不了的原语,就是它的合规漏洞,直接进审计报告。本层只"审问"记忆,不存数据、不替代任何记忆库——寄生而非替代。

9 个能力原语 / 9 primitives

| 组 | 原语 | 作用 | 合规/评测意义 | |---|---|---|---| | 审计 | enumerate | 分页列出全部记忆 | 不可盘点 = 不可审计 | | 审计 | provenance | 单条记忆来源溯源 | 不可溯源 = 合规不过 | | 审计 | subjectLookup | 按用户主体拉取记忆 | 被遗忘权的执行前提 | | 审计 | delete | 删除并验证(硬删 vs 软删) | 删不掉 = PIPL/GDPR 违法 | | 审计 | export | 导出某用户全部记忆 | 数据可携带,硬要求 | | 审计 | mutationHistory | 记忆改前版本 | 事实演化追溯(金融/医疗必查) | | 评测 | retrieve | query 召回结果 | 测 recall/precision | | 评测 | write | 写入记忆 | 喂基准场景 | | 评测 | telemetry | 延迟/成本遥测 | 效率维度打分 |

用法 / Usage

import { MockAdapter, fullProfile, Capability } from '@mtl/contract'

// 1. 实现接口(或用参考适配器)
const adapter = new MockAdapter()

// 2. 探测能力支持 + 质量(关键:不止"能不能",还看"好不好")
const profile = await fullProfile(adapter)
// => [{ capability: 'delete', supported: true, quality: 'full', notes: '硬删 ...' }, ...]

// 3. 缺口即漏洞
const gaps = profile.filter((r) => !r.supported || r.quality === 'degraded')

参考适配器 / Reference adapters

• MockAdapter — 全功能正确实现(硬删除、完整溯源、历史版本)。黄金样本 + 演示 + 测试基底。
• NoopAdapter — 零能力(每原语抛 UnsupportedError)。验证缺口检测有效,治理产品的"反面教材"。

质量分级 / Quality grading

探针不仅判断"是否支持",还判断"质量":

• full — 完整正确(如 delete 是硬删除,删除后不可枚举)
• partial — 部分支持(如 delete 是软删除,仍可恢复)
• degraded — 名义支持但有缺陷(如 delete 声称成功但记录仍可见 = 违规)

这一分级直接驱动治理审计报告的风险等级,和评测榜单的治理维度评分。