MemPalace 修正记录全解：docs/HISTORY.md 如何治理一个开源项目的基准声明

MemPalace 仓库中的 docs/HISTORY.md 是该项目上市后所有"修正、撤回与公开公告"的权威记录（canonical record），按时间倒序归档了三条关键公告：2026-04-14 的基准表重写、2026-04-11 的仿冒域名警告、2026-04-07 的项目组公开致歉与纠错说明。本文以这份文档为骨架逐条展开，并结合仓库中 README.md 的当前基准表、CHANGELOG.md 的变更记录、benchmarks/ 目录下已提交的复现结果文件，说明这些修正在代码库中如何真正落地，以及如何验证一个记忆系统的检索数字是否"干净、诚实、可复现"。

这份记录在仓库中的定位：为什么修正要独立成文

HISTORY.md 开头就声明了自己的定位："This file is the canonical record of post-launch corrections, public notices, and retractions that affect MemPalace's public claims."（本文件是影响 MemPalace 公开声明的修正、公告与撤回的权威记录，最新在前。）

从 CHANGELOG.md 可以看到这一文档化的来龙去脉：在 2026-04-14 的整改中，项目组明确"将 docs/HISTORY.md 新增为修正、撤回与公开公告的权威存放处；把 2026-04-07 的『Milla & Ben 的说明』和 2026-04-11 的仿冒域名公告从 README.md 中迁出"。换言之，README 只保留"当前仍然成立"的声明，而所有"我们曾经说错过什么、现在改成了什么"全部沉淀到 HISTORY 中。这种把"纠错史"与"产品页"分离的做法，是本文值得学习的第一点。

2026-04-14：基准表重写——一次由社区审计触发的系统性修正

这是 HISTORY.md 中篇幅最长、信息密度最高的一条公告，对应社区审计 issue #875。它指出了一个类别错误（category error）：MemPalace 在 README.md 与官方文档站上把自身的检索召回率（R@5、R@10）与竞品发布的端到端 QA 准确率放在同一列对比。这是两种完全不同的指标，不可直接比较——"一个系统可以拥有 100% 的检索召回率，同时只有 40% 的 QA 准确率"。

审计还发现了另外两个问题：

• 已撤回的 "+34% palace boost" 声明（见下文 2026-04-07 公告）在撤回后仍残留在多个页面；
• 两个竞品数字（Mem0 ~85%、Zep ~85%）没有任何已发布来源，也与这些项目实际发布的指标不符。

本次整改具体改了什么（原文档六项变更全记录）

HISTORY.md 完整列出了整改 PR 的六项变更，下面逐条继承并补充仓库佐证：

1. 所有页面的头条数字统一为"raw 模式下 LongMemEval 96.6% R@5"，并且该数字于 2026-04-14 在 Linux x86_64 上针对打标签的 v3.3.0 发布版独立复现。复现的结果 JSONL 已提交到 benchmarks/results_*.jsonl。在仓库中可以直接核对这些文件，例如 results_mempal_raw_session_20260414_1629.jsonl、results_mempal_hybrid_v4_held_out_session_20260414_1634.jsonl、results_mempal_hybrid_v4_llmrerank_session_20260414_1654.jsonl 与 results_mempal_hybrid_v4_llmrerank_session_20260414_1659.jsonl——文件名中的日期戳 20260414 与公告日期精确对应。从文件内容看（每行一个 question 的 question_id、question、answer 与 retrieval_results.ranked_items 全量排序列表），这些结果文件是逐题可审计的，而非只存一个聚合分数。
2. "100% with Haiku rerank" 声明从所有公开对比表中移除。 公告给出的理由值得细读：该结果确实在项目方机器上可复现，且用另一个 LLM 家族（通过 Ollama Cloud 的 minimax-m2.7）也能复现（完整 500 题 LongMemEval 上 99.2% R@5 / 100.0% R@10）——但 99.4% → 100% 的最后一步是通过检查三个具体错误答案调试出来的，benchmarks/BENCHMARKS.md 自 2 月起就把这种做法称为 "teaching to the test"（面向测试调参）。它属于方法论文档，不属于头条数字。
3. 混合管线的"诚实留出数字"成为新的可比口径：hybrid_v4 在 450 道从未参与其调优的问题上取得 98.4% R@5，使用确定性种子。当涉及 LLM rerank 的对比时，这才是应被引用的数字。这 450 题的划分文件就是仓库中的 benchmarks/lme_split_50_450.json——打开可见其结构为 dev（50 题，可安全用于迭代调优）与 450 题留出集，由 benchmarks/longmemeval_bench.py 的 --create-split / --dev-only / --held-out 参数配合使用（脚本支持 --limit、--mode、--out 等完整 CLI 参数，见该文件末尾的 argparse 定义）。
4. 撤回的 "+34% palace boost" 已从 README.md、website/concepts/the-palace.md、website/guide/searching.md、website/reference/contributing.md 全部移除。 公告保留了建设性表述：wing（翼）与 room（房间）过滤仍然有用——它们是标准的元数据过滤手段——但不再被呈现为"新颖的检索改进"。
5. 混用检索召回与 QA 准确率的竞品对比表从 README.md 和 website/reference/benchmarks.md 移除。 现在的原则是：只有当 MemPalace 能在同一指标上公平比较时，才链接到被引用的来源；否则只报告自己的数字，让读者自行判断。这一点在 README.md 的 "Benchmarks" 一节可以验证——当前 README 明确写道"我们刻意不包含与 Mem0、Mastra、Hindsight、Supermemory、Zep 的并排对比"，并解释原因正是"检索召回与端到端 QA 准确率放在不同 split 上对比不是诚实的比较"。
6. LoCoMo "top-50 rerank 下 100% R@10" 一行从公开对比面移除。 公告的技术理由非常硬核：LoCoMo 每条对话的 session 数为 19–32，而 top_k=50 时检索阶段在结构上会返回该对话的全部 session，于是这个数字度量的其实是"LLM 对整段对话的阅读理解力"，而不是检索能力。

