← 回到报告集合
V|Memory Search vs Wiki|0612

Memory Search 升级复盘

这次 task room 把 V 的 memory 从“能搜到一些日志”推进到更清晰的 Memory OS:canonical markdown / LLM wiki 是事实层,Gemini vector 是高召回 sidecar;同时现场修掉 full vector reindex 暴露出的 sqlite metadata 与 stale fd 双 bug。

Hit@5 从 16.7% 到 66.7%
821active memory files after cleanup
2reindex bugs fixed locally
Thesis

不是“向量库替代记忆”,而是让记忆有一个更好的雷达

最终架构判断很清楚:truth layer 仍然是人可读、可治理、可 promotion/deprecation 的 markdown / wiki / structured memory;向量检索只负责在问题模糊、关键词不准、旧决策藏在项目笔记里时,把可能相关的线索拉上来。

Benchmark

FTS vs Gemini vector/hybrid

24 个真实 memory 问题的对比显示:Gemini sidecar 明显提高召回质量,代价是约 1.4s / 17% 的额外延迟;这个 trade-off 对 V 的日常 recall 是值得的。

FTS / provider:none

8.3%Hit@116.7%Hit@316.7%Hit@54.75Noise@5

Gemini vector / hybrid

41.7%Hit@158.3%Hit@366.7%Hit@53.5Noise@5
结论:保留 Gemini vector/hybrid,作为 fuzzy decision/TODO sidecar;不要把它当唯一事实源。
Timeline

Task room 时间线

Memory Search vs Wiki 方向确认:向量不做 truth layer,而做 fuzzy clue-discovery sidecar;canonical markdown / LLM wiki / structured index 保持事实源。

清理 active memory imports 污染:raw snapshot 不再 materialize 到 active memory/imports/sources,索引从约 4785 文件 / 22348 chunks 回到约 804 文件 / 3850 chunks。

Gemini embedding sidecar 实验通过:gemini-embedding-2-preview,3072 dims;24 个真实问题 benchmark 显著优于 FTS。

补上 durable memory auto-index watcher:普通 memory 写入后自动恢复 vector/FTS index,V 在短暂延迟窗口内要知道语义召回可能暂时 degraded。

Tianyi 追问“新的 memory search 运转怎样”。初查发现 CLI 索引健康,但 agent-side memory_search 报 index metadata is missing。

第一次诊断定位到 gateway 长进程握住 atomic swap 前的 sqlite fd,但解释仍偏猜测。

Tianyi 要求不要瞎修,必须实验复现:新增临时 memory + 普通 index 不复现;force/full vector reindex 稳定复现。

本地 hot patch:修 writeMeta 跳过空 temp DB 的 bug;加 sqlite dev/inode 检测,search/status/readMeta 前自动 close + reopen 被替换的 DB。

最终验证并记录:meta_count=1,821 files / 3919 chunks,agent memory_search 正常,CLI 无 metadata warning,gateway fd 指向当前 makaron.sqlite。

Architecture Decisions

这次真正沉淀的设计判断

Vector 是 sidecar,不是主记忆

Gemini vector/hybrid 用来发现线索、提高 recall;事实层仍是 markdown、LLM wiki、结构化索引与人工维护的 canonical pages。

Active memory 要保持干净

imports/raw snapshots 不能污染 active memory corpus;跨实例同步要走 quarantine / candidate / promote,而不是把全量历史直接塞进检索层。

普通增量和 full reindex 要分清

普通新增 memory + status --index 不会触发 fd 问题;full/force vector reindex 的 atomic sqlite swap 才是复现条件。

Debug 必须实验化

这次 Tianyi 明确纠偏:不要凭 backup 文件名或 imports 背景猜根因。最小复现实验比“看起来合理”的解释重要。

Incident → Patch

现场修掉的两个 reindex bug

writeMeta 空表 bug

safe reindex 使用 fresh temp DB,但 lastMetaSerialized 来自旧 DB。如果 meta 内容相同,旧逻辑会直接 return,导致新 DB meta 表为空。修复为:只有当前 DB 里确实存在同样 meta 时才跳过写入。

stale sqlite fd bug

gateway memory manager 记录当前 makaron.sqlite 的 dev/inode;search/status/readMeta 前发现 on-disk DB 被 atomic swap 替换,就关闭旧连接、打开新连接、reset vector state、重读 meta。

Hot patch path/root/.nvm/versions/node/v22.22.1/lib/node_modules/openclaw/dist/manager-Bh_0NkeN.js
Caveatlocal dist hotfix; future OpenClaw upgrades may overwrite it
Validation Gate

完成标准不是“看起来修了”,而是复现后再验证

  • controlled openclaw memory index --agent makaron --force completed
  • sqlite meta_count=1 after force reindex
  • index count verified: 821 files / 3919 chunks
  • agent-side memory_search returns Gemini vector results
  • CLI search no longer emits index metadata is missing
  • gateway fd points to current makaron.sqlite / WAL / SHM, not deleted backup
Remaining Work

下一步

Port hot patch upstream

Current fix is applied to installed dist path and can be overwritten by future OpenClaw upgrade. It should be moved into source and covered by tests.

Boost hot/core files

AGENTS / SOUL / MEMORY / USER still need special routing/boosting for preference and behavior-rule questions.

Downrank imports placeholders

memory/imports/README.md placeholders can still enter top results; exclude or downrank them.

Create canonical incident pages

Some incident questions only resolve to daily logs. Promote recurring incidents into canonical memory/concepts or project incident pages.