agentmemory LongMemEval-S 基准测试：面向 AI 编程 Agent 的持久记忆检索能力评估

agentmemory LongMemEval-S 基准测试：面向 AI 编程 Agent 的持久记忆检索能力评估

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory

导读

本指南围绕 agentmemory 在LongMemEval-S学术基准上的检索评估展开，回答一个核心问题：当 AI 编码 Agent 需要在跨越约 48 个会话、约 115K token 的历史记忆中定位"哪个会话回答了这个问题"时，agentmemory 的检索系统能做到多好。读完本文你将掌握：LongMemEval-S 数据集的含义与构建方式、recall_any@K等评估指标的精确计算方法、BM25-only 与 BM25+Vector 混合检索的完整跑测流程，以及从 benchmark/longmemeval-bench.ts 源码到 benchmark/data/longmemeval_results_hybrid.json 结果文件的全链路复现方法。

LongMemEval（ICLR 2025，论文 arXiv:2410.10813）是评估聊天助手长期记忆能力的学术基准，覆盖 5 项核心能力：信息抽取、跨会话推理、时间推理、知识更新与拒答（abstention）。agentmemory 用它来验证自家 BM25 倒排索引与本地向量索引的混合检索在真实对话记忆上的召回表现。

基准配置总览

在正式解读数字之前，先明确本次评估的完整设定（见 benchmark/LONGMEMEVAL.md）：

两个要点值得注意：

1. 这是"检索召回"而非端到端问答准确率。官方 LongMemEval 排行榜指标是 QA 准确率（检索 + 生成答案 + GPT-4o 裁判），真实排行榜上的系统根据 LLM reader 的不同在 60–95% 之间，Oracle GPT-4o 约 82.4%。因此本文所有数字都应被理解为"在 LongMemEval-S 语料上的检索能力上限分析"，而不是 LongMemEval 官方分数。
2. 每题独立建索引。评估流程为：针对每个问题，从其约 48 个会话构建一个全新的索引，用问题文本执行搜索，然后检查 gold 会话 ID 是否出现在结果中（见 benchmark/longmemeval-bench.ts）。这保证索引规模、会话构成对所有系统完全一致，比较的是检索算法本身。

核心检索组件：三套源码实现

本次评估对比的三个检索系统，对应 agentmemory 源码中三个真实的索引/搜索实现，这也是评估能代表生产能力的根本原因。

BM25 关键词索引（SearchIndex）

BM25-only 模式直接使用 src/state/search-index.ts 中实现的SearchIndex类。这是一个经典的倒排索引实现，关键设计包括：

• BM25 打分公式：参数k1 = 1.2、b = 0.75（search-index.ts），IDF 采用平滑变体log((N - df + 0.5) / (df + 0.5) + 1)，避免负 IDF；
• 词干还原（Porter stemming）：所有 token 在索引与查询侧都会经过 src/state/stemmer.ts 中实现的 Porter 词干算法（stem()函数），例如复数、过去式、-ation、-ness等后缀被统一折叠；
• 同义词扩展：src/state/synonyms.ts 维护了 43 组领域同义词（如db/database/datastore、perf/performance/latency/throughput），查询词命中同义词组时以 0.7 的权重附加扩展项；
• 前缀匹配：基于排序词表做lowerBound二分查找，对查询词前缀命中额外计入 0.5 权重系数的 IDF 得分；
• CJK 支持：含 CJK 字符的 token 走 src/state/cjk-segmenter.ts 的分词路径而非词干还原（search-index.ts）。

索引字段覆盖观察（observation）的title、subtitle、narrative、facts、concepts、files与type（search-index.ts），即检索时不会遗漏记忆正文之外的元信息。

向量索引（VectorIndex）

向量模式使用 src/state/vector-index.ts 的VectorIndex，为每条观察保存{ embedding: Float32Array, sessionId }，搜索时对查询向量与库内所有向量计算余弦相似度（vector-index.ts），维护一个 Top-K 最小堆式的结果窗口。该模块还实现了validateDimensions维度守卫与 base64 序列化持久化——代码注释里特别记录了因 Node Buffer 池切片导致的"磁盘上出现幽灵 2048 维"崩溃问题（issue #455/#469/#584/#587），float32ToBase64显式传byteOffset+byteLength规避（vector-index.ts）。

