Clarify source-of-truth between Markdown memory and plugin recall (dual-memory model causes confusing behavior)

[acesjohnny]

Summary / 摘要

EN

When memory-lancedb-pro is used as the active memory plugin in OpenClaw, there are effectively two different memory systems active at the same time:

1. Workspace Markdown memory

   • MEMORY.md
   • memory/YYYY-MM-DD.md
   • loaded into session context during startup

2. Plugin semantic memory

   • LanceDB-backed store
   • used by memory_recall / auto-recall / semantic retrieval

These two systems are not automatically equivalent, but from the user’s point of view they both appear to be “memory”. This creates a confusing dual-source-of-truth setup.

中文

当 memory-lancedb-pro 作为 OpenClaw 的活动 memory plugin 使用时，实际上会同时存在两套不同的记忆系统：

1. 工作区 Markdown memory

   • MEMORY.md
   • memory/YYYY-MM-DD.md
   • 会在 session startup 时读入上下文

2. 插件语义记忆

   • 基于 LanceDB 的存储
   • 被 memory_recall / auto-recall / semantic retrieval 使用

这两套系统并不会自动等价同步，但从用户视角看，它们都叫“memory”，因此很容易形成一个混乱的“双真相源”配置。

Observed behavior / 实际观察到的行为

EN

In my setup:

• OpenClaw session startup reads:
  • MEMORY.md
  • memory/YYYY-MM-DD.md
• memory_recall uses the plugin store (memory-lancedb-pro)
• A fact written into memory/YYYY-MM-DD.md may be visible in startup context
• But that same fact may not be found by memory_recall
• A fact written through memory_store is immediately retrievable via memory_recall
• But it is not necessarily written back into Markdown memory

So the system behaves like this:

• Markdown memory = visible to startup context
• Plugin memory = visible to semantic recall
• but users are not clearly told these are separate layers

中文

在我的配置里：

• OpenClaw session startup 会读取：
  • MEMORY.md
  • memory/YYYY-MM-DD.md
• memory_recall 实际查的是插件存储（memory-lancedb-pro）
• 写进 memory/YYYY-MM-DD.md 的内容，可能能在 startup context 里看到
• 但同一条内容，不一定能被 memory_recall 检索到
• 通过 memory_store 写进去的内容，能立刻被 memory_recall 命中
• 但它也不一定会自动回写到 Markdown memory

所以实际效果变成：

• Markdown memory = 对 startup context 可见
• Plugin memory = 对 semantic recall 可见
• 但用户并没有被明确告知它们是两层不同的系统

Why this is a problem / 为什么这是个问题

EN

This leads to a strong expectation mismatch:

A user may reasonably assume:

“If something is written into my memory file, semantic memory recall should be able to find it.”

But under the current plugin-first setup, this is not always true.

That makes the configuration feel inconsistent, even though the plugin itself is technically working.

中文

这会造成很明显的预期错位：

用户很自然会认为：

“既然某条内容已经写进 memory 文件，那 semantic recall 理应能搜到它。”

但在当前 plugin-first 的配置下，这件事并不总成立。

于是整体体验会显得“不一致”——哪怕插件本身在技术上其实是正常工作的。

Reproduction / 复现步骤

EN

Environment:

• OpenClaw with memory-lancedb-pro enabled as active memory slot
• plugin recall backed by LanceDB
• session startup still reads MEMORY.md / memory/YYYY-MM-DD.md

Steps:

1. Write a preference/fact only into memory/YYYY-MM-DD.md
2. Start a new session (so the daily note is read into context)
3. Observe that the model can sometimes “see” the note from startup context
4. Run memory_recall with a query targeting that fact
5. Observe that recall may return no result
6. Then write the same fact via memory_store
7. Run memory_recall again
8. Observe that the stored memory is retrieved immediately

中文

环境：

• OpenClaw 启用了 memory-lancedb-pro 并作为活动 memory slot
• recall 由 LanceDB 支撑
• session startup 仍会读取 MEMORY.md / memory/YYYY-MM-DD.md

步骤：

1. 只把某条偏好 / 事实写进 memory/YYYY-MM-DD.md
2. 开一个新 session（确保 daily note 被读入上下文）
3. 观察模型有时能通过 startup context “看到”这条内容
4. 使用针对该内容的查询运行 memory_recall
5. 观察 recall 可能返回 no result
6. 然后把同一条内容通过 memory_store 写入
7. 再次运行 memory_recall
8. 观察该条内容会立刻被召回

Technical interpretation / 技术判断

EN

This appears to be less of a core code bug and more of a product / configuration UX bug:

• OpenClaw’s native docs emphasize Markdown memory as the durable memory layer
• the plugin makes DB-backed semantic memory the practical truth for recall
• the relationship between the two is not made explicit enough during setup

So users can unintentionally end up with a dual-memory architecture without understanding the consequences.

中文