公告最后向提交审计的社区成员致谢，并感谢了平行整理的 Discussion。这条公告的价值在于：它展示了一个团队如何把"数字从哪来、为什么不能比、撤回后改成了什么"三件事一次性交代清楚。

2026-04-11：仿冒域名与恶意软件公告

第二条公告短小但属于安全类通知。多个社区成员（issues #267、#326、#506）报告了分发恶意软件的仿冒 MemPalace 网站。公告声明该项目的唯一官方入口只有三个：

• GitHub 仓库（github.com/MemPalace/mempalace）；
• PyPI 包 mempalace（pypi.org/project/mempalace）；
• 文档站 mempalaceofficial.com。

其余任何域名——被报告最多的为 mempalace.tech——均不属于项目方。公告给出唯一行动建议：永远不要运行来自非官方站点的安装脚本。这一条对读者是硬性的安全边界：安装 MemPalace 只应走 PyPI 或官方仓库源码，文档与代码以仓库内 pyproject.toml、README.md 为准。

2026-04-07：Milla & Ben 的说明——逐项承认错误的公开信

这是最早的一条公告，形式是项目组两位作者（Milla Jovovich 与 Ben Sigman）以引用块写下的公开信。核心叙事是："社区在发布数小时内就在 README 中发现了真实问题，我们想直接回应。"

承认错误的五项内容（原文档全记录）

1. AAAK token 示例错误。 早期 README 用粗略启发式（len(text)//3）估算 token 数，而不是真实 tokenizer。经 OpenAI tokenizer 实测：英文示例是 66 tokens，AAAK 示例是 73 tokens。结论是 AAAK 在小规模下并不省 token——它的设计目标是"大规模下的重复实体压缩"，README 中的例子是个糟糕的演示。项目方承诺重写该示例。
2. "30x lossless compression" 说法夸大。 AAAK 是一个有损缩写系统（实体编码、句子截断）。独立基准显示 AAAK 模式在 LongMemEval 上得分 84.2% R@5，对比 raw 模式的 96.6%，存在 12.4 个点的回退。诚实的表述是：AAAK 是一个以保真度换 token 密度的实验性压缩层，且 96.6% 的头条数字来自 RAW 模式，不是 AAAK。这一数字与 benchmarks/README.md 中 --mode aaak 的复现说明（84.2%）相互印证。
3. "+34% palace boost" 具有误导性。 该数字比较的是无过滤检索与 wing+room 元数据过滤。而元数据过滤是底层向量存储的标准功能，不是新颖的检索机制。"真实且有用，但不是护城河（not a moat）"。
4. "矛盾检测"（contradiction detection）名不副实。 它作为一个独立工具（fact_checker.py）存在，但并未如 README 所暗示的那样接入知识图谱操作。对应仓库源码 mempalace/fact_checker.py，其"独立工具"状态与公告描述一致。
5. "100% with Haiku rerank" 结果真实（有结果文件），但 rerank 管线当时不在公开基准脚本中，承诺补入。

仍然成立且可复现的内容

公告同时保留了"仍然为真"的部分，避免矫枉过正：

• raw 模式下 LongMemEval 96.6% R@5，500 题、零 API 调用——由社区成员在 M2 Ultra 上 5 分钟内独立复现；
• 本地、免费、无订阅、无云、数据不出机器；
• 架构本身（wings、rooms、closets、drawers）是真实且有用的，只是不是"魔法检索增益"。

当时承诺的四项整改

