From 55487bc7c9d7e72e88c52a39c608ef73e7aa7dbb Mon Sep 17 00:00:00 2001
From: rezero-household <rezero-household@users.noreply.github.com>
Date: Sun, 1 Mar 2026 14:46:54 -0800
Subject: [PATCH] docs: clarify OPENCLAW_MEMORY_DIR for memory browser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OpenClaw does not create a memory/ subdirectory under OPENCLAW_HOME.
Agent memory markdown files (daily logs, MEMORY.md, etc.) live in each
agent's workspace directory, not in ~/.openclaw/memory/.

Without OPENCLAW_MEMORY_DIR set, the memory browser falls back to
OPENCLAW_HOME, which only contains .sqlite session indices — not the
human-readable markdown files users expect to see.

Document the correct value and add an inline note to .env.example.
---
 .env.example |  6 ++++++
 README.md    | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/.env.example b/.env.example
index 9123dcd..20d9940 100644
--- a/.env.example
+++ b/.env.example
@@ -67,6 +67,12 @@ NEXT_PUBLIC_GATEWAY_URL=
 # === OpenClaw Paths (derived from OPENCLAW_HOME if not set) ===
 # OPENCLAW_LOG_DIR=/path/to/.openclaw/logs
 # OPENCLAW_MEMORY_DIR=/path/to/.openclaw/memory
+#
+# NOTE: OpenClaw does NOT store agent memory markdown files under OPENCLAW_HOME/memory/.
+# That directory does not exist by default. Agent memory lives in each agent's workspace
+# (e.g. ~/clawd-agents/{agent}/memory/). Point this at your agents root to make the
+# Memory Browser useful:
+#   OPENCLAW_MEMORY_DIR=/home/you/clawd-agents
 # OPENCLAW_SOUL_TEMPLATES_DIR=/path/to/.openclaw/templates/souls
 # OPENCLAW_BIN=openclaw
 
diff --git a/README.md b/README.md
index b369888..415052b 100644
--- a/README.md
+++ b/README.md
@@ -282,10 +282,20 @@ See [`.env.example`](.env.example) for the complete list. Key variables:
 | `OPENCLAW_HOME` | Yes* | Path to `.openclaw` directory |
 | `OPENCLAW_GATEWAY_HOST` | No | Gateway host (default: `127.0.0.1`) |
 | `OPENCLAW_GATEWAY_PORT` | No | Gateway WebSocket port (default: `18789`) |
+| `OPENCLAW_MEMORY_DIR` | No | Memory browser root (see note below) |
 | `MC_ALLOWED_HOSTS` | No | Host allowlist for production |
 
 *Memory browser, log viewer, and gateway config require `OPENCLAW_HOME`.
 
+> **Memory Browser note:** OpenClaw does not store agent memory markdown files under
+> `$OPENCLAW_HOME/memory/` — that directory does not exist by default. Agent memory lives
+> in each agent's workspace (e.g. `~/clawd-agents/{agent}/memory/`). Set
+> `OPENCLAW_MEMORY_DIR` to your agents root directory to make the Memory Browser show
+> daily logs, `MEMORY.md`, and other markdown files:
+> ```
+> OPENCLAW_MEMORY_DIR=/home/you/clawd-agents
+> ```
+
 ## Deployment
 
 ```bash