这看起来未必是“核心代码坏了”，更像是一个产品 / 配置体验层面的 bug：

• OpenClaw 原生文档强调 Markdown memory 是持久记忆层
• 这个插件又让数据库语义记忆变成 recall 的实际真相源
• 但两者之间的关系在配置阶段没有被讲清楚

结果就是：用户会在不知情的情况下，进入一个双记忆架构。

Suggested improvements / 改进建议

1. Explicit memory operating mode / 明确的 memory operating mode

EN

During setup, ask users to choose one mode explicitly:

• Markdown-first
• Plugin-first
• Dual-write

中文

在配置阶段明确让用户选择一种模式：

• Markdown-first
• Plugin-first
• Dual-write

2. Add configuration warnings / 增加配置告警

EN

If the plugin is active as the memory slot, show a warning such as:

Writing to MEMORY.md or memory/YYYY-MM-DD.md does not automatically guarantee semantic recall through the plugin. Use memory_store, import, or mirroring for recallable memory.

中文

如果插件已经作为活动 memory slot 启用，建议给出类似警告：

写入 MEMORY.md 或 memory/YYYY-MM-DD.md 并不自动保证插件 semantic recall 可以检索到。对于需要 recall 的内容，请使用 memory_store、import 或 mirroring。

3. Better import / mirror strategy / 更好的导入与镜像策略

EN

For plugin-first users, consider providing:

• initial import from MEMORY.md
• optional mirroring for important long-term memories
• clearer distinction between:
  • journal/log memory
  • semantic recall memory

中文

对于 plugin-first 用户，可以考虑提供：

• 从 MEMORY.md 的初始化导入
• 对重要长期记忆的可选镜像机制
• 更明确地区分：
  • journal/log memory
  • semantic recall memory

4. Stronger documentation / 更强的文档说明

EN

The README/docs should more explicitly state:

• memory/YYYY-MM-DD.md is best treated as a journal/log
• plugin memory is the primary semantic recall layer
• these two are related but not automatically the same store

中文

README / 文档应更明确说明：

• memory/YYYY-MM-DD.md 更适合作为 journal/log
• plugin memory 才是主要的 semantic recall 层
• 这两者有关联，但并不是自动同一个存储

Suggested preferred model / 建议的推荐模型

EN

A clean mental model would be:

• plugin memory = primary recall source
• MEMORY.md = curated human-readable long-term memory
• memory/YYYY-MM-DD.md = daily log / working journal

This would avoid the current “two systems, one label” confusion.

中文

一个更清晰的心智模型应该是：

• plugin memory = recall 的主存储
• MEMORY.md = 面向人类可读的长期整理记忆
• memory/YYYY-MM-DD.md = daily log / 工作日志

这样就能避免现在这种“两个系统，共用一个 memory 名字”的混淆。

Final note / 最后说明

EN

This feels like an important UX issue because it changes what users believe “memory” means.
The plugin works, but the current setup can easily create a misleading expectation of automatic equivalence between Markdown memory and semantic recall memory.

中文

这是个挺重要的 UX 问题，因为它会直接改变用户对“memory”这个概念的理解。
插件本身是工作的，但当前配置很容易让用户误以为 Markdown memory 和 semantic recall memory 会自动等价。

[AliceLJY]

分析非常深入，确实是目前用户体验最大的痛点之一，感谢梳理 🙏

你说得对——插件记忆和原生 Markdown 记忆是两个独立的存储层，恰好共享了「记忆」这个词，导致用户困惑。

当前正确的心智模型：

• Plugin memory（LanceDB）= 主要召回源，memory_recall 查这里
• MEMORY.md = 人工维护的长期参考，Claude 直接读文件
• memory/YYYY-MM-DD.md = 日常工作日志

短期改进（下个版本）：

• README 补充双记忆模型说明
• 插件启动时加提示日志：memory_recall queries the plugin store, not MEMORY.md

中期：

• 加 import-markdown 命令，一键将现有 Markdown 记忆导入插件库
• 考虑 syncMarkdown: true 配置，写入插件时同步到 Markdown

长期：

• setup wizard 中让用户明确选择 memory mode（markdown-first / plugin-first / dual-write）

这个 issue 保留作为 tracking。短期的文档改进如果你有兴趣也欢迎提 PR。

[jlin53882]

We've implemented three improvements for this issue in PR #367:

1. README: Added a Dual-Memory Architecture section explaining Plugin Memory (LanceDB) vs Markdown Memory
2. Startup warning: Plugin now logs a human-readable reminder on every initialization
3. import-markdown command: One-command migration of Markdown memories into the plugin store

Gateway log verification:
\
01:23:46 [memory-lancedb-pro] memory_recall queries the plugin store (LanceDB), not MEMORY.md...
01:23:49 memory-lancedb-pro: initialized successfully (embedding: OK, retrieval: OK)
\\

PR: #367