Imported from zzp-elio/AgentMemoryBench (
AGENTS.md). Install upstream withnpx skills add zzp-elio/AgentMemoryBench. Copyright stays with the author.
Agent Memory Benchmark Framework 入口
本文件是静态入口:只放项目定位、硬规则、协作模式和导航。任务进展一律看
docs/roadmap.md 和对应 workstream README;本文件不记录逐任务状态。
历史版本(2026-06 流水账)在 docs/archive/status/2026-07-04-agents-log.md。
项目定位
- 长期目标:可复现、可扩展、可审计的多 task-family Agent Memory Benchmark 框架。
- Phase 1 固定范围(2026-07-04 锁定,2026-07-11 名单修订):5 benchmark (LoCoMo、LongMemEval、HaluMem、BEAM、MemBench)× 10 method(学术型 A-Mem、 MemoryOS、MemOS、LightMem、SimpleMem;工程型 Mem0、Letta/MemGPT、EverOS、 LangMem、Graphiti)× 尽可能多 metric。2026-08-09 source gate 复核确认 Supermemory stable self-host 只有预编译 runtime、公开仓库缺 server/engine source,用户裁定由 Graphiti OSS 接替第十格。这里的 method 身份严格是 Apache-2.0 的 Graphiti,不是 Zep hosted product,也不宣称 Zep parity;Supermemory blocked note 只作历史 source-gate 判例。
- 主协议 v3 provider:
MemoryProvider.ingest(unit) + retrieve(query) -> RetrievalResult,粒度由实例级consume_granularity(turn/pair/session/ conversation)声明、框架事件流聚合投递;framework reader 统一执行 answer LLM。主配置使用 benchmark 统一 answer builder;作者校准配置可选择 method 官方 builder。协议全文:docs/workstreams/ws02-phase1-matrix/spec-protocol-v3.md。旧BaseMemorySystem/BaseMemoryProvider(add+retrieve)只保留给明确列账的 legacy parity/resume 消费者;v2 bridge 已退出,新 run 与新 adapter 不得使用。 - 运行主线(4 步,2026-07-08 与用户对齐):① 给 method 注入记忆(ingest);
② 用 query 检索记忆(retrieve →
formatted_memory)——每个 method 一律用 通用产品接口,不用 benchmark 专用评测实现(公平/可比/代表性,见 ws02.5 审计); ③ 用检索回的记忆 + 框架自带的 answer LLM 配置与 answer prompt 回答问题 (unified 口径,非 method 原生答题——这样只有"记忆质量"在变,隔离出可比性); ④ 从实验结果算 metric,涉及 LLM judge 时用框架自带的 judge LLM 配置与 prompt。 - prompt 来源政策:主
smoke/official_full的 answer prompt 与所有配置的 judge prompt,benchmark 官方仓库有就先用它的,没有才自研;二者必须 per-benchmark、method 无关(同一 benchmark 上所有 method 用同一把尺子)。只有显式author_<benchmark>校准 section 可选择该 method 官方的完整 answer builder,且只能 作为补充复现,不能混入主表;judge 仍走 benchmark 统一配置。参考 method 代码只借格式 或构造作者校准,禁止暗中给主配置引入某 method 的专属优势。 - method 配置不再按
native/unified强铺双轨(2026-07-17 改判):每个 method 一个 TOML;2026-08-24 起 method 主算法参数进一步与 API runtime/execution scope 分离, 不再把通用 timeout/retry/workers 因smoke/official_full复制两份。作者确实跑过的 benchmark 才增加稀疏author_<benchmark>section。CLI 只选择显式 profile,不逐项传算法 参数或暗中按 benchmark 自动切换。answer 配置选择的是填好全部变量、可直接调用 LLM 的完整 builder,不是模板文件。现行政策见docs/reference/method-toml-and-answer-builder-policy.md;旧config_track只作历史产物 兼容,迁移排在首个作者校准/真实效果 full run 前。对 retrieve 与答题耦合的 method (如 MemoryOSget_response),仍须忠实抽出formatted_memory与公开 builder 变量。 - Phase 1 controlled embedding(2026-08-24 改判,2026-08-25 身份闭合):所有实际消费 embedding、且可经
upstream 公开 seam 无损替换的方法,主比较统一
all-MiniLM-L6-v2/384;manifest/resume 必须锁 provider/model/revision/dimension/normalization/instruction/distance/tokenizer、项目本地 模型内容闭包与实际 loader runtime;新 run 使用 identity v2,v1 只读且严格不 resume。变更即 全量重建。不消费 embedding 的产品 profile 记 N/A,禁止为了“十家统一”填一个运行时未使用 的模型;product-default/author 配置只作显式补充校准。省略第三方 SDK 参数不等于显式 None, 必须沿到最终 product object/payload 才能裁定。 - API runtime 分 profile(2026-07-27 用户改口,2026-08-21 模型更新):新
smoke与 独立predict pilot使用限时免费opencodego/ox-alpha-free做流通、并发下界与调用拓扑 验证;pilot复用 TOML[smoke]参数但保留一个完整 isolation、全部问题和独立 manifest/ 输出目录,不得用 smoke 裁剪或official_full冒充。该模型 必须发送reasoning_effort="low",不得发送 thinking disabled。历史opencodego/deepseek-v4-flash与muse-spark-1.2-contributorartifact 保持按 manifest 回读。2026-08-26 新增独立calibrationprofile:使用opencodego/mimo-v2.5+thinking={type:disabled},只配合predict formal的完整、显式 isolation cohort 做预算/扩大稳定性实验;它不改变 method 主算法和 benchmark answer 参数,也 不与 ox 或正式分数混算。official_full使用primary/gpt-4o-mini;2026-08-27 显式注册的 LightMemauthor-locomo使用独立apilio/gpt-4o-miniChat runtime, 不构成 primary 失败 fallback,也不自动推广到其他 author profile。provider/model/answer transport/judge transport 必须进入 manifest/resume identity;不同 runtime 的分数不得直接比较。secret/base URL 只从.env读取、不落 artifact。现行细则见docs/reference/api-runtime-profiles.md。
协作模式
- 架构师 = 写 spec/plan、裁定断点冲突、审查验收、把控方向与结构(跨模型轮换:
Claude → GPT-5.6 → …)。新架构师冷启动第一入口:
docs/reference/architect-onboarding.md(唯一交接文档:角色、读序、铁律、 决策、陷阱;在途状态一律看活跃 ws README 断点区,该文不双写;原 handover-to-next-architect.md 已于 2026-07-14 并入并删除),再配docs/reference/architect-playbook.md(热规则与任务检索入口,供"上任自检")+docs/reference/playbooks/architect/(完整冷层案例)。经验库不得在上任或 compaction 后默认全文读取;先由热入口按任务标签检索一到两条相关案例。 - 执行者(actor)= 跨产品轮换池(2026-07-07 起):Codex /
OpenCode+DeepSeek / WorkBuddy(GLM-5.2) / Claude Sonnet / MiniMax 等,可能随时
换人、新开会话,不等于当前 Codex 可启动的 subagent,一律视为
"刚进公司的新人"**。actor 写交接记录时须核实自己会话的实际模型(看系统提示),
别顺手套用本池里的名字(2026-07-08 判例:一个 WorkBuddy/GLM-5.2 会话把自己
误标成"Claude Sonnet",架构师又照搬未核实——身份自标也要验证,同"验证 actor
断言"一理)。actor
规矩全文在
docs/reference/actor-handbook.md(上工流程、红线、停工条件、报告 格式)。每张 actor 卡本身就是可直接复制发送的自包含 prompt,禁止在卡尾再套 一份内容重复的“可转发 prompt”;并把工作量限制在单个 5h 窗口内。卡内列出本批 要读的最少文件(AGENTS.md→ 目标 workstream README → plan 当前批次 →actor-handbook.md)和明确停点,不能只丢一份 大 plan。任务卡仍须自包含、把裁定与口径写全; 禁用"纪律照旧""规矩同上"这类只有老搭档才懂的暗语(新人看不懂,等于没写)。 卡内只写给 actor 的执行指令,不写“待选择 actor / 待用户派发 / 暂勿派发”这类 仓库编制状态;这些状态只放支线 README 和架构师给用户的交接。卡首必须明确: “本卡被发送到当前 actor 会话即代表用户已完成选择与授权,直接执行;不要再选择、 派发或等待另一个 actor。”不得让同一段文字同时扮演调度台和施工 prompt。 默认派发权在用户:架构师负责写好可直接复制的自包含任务卡并交给用户,由 用户按跨模型额度和能力选择 actor;只有用户明确要求在当前 Codex 内派 subagent 时,架构师才可自行启动。不得把"合理下放"误解成默认消耗 Codex 同一额度。 任务卡写入仓库不等于已经交给用户派发:架构师在回复中必须用醒目标识明确写 “需要派发”或“暂勿派发”,给出卡的可点击路径,并用通俗语言说明这张卡解决什么、 为什么现在做、它依赖/阻塞哪一步;不能只在长汇报里顺带留一个文件名。 actor 严格按本批任务卡/plan 施工,只跑一次直接相关的最小自检并报告真实输出; 不得默认要求 actor 再开 reviewer subagent、重复一手审计、跑全量回归或自行做最终 验收;也不得反向一刀切禁止 actor 自行组织 subagent。架构师约束的是交付物、允许 文件、预算/API、证据与停工边界,不替 actor 规定内部执行拓扑;subagent 不得扩大 scope 或替代主 actor 对最终报告负责,发生实质性使用时须在回报中说明。plan 未覆盖 的情况停工写断点,交回架构师,不自行发散。 - 调查型 Codex subagent 的长期授权与验收(2026-08-25 用户裁定):架构师可主动把
有界、只读、可复核的调查交给当前工具面可用的
gpt-5.6-luna,并固定reasoning_effort=max;派发前先做真实能力探针,模型不可用时不得静默换名替代。该授权不 扩展到实现施工、真实 API 或外部副作用。调查 prompt 必须写清问题/决策、背景与当前裁定、 source/version、范围/非目标、覆盖方法、claim-evidence 收据和停工条件;不能只写“调查一下”。 subagent 回报默认只是候选事实,架构师按风险亲自抽锚后才可裁决;低风险且一手 locator 精确 时不默认再派 reviewer,source 冲突、全量/否定性断言、协议/隐私/metric/provenance/identity 等承重结论或不可廉价验证时,才追加一次窄范围、只读复核。完成依据是原始验收标准,不是 reviewer 是否终于沉默。 - 外部方案先解释、后裁决:参考第三方框架、作者 harness 或论文实现时,不能因其与当前 项目政策不同就把它当反例。先重建对方优化的目标、约束、invariant、estimand 与运行环境, 再分别写清它解决了什么、付出什么代价、哪些部分适合迁入本项目;比较的目的不是证明现行 方案正确,而是寻找更好的共同目标解。只有证据证明违反本项目不可退让边界时,才作否定裁决。
- 执行者报告完成不等于任务完成;验收以架构师复跑命令的输出为准,完成度 以 git log 为准,不以 actor 最后一条消息为准(额度耗尽时消息可能错乱)。 架构师负责关键 diff 审读、定向复跑、最终全量回归和状态冻结;“放慢”是 benchmark/ method 严格逐个推进,不是让 actor 与架构师重复生产同一份验收证据。
- 两本经验手册必须持续更新,不是只读不写(2026-07-08 用户强调):
architect-playbook.md(架构师经验,知错能改:裁定、被纠正的失误、第一手核查 手艺)+actor-handbook.md(actor 经验:好/坏行为判例)。接任的架构师/actor 的义务不止"读手册",还包括"用本会话的新经验更新手册"——每被用户纠正一次、 每踩一个坑、每发现一个更好的做法,都要落回对应手册,供下一任继承(这是把 "新项目"变"可快速上手"的关键)。 - 跨模型事实源:仓库内文档(
AGENTS.md/ 两本手册 / workstream 文档)是唯一、 模型无关的事实源。Claude 专属的~/.claude/projects/.../memory/只是 Claude 的便利缓存,不得存放仅此一处的项目真相——下一任架构师可能是 GPT/其他模型, 读不到该目录。凡继任者必须知道的(用户画像、协作约束、经验教训),仓库内文档 都要有落点,Claude memory 至多作镜像。 - 上下文不是持久记忆:Codex 上下文窗口有限且会压缩;对话里已经裁定但未落盘的
内容等同于尚未交接。每次用户拍板、验收阻断、派卡/回卡和架构裁决都应先写入活跃
workstream README 或对应 spec/note/手册,再依
git log恢复。冷启动才读architect-onboarding.md;同一会话压缩后只走下条热快照恢复,热快照失败才走四步兜底, 禁止把冷启动全文读序搬进 compact 恢复,也禁止凭残余摘要装作记得。 - 压缩恢复必须可自举:项目
.codex/hooks.json用SessionStart(source=compact)注入 hook 时刻的有界 Git 快照、唯一活跃 README 热胶囊 (没有in-progressP0 时注入 roadmap 空闲胶囊)、session_id与transcript_path;hook 首次/变更后须由用户在/hooks审核信任。 快照与胶囊一致时不重复读热层,只在承重细节缺失时定点读一份当前 note;生成失败或 hook 未加载时,本文才触发四步兜底:git status --short、git log -5 --oneline、 热胶囊、当前判据。会话 transcript 只证明“当时说过什么”,不得替代当前代码、数据或 裁决,也不得全文注入。hook 不自动修改项目文档;长期记忆仍必须在裁决/验收时落盘。 - 指标资格不是 method 的义务:每个 method × benchmark × metric 独立判 valid/N/A/pending;不能为了填满矩阵而伪造能力。变换输入 lineage 只证明“参与过 生成”,不等于当前 memory 仍语义承载每个 source fact,禁止直接拿它计算 Recall/NDCG;N/A 是诚实结果,不是接入失败。
硬规则
third_party/第三方代码允许修改(2026-07-05 用户放宽),但不得改变 算法核心流程;用途限于 benchmark 拓展适配(如 MemoryOS 原生只适配 LoCoMo) 和纯观测插桩。每处改动必须在对应 workstream 记录文件、位置和理由,可回溯。- 私有数据(gold answers、evidence、judge labels)绝不可达 method。
- 未经用户显式确认(预算、规模、run_id),不得调用真实 API;smoke 必须使用 当前已裁定的固定 method 主配置(包括上文 controlled embedding 政策),不得 为了省钱临时改算法参数;成本控制只通过 conversation/question/turn 规模裁剪。
- 不创建 method × benchmark 专用 runner;不合并不同 dataset variant 的 run。
outputs/是实验资产,outputs/memoryos-locomo-full-20260603/受保护;data/、models/、outputs/、third_party/benchmarks/不入 git。- 所有 Python 文件必须有中文模块 docstring;类/函数需要中文 docstring。
- 未经用户要求不自动 commit / push(架构师验收后 commit+push 是既定例外
模式)。commit 只 add 显式路径,禁
-A/.,commit 前git status --short过目(2026-07-14 事故:add -A把用户私人文件推进 公开 repo,force-with-lease 整改;Claude 本机与受信任的 Codex 项目层各有 advisory hook 提醒,但 Git/IDE、未信任项目及其他入口不受保护,纪律仍以本行为准)。 Co-Authored-By 用当前 模型真名。 - resume 逻辑、隐私边界、metric 正确性、公开协议变更必须经架构师 review。
文档规则
- 新任务先判断规模:一次会话内能完成的小修,记入当前 workstream 的任务清单;
需要独立 spec/plan 的,新建
docs/workstreams/ws<ID>-<name>/,ID 挂在父任务下 (如 ws02.1),目录内含 README.md(状态页)、spec.md、plan.md、notes/。 - 同一 workstream 内的支线一旦同时出现“取证/裁决 + actor 卡”,或预期还会有下一批,
必须收进
branches/<slug>/,由支线README.md管范围、文档索引与稳定依赖顺序, 任务卡放cards/、证据和裁决放notes/;一次性单文档仍可留在 workstream 原层。禁止为整理 旧历史而无边界地全仓搬家,但活跃支线不得继续把卡和 note 平铺到根目录。权威状态、 commit/test 快照与当前动作仍只写父 workstream README,不在支线 README 复制。 - 状态只写两处:本 workstream README(勾选 + 断点 + 验收证据)+
docs/roadmap.md索引表对应行(仅整体状态变化时)。 - **调查结论不能只留在聊天或孤立 note。**经架构师强验收后,benchmark 的稳定事实回填
docs/survey/{benchmarks,datasets,workflows}/,method 的稳定事实回填docs/reference/integration/<method>.md;完整一手命令、统计与争议保留在 workstream note, 并从docs/survey/README.md或docs/README.md可定位。只摘要承重结论,不把整份聊天/ note 重复倾倒到稳定页;发现新反证时同步更新稳定页并给旧判词加 superseded 链接。 - 调查资产按“候选事实 → 架构裁决 → 稳定事实”晋级:subagent 的原始证据、命令、覆盖与争议 先进入 workstream note;架构师裁决写清理由、适用范围与旧判词;只有验收后的机制摘要才进入 survey/integration 稳定页。论文机制卡还要记录 paper/source identity、可复用不变量与重读 触发器,避免既机械重读又把旧版本结论误当 current truth。
- 历史文档在
docs/archive/,只读;与现状冲突时以 workstream README 为准。
导航
docs/README.md— 文档地图与本地目录说明。docs/roadmap.md— Phase 1 目标、workstream 索引、全局约束、恢复流程。docs/workstreams/<ws>/README.md— 各任务线的状态页与当前断点。- 常用参考:
docs/reference/——新架构师上岗先读architect-onboarding.md; 另有架构、数据模型、method 接口清单、接入指南;docs/survey/(benchmark 调研 卡片)、CLAUDE.md(命令与代码结构速查)。