本地嵌入提供者（LocalEmbeddingProvider）

嵌入由 src/providers/embedding/local.ts 的LocalEmbeddingProvider提供，通过@huggingface/transformers加载Xenova/all-MiniLM-L6-v2模型（dtype: "q8"量化，mean pooling + L2 归一化），输出 384 维向量，全程本地推理、无需 API Key（local.ts）。@huggingface/transformers在 package.json 中声明为 optionalDependencies，未安装时会抛出带安装提示的明确错误。

混合检索（HybridSearch）

hybrid 模式在 src/state/hybrid-search.ts 中实现，将 BM25、向量与图谱三路检索结果做加权 RRF（Reciprocal Rank Fusion）融合，RRF_K = 60，默认权重bm25Weight = 0.4、vectorWeight = 0.6、graphWeight = 0.3（hybrid-search.ts）。评估脚本构造 HybridSearch 时传入权重(0.4, 0.6, 0.0)并关闭重排，即严格对应 BM25+Vector 双流融合。

融合细节值得展开（hybrid-search.ts）：

• 每条候选的综合得分 = 各流weight / (RRF_K + rank)的加权和，除以"当前激活流的最大可达得分"做归一化，使单流命中也能保留配置权重、静默流不产生惩罚；
• 多流同时命中的候选获得AGREEMENT_BONUS = 0.05的多流一致加成；
• 随后按会话去重（每会话最多 3 条，diversifyBySession），再回填观察对象（enrichResults）。

评估脚本 benchmark/longmemeval-bench.ts 将每个会话的全部对话轮次拼接为role: content文本块（longmemeval-bench.ts），构造CompressedObservation后同时喂给 BM25 索引与向量索引，从而让三套检索在完全相同的观察语料上比较。

总体结果解读

核心结果如下表（完整 JSON 见 benchmark/data/longmemeval_results_hybrid.json 与 benchmark/data/longmemeval_results_bm25.json）：

值得强调的结论：

1. 混合检索与纯向量仅差 1.4pp（95.2% vs 96.6%），且两者使用完全相同的嵌入模型（all-MiniLM-L6-v2）——说明 BM25 关键词信号与向量语义信号高度互补而非冲突；
2. BM25 单独即有 86.2%——Porter 词干 + 同义词扩展的关键词检索在对话数据上的表现远强于直觉预期；
3. 向量给 BM25 带来 +9pp 的提升（86.2% → 95.2%），是任何单一组件贡献的最大增益，印证了混合检索的设计价值；
4. R@10 达 98.6%——几乎所有 gold 会话都能在前 10 条结果中找到，说明在真实召回场景下用户几乎不需要翻页。

需要再次强调的方法论边界（原文明确声明）：这些是检索召回率，不是端到端 QA 准确率；agentmemory不声称这些数字是"LongMemEval 官方分数"。

按问题类型的细粒度分析

混合检索（BM25+Vector）

BM25-only

结论提炼：

• 偏好（preference）类是最难类别：BM25 仅 60.0%、混合也只有 83.3%。这类问题要求理解隐式/间接表述（如"我不太喜欢 X 那种做法"），关键词无法直接命中，语义向量也受限于表达方式；
• 跨会话类（multi-session）与知识更新类（knowledge-update）最强：混合模式下 R@5 分别达 97.7% 与 98.7%、R@10 双双 100%。当事实分散在多个会话中时，混合检索的"多路召回 + 会话级去重"优势得到充分发挥；
• 对 BM25 而言，偏好类与 assistant 类是最弱项（60.0% / 80.4%），而 knowledge-update 却最好（92.3%）——知识更新问题通常含有明确的实体与关键词（如某 API 版本号变更），恰好是关键词检索的强项。

评估指标的计算口径

benchmark/longmemeval-bench.ts 中每个指标的实现都只有几行，值得逐一定义：

• recall_any@K：goldSessionIds中任一 ID 是否出现在retrievedSessionIds的前 K 条里（longmemeval-bench.ts）。注意"any"语义——只要命中任一 gold 会话即算成功，这与官方 LongMemEval 按答案会话粒度评分的口径一致；
• NDCG@10：以 gold 会话集合为相关集，按1 / log2(i + 2)的 DCG 衰减计算，再除以理想 DCG 归一化（longmemeval-bench.ts）；
• MRR：首个 gold 会话在检索结果中的排名的倒数（longmemeval-bench.ts）。

