docs: clarify dual-memory architecture (fixes #344)

README.md

@@ -13,15 +13,15 @@ A LanceDB-backed OpenClaw memory plugin that stores preferences, decisions, and
 [![npm version](https://img.shields.io/npm/v/memory-lancedb-pro)](https://www.npmjs.com/package/memory-lancedb-pro)
 [![LanceDB](https://img.shields.io/badge/LanceDB-Vectorstore-orange)](https://lancedb.com)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
 <h2>⚡ <a href="https://github.com/CortexReach/memory-lancedb-pro/releases/tag/v1.1.0-beta.10">v1.1.0-beta.10 — OpenClaw 2026.3+ Hook Adaptation</a></h2>
 
 <p>
-  ✅ Fully adapted for OpenClaw 2026.3+ new plugin architecture<br>
-  🔄 Uses <code>before_prompt_build</code> hooks (replacing deprecated <code>before_agent_start</code>)<br>
-  🩺 Run <code>openclaw doctor --fix</code> after upgrading
+ ✅ Fully adapted for OpenClaw 2026.3+ new plugin architecture<br>
+ 🔄 Uses <code>before_prompt_build</code> hooks (replacing deprecated <code>before_agent_start</code>)<br>
+ 🩺 Run <code>openclaw doctor --fix</code> after upgrading
 </p>
 
+
 [English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
 
 </div>
@@ -129,6 +129,26 @@ Add to your `openclaw.json`:
 - `extractMinMessages: 2` → extraction triggers in normal two-turn chats
 - `sessionMemory.enabled: false` → avoids polluting retrieval with session summaries on day one
 
+---
+
+## ⚠️ Dual-Memory Architecture (Important)
+
+When `memory-lancedb-pro` is active, your system has **two independent memory layers** that do **not** auto-sync:
+
+| Memory Layer | Storage | What it's for | Recallable? |
+|---|---|---|---|
+| **Plugin Memory** | LanceDB (vector store) | Semantic recall via `memory_recall` / auto-recall | ✅ Yes |
+| **Markdown Memory** | `MEMORY.md`, `memory/YYYY-MM-DD.md` | Startup context, human-readable journal | ❌ Not auto-recalled |
+
+**Key principle:**
+> A fact written into `memory/YYYY-MM-DD.md` is visible in startup context, but `memory_recall` **will not find it** unless it was also written via `memory_store` (or auto-captured by the plugin).
+
+**What this means for you:**
+- Need semantic recall? → Use `memory_store` or let auto-capture do it
+- `memory/YYYY-MM-DD.md` → treat as a **daily journal / log**, not a recall source
+- `MEMORY.md` → curated human-readable reference, not a recall source
+- Plugin memory → **primary recall source** for `memory_recall` and auto-recall
+
 Validate & restart:
 
 ```bash

index.ts

@@ -1993,6 +1993,15 @@ const memoryLanceDBProPlugin = {
     );
     logReg(`memory-lancedb-pro: diagnostic build tag loaded (${DIAG_BUILD_TAG})`);
 
+    // Dual-memory model warning: help users understand the two-layer architecture
+    // Runs synchronously and logs warnings; does NOT block gateway startup.
+    api.logger.info(
+      `[memory-lancedb-pro] memory_recall queries the plugin store (LanceDB), not MEMORY.md.\n` +
+      `  - Plugin memory (LanceDB) = primary recall source for semantic search\n` +
+      `  - MEMORY.md / memory/YYYY-MM-DD.md = startup context / journal only\n` +
+      `  - Use memory_store or auto-capture for recallable memories.\n`
+    );
+
     api.on("message_received", (event: any, ctx: any) => {
       const conversationKey = buildAutoCaptureConversationKeyFromIngress(
         ctx.channelId,