mempalace

LoCoMo 在 llm_rerank_locomo() 运行之前，会将融合后的候选列表截断至 top-k。因此，重排序器只是对同一组 ID 重新排序，而 compute_retrieval_recall 仅评估证据集合的成员归属，忽略顺序。这就是为什么即使发起了 LLM 调用，使用与不使用 --llm-rerank 的运行也会产生完全相同的召回率。

解决方法：在仅测试召回率的 LoCoMo 运行中省略 --llm-rerank，例如：

python benchmarks/locomo_bench.py --granularity session --top-k 10 --mode hybrid

该标志会影响 LongMemEval 上的 R@k，因为那里的重排序发生在截断之前。要使其影响 LoCoMo 的召回率，需要对更大的候选池进行重排序，并在截断之前选出最终的 top-k 项。简单的“从候选池中挑选 k 个”提示词可能会降低多证据召回率，因此可以考虑保留融合结果的头部，仅让 LLM 填充尾部位置。CLI 帮助和 benchmarks/BENCHMARKS.md 已更新，以记录此限制。

在 3.8.0–3.10.0 版本以及 develop 分支中，mempalace/palace_graph.py 中的 create_tunnel() 会为每个隧道加载、扫描并重写整个 tunnels.json 文件。挖掘循环会反复调用它，导致时间复杂度呈平方级增长并产生过多的磁盘写入。

通过批量创建隧道来修复此问题：

1. 添加一个线程本地的 tunnel_batch() 上下文管理器，它会获取 mine 锁，仅加载一次 tunnels.json，并构建一个 id -> tunnel 索引。
2. 让 create_tunnel() 检测同一文件是否存在处于活动状态的批次，并通过索引以 O(1) 时间进行插入/更新，且每次调用后不再保存。
3. 在批次上下文退出时仅保存一次完整的隧道列表，最好放在 finally 中。
4. 用 with tunnel_batch(config): 包裹 entity_tunnels_for_wing()、compute_topic_tunnels() 以及 topic_tunnels_for_wing() 中的循环。
5. 在批次之外保留现有的"加载-修改-保存"路径，使 MCP 工具和用户显式创建的隧道行为保持不变。

参考实现：

_TUNNEL_BATCH = threading.local()

@contextmanager
def tunnel_batch(config=None):
    config = config or MempalaceConfig()
    tunnel_file = _get_tunnel_file(config)
    outer = getattr(_TUNNEL_BATCH, "state", None)
    if outer is not None and outer["file"] == tunnel_file:
        yield outer
        return
    with mine_lock(tunnel_file):
        tunnels = _load_tunnels(config)
        state = {
            "file": tunnel_file,
            "tunnels": tunnels,
            "index": {t.get("id"): t for t in tunnels if isinstance(t, dict)},
        }
        _TUNNEL_BATCH.state = state
        try:
            yield state
        finally:
            _TUNNEL_BATCH.state = outer
            _save_tunnels(state["tunnels"], config)

通过此更改，之前需要执行约 8.8k 次完整加载/保存循环的刷新操作变为一次加载和一次保存；报告中的示例耗时降至约 8 秒，其中主要耗时来自单次 JSON 转储。

该 bug 位于 backends/chroma.py 中的 ChromaCollection._lexical_search_via_sqlite。未过滤的 SQLite FTS5 查询在没有 ORDER BY 的情况下应用了 LIMIT，因此 SQLite 按 rowid/归档顺序返回匹配项。随后只对前 500 个匹配项进行 BM25 评分，而归档在后面的更优匹配项永远不会被纳入考量。

通过在应用数量上限之前对 FTS 候选结果进行排序来修复这个受限的查询：

SELECT e.id, e.embedding_id
FROM embedding_fulltext_search
JOIN embeddings e ON e.id = embedding_fulltext_search.rowid
WHERE embedding_fulltext_search MATCH ? AND c.name = ?
ORDER BY bm25(embedding_fulltext_search)
LIMIT ?;

对于 SQLite FTS5，bm25() 值越低越好。这与其他地方已经使用的 FTS 排名排序方式一致。然后对返回的窗口进行评分，并保留排名前 n_results 的结果。

针对受影响版本（如 v3.10.0）的即时临时解决方案：

1. 升级到包含 PR fix(search): rank the unfiltered lexical window before capping it 中修复的版本。
2. 如果在本地打补丁，请在 LIMIT 之前添加上述 ORDER BY bm25(...)。
3. 作为临时解决方案，传递一个 where 过滤器；该代码路径已经移除了 500 行的上限。
4. 或者，移除或增大 max_candidates=500，但这会增加查询开销，并且只有在新的上限能够覆盖所有匹配项时才有效。

增大 max_distance 并无帮助，因为缺失的抽屉从未进入词汇候选集或向量候选集。

在 mempalace 3.9.0/3.10.0 中,旧版 mempalace repair 路径在执行 _extract_drawers、check_extraction_safety 和 copy_palace_dir 期间不会持有 mine_palace_lock。由钩子启动的 mempalace mine 进程可以在该窗口期内获取此锁,导致修复随后以 MineAlreadyRunning 失败,并丢弃已提取/备份的数据。

永久修复方案:安装包含旧版修复补丁的版本,或修补 cli/cmd_repair.py,使从 backend.get_collection 到 _post_rebuild_cleanup 的整个操作都在以下代码块内运行:

with mine_palace_lock(palace_path):
    ...

它应在提取开始前捕获 MineAlreadyRunning,报告锁持有者并以非零状态码退出。Chroma 后端中按批次获取锁的操作在同一线程上是可重入的。

受影响版本上的即时解决方法:禁用启动 miner 的 Claude Code 钩子,确保没有 miner 正在运行,然后运行修复:

pkill -f 'mempalace mine' || true
mempalace repair --yes

如果无法禁用该钩子,则在整个修复过程中持续阻止 miner:

while true; do
  pkill -f 'mempalace mine' || true
  sleep 2
done &
killer=$!

mempalace repair --yes
rc=$?

kill "$killer"
exit "$rc"

残留的 locks/mine_palace_<hash>.lock 文件通常是无害的,因为 flock 会在进程退出时释放。只有在确认没有修复或 miner 进程仍在运行、且新的 miner 仍被拒绝启动之后,才可删除该文件。

将 MemPalace 升级到包含 PR #2593 的版本。此问题影响 MemPalace 3.9.0:MCP 服务器缓存的 ChromaDB 客户端在服务器自身写入后未更新其 chroma.sqlite3 的新鲜度时间戳,因此 mempalace_add_drawer、mempalace_check_duplicate 和 mempalace_diary_write 错误地将自身的写入视为外部更改,并重新加载了 HNSW 索引。使用 pip install --upgrade mempalace 进行更新,然后通过 pip show mempalace 确认已安装的版本包含 #2593。如果尚无可用的修复版本,请从 PR #2593 安装修补后的构建版本。搜索调用不受影响,因为 ChromaBackend 路径已在 #2307 中获得了自身写入的重新标记;应用补丁后,来自其他进程的写入仍会在下一次变更时被检测到。