此外脚本对数据集做了预处理：排除 abstention（拒答）类问题（single-session-user_abs、multi-session_abs、knowledge-update_abs、temporal-reasoning_abs四类），共 500 道非拒答问题进入评估（longmemeval-bench.ts），这保证了"检索得到会话"这一事件对每个问题都是可判定的。

结果会写入benchmark/data/longmemeval_results_<mode>.json，包含per_type汇总与per_question逐题明细（gold ID、检索到的 Top-10 会话 ID），方便二次分析。

复现与运行指南

第一步：下载数据集

数据集约 264 MB，来自 Hugging Face 的xiaowu0162/longmemeval-cleaned：

pip install huggingface_hub python3 -c " from huggingface_hub import hf_hub_download hf_hub_download(repo_id='xiaowu0162/longmemeval-cleaned', filename='longmemeval_s_cleaned.json', repo_type='dataset', local_dir='benchmark/data') "

下载完成后文件位于benchmark/data/longmemeval_s_cleaned.json，评估脚本会从这里读取（longmemeval-bench.ts）。

第二步：运行 BM25-only 评估

npx tsx benchmark/longmemeval-bench.ts bm25

此模式不需要任何嵌入模型依赖，仅使用 src/state/search-index.ts 的纯关键词检索。运行约 500 道题，每处理 50 题会打印一次滚动recall_any@5进度。

第三步：运行 BM25+Vector 混合评估

npx tsx benchmark/longmemeval-bench.ts hybrid

hybrid 模式要求安装@huggingface/transformers（仓库中为 optionalDependencies，版本^4.2.0），脚本会动态导入 src/providers/embedding/local.ts 的LocalEmbeddingProvider来生成本地嵌入（longmemeval-bench.ts）：

npm install @huggingface/transformers

首次运行会自动下载Xenova/all-MiniLM-L6-v2模型（q8 量化版，约 23 MB），嵌入计算是入库时的一次性开销；搜索阶段在索引建好后是亚毫秒级（参见 benchmark/REAL-EMBEDDINGS.md 中的实测：双流检索平均延迟 2.39ms）。

运行前提

• Node.js ≥ 20（见 package.json 的engines字段）；
• 命令在仓库根目录执行，tsx由 devDependencies 提供（或使用npx tsx）；
• 完整运行 500 题需要一定时间（向量模式需为每题约 48 个会话生成嵌入），中途进度会持续打印，可放心观察。

生产环境中的启示

虽然 LongMemEval-S 评估的是独立索引上的检索能力，但它的结论与 agentmemory 的生产设计高度一致（见 benchmark/REAL-EMBEDDINGS.md 的对比评估）：

• 关键词 + 语义双路是性价比最高的组合：BM25 零依赖、零延迟成本，负责精确/实体类查询；向量负责语义类查询，两者融合后召回提升最显著（LongMemEval-S 上 +9pp，REAL-EMBEDDINGS 的 recall@10 也提升 8.2pp）；
• 本地嵌入是默认推荐：EMBEDDING_PROVIDER=local即可启用，无 API Key、无调用成本、无网络延迟；
• 检索深度影响很小：R@20（99.4%）相比 R@10（98.6%）仅提升 0.8pp，说明混合检索的前 10 条已经足够可靠——这正是生产系统中top_k默认值设计的经验依据。

延伸阅读

• benchmark/README.md：benchmark 目录总览，区分检索质量评估与负载测试两类数字；
• benchmark/REAL-EMBEDDINGS.md：真实嵌入（Xenova/all-MiniLM-L6-v2）在 30 个会话、20 个标注查询上的对比评估，含逐查询明细；
• benchmark/QUALITY.md 与 benchmark/SCALE.md：其他质量与规模维度的评估方法；
• src/state/search-index.ts、src/state/vector-index.ts、src/state/hybrid-search.ts：本次评估直接使用的三套检索实现源码；
• test/search-index.test.ts、test/hybrid-search.test.ts、test/vector-index.test.ts：对应组件的单元测试，可验证各项检索行为。

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory