MemPalace 基准评测复现指南：LongMemEval、LoCoMo、ConvoMem 三大记忆基准的完整跑法与源码解读

本篇围绕 MemPalace 仓库自带的基准评测复现指南（benchmarks/README.md），完整讲解三大 AI 记忆基准（LongMemEval、LoCoMo、ConvoMem）的数据准备、命令行跑法与预期结果，并结合评测脚本源码说明各检索模式、参数默认值与结果文件生成机制，帮助你在本地离线复现 MemPalace 的检索召回指标，并理解"逐字原文存储 + 向量检索"这一基线设计背后的评测方法论。

评测体系总览：三个基准各测什么

MemPalace 的基准目录（benchmarks/）围绕三个公开的对话记忆数据集构建，各自验证记忆系统的不同能力：

基准	测量目标	为什么重要
LongMemEval	能否在约 53 个会话中找出被埋藏的事实	基础检索质量——"大海捞针"式测试，AI 记忆领域的标准基准
LoCoMo	能否跨数周的多个对话把事实串联起来	多跳推理与时间推理能力
ConvoMem（Salesforce）	记忆系统在大体量下是否依然有效	覆盖全部记忆类型：事实、偏好、变化、拒答（abstention）

对应实现分别位于 benchmarks/longmemeval_bench.py、benchmarks/locomo_bench.py 与 benchmarks/convomem_bench.py。此外该目录还包含 benchmarks/mine_bench.py、benchmarks/membench_bench.py（MemBench 数据集评测）等补充脚本，以及 benchmarks/model_eval/ 子目录——后者是面向 LLM 候选模型的独立评测流水线（校准、实体抽取、记忆抽取、房间分类四类任务，含 10 种语言的 jsonl 数据集），与本篇的三个检索基准属于互补关系，可单独阅读 benchmarks/model_eval/README.md。

环境准备与运行前提

复现步骤极为轻量：克隆仓库后同步开发依赖即可。

# 克隆 MemPalace 仓库后进入目录
uv sync --extra dev   # 或: pip install -e ".[dev]"

根据文档声明，整套基准的运行前提是：

• Python 3.9+
• chromadb 是唯一依赖（基准脚本内部仅导入 chromadb 与少量标准库；切换高级嵌入模型时才需要额外的 fastembed）
• LongMemEval 数据约 300MB 磁盘
• 每个完整基准约 5 分钟（LoCoMo 与 ConvoMem 约 2 分钟）
• 不需要 API key、不需要 GPU、基准运行期间不需要联网（数据下载完成之后）

这是该评测设计的一个关键卖点：基线结果（raw 模式）在全链路——索引、检索、评分——中都不依赖任何 LLM 服务。

基准一：LongMemEval（500 题）

LongMemEval 是 AI 记忆领域的标准基准：每道问题对应约 53 个对话会话（haystack sessions），要求检索出标注过的答案会话。

数据下载与基本跑法

# 下载数据
mkdir -p /tmp/longmemeval-data
curl -fsSL -o /tmp/longmemeval-data/longmemeval_s_cleaned.json \
  https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_s_cleaned.json

# 运行 raw 模式（MemPalace 的 96.6% 主结果即来自该模式）
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json

# 运行 AAAK 压缩模式（84.2%）
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json --mode aaak

# 运行基于房间的加权模式（89.4%）
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json --mode rooms

# 先用 20 题做快速验证
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json --limit 20

# turn 级粒度
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json --granularity turn

预期输出（raw 模式，完整 500 题）：

Recall@5:  0.966
Recall@10: 0.982
NDCG@10:   0.889
Time:      ~5 minutes on Apple Silicon

评测循环的源码级机制

从 benchmarks/longmemeval_bench.py 的实现看，每道题的评测循环是：

1. 重建语料：从该题的 haystack_sessions 构建文档集合。--granularity session（默认）时把每个会话的全部 user 轮次拼接成一篇文档；--granularity turn 时每个 user 轮次单独成一篇，文档 ID 形如 sess_xxx_turn_N；
2. 全新集合：脚本使用共享的 chromadb.EphemeralClient()，并在每道题之间调用 _fresh_collection() 删除并重建集合，保证题目之间零状态污染（源码注释解释了这么做的原因：该版本 ChromaDB 的 EphemeralClient 实例之间共享状态）；
3. 入库与检索：以 doc_0, doc_1, ... 为 ID 写入集合，metadata 携带 corpus_id（真实会话 ID）与 timestamp，随后用问题原文做 collection.query()，按距离升序生成排序，未命中的文档补在排序末尾；
4. 自实现指标：Recall@k（标注会话是否进入 top-k）与 NDCG@k 在脚本内重新实现（evaluate_retrieval、ndcg、dcg 函数），刻意避免对 LongMemEval 官方代码的依赖。

完整的 --mode 列表与嵌入模型选项

README 展示了 raw / aaak / rooms 三种模式，而脚本的 --mode 实际支持 10 个取值：raw、aaak、rooms、hybrid、hybrid_v2、hybrid_v3、hybrid_v4、palace、diary、full。各模式的取舍逻辑（96.6% → 99.4% 的完整演进、每个改进对应的失败案例分析）详细记录在 benchmarks/BENCHMARKS.md，其中：

• raw：逐字会话文本 + ChromaDB 默认嵌入（all-MiniLM-L6-v2），零后处理——这就是 96.6% 的来源；
• aaak：入库前用 AAAK 方言压缩每个会话（对应 mempalace/dialect.py 的 Dialect.compress），查询仍用原始问题文本，用于检验压缩表示是否保留足够的语义信号——得分 84.2% 低于 raw，印证了"压缩会丢信息"的核心论点；
• rooms：入库前按主题关键词为每篇文档判定房间（technical / planning / decisions / personal / knowledge，与 mempalace/convo_miner.py 使用同一套关键词表），检索时先查问题所属房间再加权全局检索，得分 89.4%。

其他常用参数（均以脚本 argparse 定义为准）：

参数	默认值	说明
--granularity	session	session（每会话一篇）或 turn（每 user 轮次一篇）
--limit	0（全部）	只跑前 N 题，0 表示全量
--skip	0	跳过前 N 题，用于中途挂起后续跑
--hybrid-weight	0.30	hybrid 系列模式的关键词重叠加权；源码注释说明全量 500 题调参中 0.30 与 0.40 等价（噪声范围内）
--embed-model	default	default（ChromaDB 内置 all-MiniLM-L6-v2，384 维）、bge-base（768 维）、bge-large（1024 维，约 1.3GB）、nomic（768 维，约 274MB）、mxbai（1024 维）；非 default 需要 pip install fastembed，未安装时自动回退默认模型
--out	自动命名	结果 JSONL 路径

LLM 重排（可选）与训练/测试切分

--llm-rerank 会启用一个 Claude Haiku 重排通道（默认模型 claude-haiku-4-5-20251001，可用 --llm-model 切换为 claude-sonnet-4-6 或其他模型；--llm-backend ollama 可改走 Ollama 的 OpenAI 兼容端点，本地与 Ollama Cloud 均适用，--llm-base-url 可覆盖默认地址 http://localhost:11434）。API key 通过 --llm-key 传入，缺省回退到环境变量 ANTHROPIC_API_KEY。源码注释明确其定位："把 top-10 中最优会话提升到第 1 名，针对嵌入无法跨越的偏好类与术语密集类失败"。

脚本还内置了防止"对着测试集调参"的切分机制（对应仓库中已提交的 benchmarks/lme_split_50_450.json）：

# 一次性生成 50/450 开发集/留出集切分
python benchmarks/longmemeval_bench.py data/... --create-split --split-file benchmarks/lme_split_50_450.json

# 仅在 50 题开发集上迭代调参（可反复运行）
python benchmarks/longmemeval_bench.py data/... --mode hybrid_v4 --dev-only --split-file benchmarks/lme_split_50_450.json

# 最终评估——只在调参结束后运行（结果文件名带 _held_out 标记）
python benchmarks/longmemeval_bench.py data/... --mode hybrid_v4 --held-out --split-file benchmarks/lme_split_50_450.json

--dev-only 与 --held-out 必须搭配 --split-file 使用且互斥；--diary-cache / --skip-precompute 则服务于 diary 模式的会话摘要缓存，避免重复调用 LLM。