1. 用真实 tokenizer 计数、并在 AAAK 真正能体现压缩的场景下重写 AAAK 示例；
2. 在基准文档中明确加入 mode raw / aaak / rooms，让权衡可见；
3. 把 fact_checker.py 接入 KG 操作，使"矛盾检测"的声明成真；
4. 将向量存储依赖固定到已测试的版本范围（issue #100）、修复 hooks 中的 shell 注入（#110）、处理 macOS ARM64 段错误（#74）。

这四项在仓库中都有对应痕迹：benchmarks/README.md 的复现指南已明确列出 --mode aaak、--mode rooms 等模式开关与各自的预期分数；hooks 目录（hooks/ 下的 shell 脚本）随后经过了多轮加固（见 tests/test_hooks_shell.py、tests/test_hooks_bash_compat.py 等测试文件对 shell 兼容性与注入防护的覆盖）。

交叉验证：从 HISTORY.md 到仓库证据链

三条公告共同指向一套"诚实基准"方法论，仓库中留下了完整的验证链条。

1. 头条数字与当前 README 一致

README.md 的 Benchmarks 一节当前呈现的是整改后的口径：

模式	R@5	需要 LLM
Raw（语义检索、无启发式、无 LLM）	96.6%	无
Hybrid v4，留出 450 题（在 50 题 dev 上调优，训练期间未见）	98.4%	无
Hybrid v4 + LLM rerank（完整 500 题）	≥99%	任意有能力的模型

并且 README 明确说明"我们不为 '100%' 数字做头条，因为最后 0.6% 是通过检查具体错误答案达到的，benchmarks/BENCHMARKS.md 将其标记为面向测试调参"。这与 HISTORY.md 的整改第 2、3 条完全对应。

2. 结果文件可逐题审计

benchmarks/BENCHMARKS.md 在 "Notes on Reproducibility" 一节定义了审计标准：每个 benchmarks/results_*.jsonl 都包含每一道题、每一个被检索文档、每一个分数，"你可以检查每一个单独的答案——而不只是聚合值"。其 "Benchmark Integrity — The Honest Accounting" 一节甚至点名了三个被特判修复的 LongMemEval 问题（d6233ab6 引号短语题、4dfccbf8 Rachel/ukulele 时间题、ceb54acb 高中重聚偏好题），并直言"这是 teaching to the test……在同行评审论文中这是重要的方法论问题，我们在此披露它而不是让它不被审视"。

3. 复现路径仍然有效且指向正确仓库

整改第 6 条之外的细节：原复现说明曾指向已废弃的分支（aya-thekeeper/mempal），现已改指 MemPalace/mempalace。benchmarks/README.md 给出了完整可执行的复现路径：

# 安装开发依赖（uv 或 pip 二选一）
uv sync --extra dev   # 或: pip install -e ".[dev]"

# 下载 LongMemEval 数据后运行 raw 基线（96.6% 头条数字）
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json

# 快速验证：只跑 20 题
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json --limit 20

预期输出（raw 模式、完整 500 题）为 Recall@5: 0.966 / Recall@10: 0.982 / NDCG@10: 0.889，约 5 分钟（Apple Silicon）。要求是 Python 3.9+、chromadb 单一依赖、无需 API key、基准运行期间无需联网。

4. 训练/测试划分是方法论的落点

HISTORY.md 所说的"确定性种子 450 题留出"，在仓库中对应 benchmarks/lme_split_50_450.json（seed=42，CHANGELOG 亦记载该文件与 v3.3.0 复现 JSONL 一并为本次整改提交）。BENCHMARKS.md 的使用约定是：50 题 dev 集可以反复调优；450 题留出集"只碰一次"——看到留出结果后再次迭代会污染它。这套约定让"98.4% 是诚实的泛化数字"这句话具备了可执行的验证方式。

三条公告的共同启示

1. 指标口径先于指标数值。R@5 检索召回与 QA 准确率是两种度量，混排一列就构成类别错误；引用任何系统数字前，先确认它度量的是什么、在哪个 split 上测的。
2. 撤回要撤干净。"+34% palace boost" 的教训是：撤回声明后仍残留在多页面上的旧说法，比从未说过更损害信任——因此需要一份 HISTORY 作为权威记录，并逐表面（README、概念页、搜索指南、贡献指南）清理。
3. 安全面最小化。仿冒域名公告的本质是给出"唯一官方入口白名单"：仓库、PyPI 包、文档站三处，其余一律不信任，尤其不要运行来路不明的安装脚本。
4. 纠错可以成为文档资产。把"我们哪里说错了、为什么错、现在改成什么、如何复现"沉淀为 docs/HISTORY.md，配合 CHANGELOG、已提交的结果 JSONL 与划分文件，构成了一条从声明到证据的完整链条。