agentmemory 评测体系完全指南用 LongMemEval 与 coding-agent-life-v1 量化混合记忆检索栈【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory 的评测框架eval/为混合记忆检索栈BM25 向量嵌入 consolidation 记忆整合 图检索提供了一套可复现、可比较的量化基准一条基于公开 LongMemEval 500 问检索基准的公共对比轴一条基于 15 个虚构 Claude Code 会话语料的内部快速迭代轴。读完本文你将掌握如何安装沙箱、运行两类评测、解读 PK / RK / 命中率等指标、对照 grep 与 OpenAI 向量基线验证每一层检索的价值并学会为自定义后端编写新的 Adapter。评测框架的定位为什么 agentmemory 需要一套基准agentmemory 的记忆栈不是单一检索器而是由多层级联组成BM25 词法检索、嵌入向量检索、consolidation 记忆整合以及图检索graph retrieval共同服务于smart-search端点。正如 eval/README.md 所陈述的这些层级带来的数值提升必须能被证明——将整个栈与 grep 字符串匹配、OpenAI 向量检索这两种基线对比每个组件对最终召回率的贡献才可量化而不是停留在感觉更好的层面。因此仓库提供两套互为补充的评测族且都强调可复现reproducibleLongMemEval公开的 500 问多会话聊天检索基准负责对外部公开结果的横向对比coding-agent-life-v1仓库内置的虚构语料覆盖单会话、多会话因果推理、用户偏好与时间线问题用于在不花费外部 API 费用的情况下快速迭代。两套评测共用同一套 Runner 与打分逻辑差异仅在于数据来源见 eval/runner/coding-life.ts 与 eval/runner/longmemeval.ts。三个 Adapter基线、向量与完整记忆栈评测通过统一接口比较不同检索后端接口定义在 eval/runner/types.tsexport interface AdapterState unknown { name: string; init(sessions: Session[], config?: Recordstring, unknown): PromiseState; query(q: string, state: State, k: number): PromiseRankedDoc[]; teardown?(state: State): Promisevoid; }三个内置 Adapter 由 eval/runner/longmemeval.ts 与 eval/runner/coding-life.ts 中的ADAPTERS映射表注册Adapter后端所需 API Key说明grep分词子串匹配无纯词法基线零成本、零外部依赖vectorOpenAItext-embedding-3-small 余弦相似度OPENAI_API_KEY纯向量基线用于衡量语义检索相对词法匹配的提升agentmemory运行中的 agentmemory 服务走smart-search端点无可选AGENTMEMORY_SECRET完整的混合记忆栈实际评测名称是agentmemory-hybridgrep最简单的词法基线grep.ts 的实现非常直白将查询串小写化、过滤掉长度 ≤2 的 token然后在每个会话正文中统计命中的词项数并据此排序。它的价值在于给出只做词法匹配、零语义理解时的下限任何声称有价值的记忆层都应稳定超越它。vectorOpenAI 嵌入 余弦相似度vector.ts 使用text-embedding-3-small维度 1536init阶段按每批 50 条会话批量编码每条内容截断至 8000 字符查询阶段对问题单独编码后与全部会话向量计算余弦相似度排序。注意init会立即抛出OPENAI_API_KEY required错误因此运行 vector Adapter 必须显式提供密钥。agentmemory走生产级 smart-search 端点agentmemory.ts 是最接近真实使用路径的 Adapterinit阶段逐条调用POST /agentmemory/remember将每个会话写入记忆存储type: eval-session并以会话 ID 作为 concept同时建立记忆条目 ID → 会话 ID的映射query阶段调用POST /agentmemory/smart-searchlimit取max(k*10, 50)把返回的观测结果去重后映射回会话 ID。由于走的是生产端点它实际锻炼的是 BM25 嵌入 重排的完整链路。该 Adapter 默认连接http://localhost:3111可通过AGENTMEMORY_BASE_URL环境变量或config.baseUrl覆盖可选AGENTMEMORY_SECRET以 Bearer 方式鉴权。先沙箱后评测隔离你的真实记忆库运行agentmemoryAdapter 会向运行中的服务写入 15 个或 LongMemEval 的数百个评测会话——如果直接连你的真实~/.agentmemory会同时造成两个方向的污染评测结果被既有记忆干扰真实记忆库被评测数据污染。因此官方文档明确要求Always sandbox始终沙箱化。仓库提供了 eval/scripts/sandbox.sh 一键完成隔离在3411/3412端口启动干净的 agentmemory iii-engine状态存放在/tmp/agentmemory-eval-sandbox/下该脚本强制要求SANDBOX_ROOT非空且位于/tmp/下否则拒绝执行自动导出AGENTMEMORY_BASE_URL指向沙箱脚本退出EXIT trap时自动销毁。source eval/scripts/sandbox.sh npm run eval:coding-life -- --adapters grep,agentmemory脚本要求iiiv0.11.2 位于 PATH 上agentmemory 的固定版本且要求仓库已构建缺少dist/index.mjs时会提示先执行npm run build。如果你已安装其他版本可将固定版本装入~/.local/bin并确保该目录在 PATH 最前mkdir -p ~/.local/bin curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin export PATH$HOME/.local/bin:$PATH # 持久化可加入 ~/.zshrc 或 ~/.bashrc从源码看沙箱通过生成的iii-config.yaml配置了iii-httpHTTP 端口 3411、iii-state基于文件的 KV 存储、iii-queue、iii-pubsub、iii-cron、iii-stream流端口 3412与iii-exec启动node dist/index.mjs等 worker并轮询/agentmemory/livez等待就绪30 秒内未就绪则打印日志尾部并退出。快速上手两条评测路径coding-agent-life-v1内置语料无需下载# 仅跑 grep 基线不需要沙箱 npm run eval:coding-life -- --adapters grep # 叠加 agentmemory 与 vector需要沙箱 OpenAI Key source eval/scripts/sandbox.sh OPENAI_API_KEYsk-... npm run eval:coding-life -- --adapters grep,vector,agentmemory该语料位于 eval/data/coding-agent-life-v1/包含sessions.json15 个虚构的 Claude Code 会话约 6KB主题是一个名为shipctl的 Rust CLI 项目queries.json15 条人工评分的问题每条带goldSessionIds正确答案所在会话 ID。从 queries.json 可以看到问题类型覆盖相当全面single-session-bug如 q-001 认证环境变量优先级修复、single-session-infra、single-session-refactor、single-session-feature、single-session-test、single-session-perf、single-session-api、single-session-db、single-session-release、multi-session-causal如 q-011 追查 staging 事故根因需横跨 sess-001 与 sess-014、preference如 q-013 用户的格式化偏好、multi-session-review与temporal如 q-015 2026 年 4 月 8 日发布了什么。Runner 支持三个额外参数见 coding-life.ts 的 CLI 解析--data数据目录默认eval/data/coding-agent-life-v1、--k截断深度默认 5、--out报告输出目录默认eval/reports/coding-life。LongMemEval_s公开基准278MB 下载mkdir -p ~/datasets/longmemeval curl -Lo ~/datasets/longmemeval/longmemeval_s.json \ https://huggingface.co/datasets/xiaowu0162/longmemeval/resolve/main/longmemeval_s source eval/scripts/sandbox.sh # 每类分层抽样 10 条快速迭代OpenAI 花费约 $0.20 OPENAI_API_KEYsk-... LONGMEMEVAL_PATH~/datasets/longmemeval/longmemeval_s.json \ npm run eval:longmemeval -- --stratify 10 # 完整 500 问 × 3 个 AdapterOpenAI 花费约 $2 OPENAI_API_KEYsk-... LONGMEMEVAL_PATH~/datasets/longmemeval/longmemeval_s.json \ npm run eval:longmemevalload.ts 负责把 LongMemEval 原始 JSON 转换为内部Question结构每个会话的[{role, content}]轮次被扁平化为[role] content文本并校验haystack_session_ids与haystack_sessions长度一致stratifySample则按问题类型分桶后每类取前 N 条保证快速迭代时覆盖所有题型。Runner 额外支持--limit截断问题总数与--stratify每类抽样数--data缺省时直接读取LONGMEMEVAL_PATH。打分与指标解读PK、RK、命中率与 p50 延迟打分逻辑集中在 score.tsPKPrecisionK取前 K 个检索结果其中命中 gold 会话的比例hits / k逐问平均RKRecallK前 K 个结果覆盖全部 gold 会话的比例hits / gold.size逐问平均Hit命中率是否至少有一个 gold 会话进入前 KtopGoldRank第一个 gold 会话在完整排序中的位次1-based用于观察 gold 是否被排到很后面latencyMs单次查询耗时聚合时按 Adapter 计算p50 延迟。每条问题的逐行结果以 NDJSON 写入scores.ndjson字段含questionId、questionType、adapter、k、precisionAtK、recallAtK、hit、topGoldRank、latencyMs聚合结果写入summary.json包含按 Adapter 与按问题类型的 P/R/hit 汇总。理解 PK 的数学上限很重要以 coding-agent-life-v1 为例15 问中 12 问只有 1 个 gold 会话、3 问有 2 个因此 P5 的理论上限是(12×1/5 3×2/5)/15 0.240。正如已发布的记分卡 docs/benchmarks/2026-05-20-coding-agent-life-v1.md 指出的该语料刻意设计得小而 gold 稀疏目的是快速迭代检索栈而非比拼 PK 头条数字核心信号是 Recall 与按题型拆分的 P5而 LongMemEval 提供的就是那个公共对比轴。报告落盘位置eval/reports/bench/已被 gitignore即scores.ndjsonsummary.json正式发布的记分卡则放入docs/benchmarks/YYYY-MM-DD-bench.md。写入与复现一份已发布的记分卡样本仓库已发布基于上述框架产出的示例记分卡 docs/benchmarks/2026-05-20-coding-agent-life-v1.md其运行环境为 agentmemory v0.9.26 iii-engine v0.11.2本地默认嵌入提供方沙箱端口 3411/3412。结果摘要K5AdapterP5R5命中率p50 延迟grep分词子串0.2270.96715/150 msagentmemory-hybrid0.2401.00015/1514 ms解读要点agentmemory-hybrid的 R5 达到 1.000P5 0.240 恰好处于该数据集的数学上限所有 gold 会话均进入 top-5grep 基线的 R5 0.967在某道多 gold 问题上漏掉了 1 个会话。提升体现在召回而非聚合精度——这正是该评测体系想展示的效果完整的混合记忆栈相对纯词法基线主要价值在于更稳地把正确答案捞回 top-K。该记分卡也明确提示此基准体量小15 问、gold 稀疏不应拿来做头条 PK 对比。编写新 Adapter三步接入自己的检索后端任何自定义检索后端都能以 Adapter 形式接入评测官方文档给出完整模板import type { Adapter } from ../types.js; export const myAdapter: AdapterMyState { name: my-adapter, async init(sessions, config) { /* index */ return state; }, async query(q, state, k) { /* search */ return ranked; }, };接入步骤在 eval/runner/adapters/ 下按AdapterState接口实现query返回按相关性降序的RankedDoc[]{ sessionId, score }在 eval/runner/longmemeval.ts 与 eval/runner/coding-life.ts 的ADAPTERS映射表中注册即可通过--adapters指定先在 coding-agent-life-v1 上冒烟验证正确性再投入 OpenAI 花费跑 LongMemEval。从源码看可复用的细节vector展示了带批处理与维度校验的init写法agentmemory展示了写入索引 记录 ID 映射 查询去重映射回会话的完整状态机模式scoreQuestion对空 gold 集返回 RK 0 的边界处理也可作为实现参考。另外仓库在 test/eval-adapters.test.ts 与 test/eval.test.ts 中对适配器与评测流程有对应测试可作为行为契约参考。评测体系仓库结构速览eval/ ├── README.md ├── runner/ │ ├── types.ts Adapter、Question、RankedDoc、ScoreRow 类型 │ ├── score.ts PK、RK 计算与聚合 │ ├── load.ts LongMemEval JSON → Question[] │ ├── adapters/ │ │ ├── grep.ts 分词子串匹配基线 │ │ ├── vector.ts OpenAI 嵌入 余弦 │ │ └── agentmemory.ts POST /agentmemory/{remember,smart-search} │ ├── longmemeval.ts 公开基准 Runner │ └── coding-life.ts 内部基准 Runner ├── scripts/ │ └── sandbox.sh 沙箱化启动与销毁 └── data/ └── coding-agent-life-v1/ ├── sessions.json 15 个虚构会话约 6KB └── queries.json 15 条带 gold 会话 ID 的问题两条 npm 脚本见 package.json对应两个 Runnernpm run eval:coding-life与npm run eval:longmemeval均通过tsx直接执行 TypeScript。总结如何用这套框架量化你的记忆层agentmemory 评测体系的设计哲学是每层价值可证明grep给出词法下限vector给出纯语义基线agentmemory给出完整生产链路三者在同一批问题上、以同一套 PK / RK / hit / 延迟指标横向对比。内部语料小到几秒跑完、免费可复现适合开发期快速迭代LongMemEval 体量大、题型全适合发布前产出可与公开结果对照的记分卡。任何想接入的检索后端遵循Adapter接口三步即可纳入这套评测体系。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考