结果文件默认写入 benchmarks/results_mempal_{mode}[_{embed_model}][_llmrerank]_{dev|held_out}_{granularity}_{时间戳}.jsonl——目录中现有的 results_mempal_raw_session_20260414_1629.jsonl、results_mempal_hybrid_v4_llmrerank_session_*.jsonl 等文件正是该命名规则的真实产物。

基准二：LoCoMo（1,986 个 QA 对）

LoCoMo 测试 10 段长对话（每段 19–32 个会话、400–600 个对话轮次）上的多跳推理。

# 克隆 LoCoMo 数据集
git clone https://github.com/snap-research/locomo.git /tmp/locomo

# session 粒度（README 报告的 60.3% 结果）
python benchmarks/locomo_bench.py /tmp/locomo/data/locomo10.json --granularity session

# dialog 粒度（更难——48.0%）
python benchmarks/locomo_bench.py /tmp/locomo/data/locomo10.json --granularity dialog

# 提高 top-k（top-50 时 77.8%）
python benchmarks/locomo_bench.py /tmp/locomo/data/locomo10.json --top-k 50

# 只跑 1 段对话做快速验证
python benchmarks/locomo_bench.py /tmp/locomo/data/locomo10.json --limit 1

预期输出（session 粒度、top-10、全部 10 段对话）：

Avg Recall: 0.603
Temporal:   0.692
Time:       ~2 minutes

一个容易踩的坑：脚本默认 top-k 是 50

从 benchmarks/locomo_bench.py 的 argparse 定义看，--top-k 的默认值是 50（帮助文本："Top-k retrieval (default: 50)"）。而 README 预期的 60.3% 明确标注为 "session, top-10"，"77.8%" 则对应 top-50。因此若要精确复现 60.3% 这一基线数字，需要显式追加 --top-k 10；直接裸跑（不传 --top-k）得到的是 top-50 的约 77.8%。这一点在对比结果时必须留意，BENCHMARKS.md 的"诚实性"章节也特别指出：top-50 超过了每段对话的会话数上限，会使检索在结构上变成平凡的——可发布的诚实 LoCoMo 基线是 top-10 的 60.3%。

其他值得注意的脚本参数：

参数	默认值	说明
--mode	raw	可选 raw / aaak / hybrid（v5）/ rooms（关键词路由）/ palace（LLM 房间分配）
--granularity	session	dialog（每轮一篇）或 session（每会话一篇）
--llm-model	claude-sonnet-4-6	注意：LoCoMo 脚本重排默认模型与 LongMemEval 脚本（Haiku）不同
--palace-cache / --palace-model	— / Haiku	palace 模式的房间分配缓存路径与分配模型
--hybrid-weight	0.30	hybrid v5 的关键词重叠权重；v5 的改进点是从关键词中剔除双方说话人姓名（两段对话中每个会话都包含两个名字，包含它们会让所有会话获得同等加权）
--embed-model	default	default（ChromaDB 内置）或 BAAI/bge-large-en-v1.5（需要 fastembed）

脚本按 5 个类别分别统计召回：Single-hop、Temporal、Temporal-inference、Open-domain、Adversarial（CATEGORIES 字典，编号 1–5）。结果默认写入 benchmarks/results_locomo_{mode}[_llmrerank]_{granularity}_top{k}_{时间戳}.json，仓库中已提交的 benchmarks/results_locomo_raw_session_top10_20260414_1634.json 与 benchmarks/results_locomo_hybrid_session_top10_20260414_1649.json 即为 raw 与 hybrid 两种模式的对照样本。

基准三：ConvoMem（Salesforce，75K+ QA 对）

ConvoMem 覆盖六类对话记忆，数据集从 HuggingFace 自动下载，无需手动准备：

# 全部类别、每类 50 条（README 报告的 92.9% 结果）
python benchmarks/convomem_bench.py --category all --limit 50

# 单一类别
python benchmarks/convomem_bench.py --category user_evidence --limit 100

# 快速验证
python benchmarks/convomem_bench.py --category user_evidence --limit 10

可用类别： user_evidence、assistant_facts_evidence、changing_evidence、abstention_evidence、preference_evidence、implicit_connection_evidence

预期输出（全部类别、每类 50 条）：

Avg Recall: 0.929
Assistant Facts: 1.000
User Facts:      0.980
Time:            ~2 minutes

从 benchmarks/convomem_bench.py 的实现看，脚本从 HuggingFace 的 Salesforce/ConvoMem 数据集 core_benchmark/evidence_questions 路径拉取各类别数据，并支持 --category（六类任选或 all）、--mode（raw / aaak）、--cache-dir（默认 /tmp/convomem_cache）等参数；与另两个脚本不同，它的 --limit 默认值是 100、--top-k 默认 10，即裸跑时每个类别取 100 条、top-10 检索——复现 README 的 92.9% 需要显式传 --limit 50。已提交的结果文件 benchmarks/results_convomem_raw_top10_20260414_1649.json 记录了 raw 模式 top-10 的完整逐题结果。

结果文件：完全可审计

原始结果提交在 benchmarks/results_*.jsonl 与 benchmarks/results_*.json 中。每个文件包含每一道问题、每一条被检索到的文档、每一个分数——你可以逐题检查，而不只是看聚合指标。当前仓库中可见的真实结果文件包括：

• LongMemEval：results_mempal_raw_session_20260414_1629.jsonl（raw 基线）、results_mempal_hybrid_v4_held_out_session_20260414_1634.jsonl（留出集）、results_mempal_hybrid_v4_llmrerank_session_*.jsonl（Haiku 重排）
• LoCoMo：raw session top-10 与 hybrid session top-10 的 JSON 结果
• ConvoMem：raw top-10 全类别结果
• MemBench：results_membench_hybrid_all_movie_top5_20260414_1656.json

由于脚本是确定性的（固定数据集、无随机性、ChromaDB 嵌入可复现），相同数据 + 相同脚本每次运行得到相同结果；任何一次跑出的异常都可以从 JSONL 中定位到具体题目与会话。

评分口径：检索召回 ≠ 端到端问答准确率

理解这套基准数字的前提是口径：所有报告的分数（96.6%、60.3%、92.9%）都是检索召回（retrieval recall）——标注的正确答案会话是否出现在 top-k 检索结果里，而不是"LLM 基于检索结果生成的回答是否正确"。端到端 QA 准确率需要 LLM 生成答案并因此需要 API key，而这不属于免费基线评测的范围（见 benchmarks/BENCHMARKS.md 中"Notes on Reproducibility"一节）。这一区分在横向对比其他记忆系统时尤为重要：不同系统公布的可能是 QA 准确率而非检索召回，两者并不直接可比。

计划中的后续基准

README 还列出了三个规划中的方向：

• 规模测试：ConvoMem 在每条目 50/100/300 段对话下的表现
• Hybrid AAAK：用原文检索、交付 AAAK 压缩结果（兼得检索质量与交付体积）
• 端到端 QA：检索 + 生成答案 + 测量 F1（需要 LLM API key）

延伸阅读

• benchmarks/BENCHMARKS.md：从 96.6% 基线到各改进模式的完整记分演进、逐条失败案例的诚实性分析（含"对着测试集调参"的披露与 50/450 切分方案）、LoCoMo 各架构（Wings v2/v3、Palace v1/v2、hybrid v5）的分区明细
• benchmarks/HYBRID_MODE.md：混合评分（嵌入 + 关键词重叠 + 时间加权）的模式说明
• benchmarks/model_eval/README.md：LLM 候选模型评测流水线（四类任务、多语言数据集、评测报告与 CSV 结果）
• 嵌入模型与后端实现：mempalace/embedding.py、mempalace/backends/chroma.py

适用前提与限制：本文所有命令、参数默认值与预期结果均以当前仓库 benchmarks/ 目录的实际内容为准；预期耗时（"~5 minutes on Apple Silicon"、"~2 minutes"）为文档标注的参考值，不同硬件会有差异；LLM 重排类选项（--llm-rerank 等）需要有效的 API key 或本地 Ollama 服务，仅当你需要复现 99.4%/100% 档次的结果时才必须准备。