OpenClaw MEMORY.md Missing: Diagnose the First Failed Layer

If OpenClaw says MEMORY.md is missing, do not create or restore the file until you know which workspace and session produced the symptom. The shortest reliable diagnosis is: 1. identify the active workspace for the affected agent; 2. prove that MEMORY.md is a regular file in that workspace; 3. confirm that the session is allowed to load private long term memory; 4. distinguish a missing bootstrap marker from a truncated injected copy; 5. test search freshness only after the bootstrap checks pass. Those checks answer different questions. Reindexing cannot repair the wrong workspace. Recreating a file cannot fix intentional shared session exclusion. Increasing a prompt budget cannot restore a file that is absent on disk. OpenClaw's current documentation makes the boundary unusually clear: Markdown files in the workspace are the durable source, MEMORY.md is the curated long term layer loaded at session start, and detailed memory/YYYY MM DD.md notes are retrieved through memory tools rather than injected on every turn. That design creates more than one legitimate meaning of “missing.” First prove which workspace is active OpenClaw's default workspace is normally ~/.openclaw/workspace , but that is only a default. A profile can select a suffixed workspace, OPENCLAW WORKSPACE DIR can override the default, and a non default agent can have its own configured workspace. A file in an old or sibling directory is real but irrelevant to the session using another directory. Ask the runtime for its resolved values instead of inferring them from the shell's current directory: Choose the affected agent from that output. Then inspect metadata, not contents: On macOS, use stat f 'type=%HT bytes=%z modified=%Sm' instead. Keep the exact private path in local operator evidence; an exported health receipt needs only an opaque workspace ID, activeWorkspaceMatches , fileExists , regularFile , byte count, and modification time. The order matters: The active workspace does not match the inspected path: classify WRONG WORKSPACE . Repair the agent or profile configuration, or intentionally migrate the file after reviewing both copies. Do not silently overwrite either workspace. The active path matches but the file is absent: classify MISSING ON DISK . Decide whether this agent actually needs curated long term memory. MEMORY.md is optional; openclaw setup workspace <path can seed missing defaults without overwriting existing files. The path exists but is not an eligible regular file: classify UNSUPPORTED FILE TYPE . This is especially relevant to sandbox seeding. Current workspace documentation says sandbox seed copies accept regular in workspace files and ignore symlink or hardlink aliases that resolve outside the source workspace. The file is a regular file in the active workspace: do not call the storage layer broken. Move to session scope and bootstrap evidence. This first stage prevents a common false repair: finding a plausible MEMORY.md somewhere on disk and assuming that the affected agent uses it. A file can exist and still be absent from one prompt The next question is not “can the shell read the file?” It is “what did OpenClaw inject for this session?” In the affected session, use: The context report distinguishes raw file size from injected size and exposes truncation. openclaw doctor can also report bootstrap problems. Record the result as a small enum— present , missing marker , truncated , or not loaded —rather than copying memory text into an incident ticket. Current OpenClaw behavior creates three important branches: A missing marker is not a crash. When a bootstrap file is absent, OpenClaw injects a missing file marker and continues. That marker is evidence about the resolved workspace at session construction time. It is stronger than an agent's natural language claim that it “cannot remember,” but it still does not tell you why the file is absent. A truncated copy is not a missing file. OpenClaw keeps the file intact on disk while truncating the injected copy when a bootstrap budget is exceeded. The documented defaults are 20,000 characters per file and 60,000 characters across bootstrap files. If /context detail reports truncation, classify BOOTSTRAP TRUNCATED . Move detailed material into memory/ .md , shorten the curated layer, or deliberately raise the limits after considering prompt cost. Restoring the file would solve nothing. Private memory can be intentionally out of scope. Workspace guidance says to load MEMORY.md only in the main private session, not in shared or group contexts. A file that is present on disk but not loaded into a shared session is SCOPE EXCLUDED , not unhealthy. Changing that boundary to make a check turn green could leak private context. The practical rule is: This precedence deliberately places privacy before availability. An operator should not “repair” a shared session by injecting private durable memory. Keep bootstrap loading and memory search in separate lanes MEMORY.md startup injection and memory search are related, but they are not the same mechanism. The curated file can be present in a main session prompt while indexed retrieval is stale. Conversely, memory search can return a daily note while the bootstrap copy of MEMORY.md is missing or truncated. Only after workspace, file eligibility, scope, and bootstrap injection pass should you run: Use a canary created for the test, not a private sentence copied from long term memory. Record whether the index is fresh and whether the canary's opaque record ID was returned. Do not export the phrase. A raw digest of a short secret is also unsafe because it can be guessed offline. Two downstream classifications are useful: SEARCH STALE : the file loaded, but the index reports pending or dirty state. Reindexing is relevant here. RETRIEVAL MISS : the index claims to be fresh, but the known canary is not returned. Inspect source coverage, backend configuration, and query behavior. Neither state justifies replacing MEMORY.md . Search repair begins only after file and bootstrap health are proven. The historical OpenClaw issue 9307 is a useful warning about conflating layers: its OpenClaw 2026.2.2 3 report included both ENOENT reads for memory files and separate watcher/search sync failures. It is not evidence that the same bug exists in current OpenClaw. It is evidence that one incident can contain more than one failed layer. Reproduce the decision before touching production The following classifier uses no memory contents and encodes the first failed layer precedence: I replayed eight fixtures through that exact precedence: a healthy main session, absent file, wrong workspace, rejected sandbox link, shared session exclusion, truncated bootstrap copy, dirty index, and fresh index canary miss. All eight produced the expected classification. That experiment exposes the main operational result: six non healthy states can be described by a person as “memory is missing,” yet each requires a different response. Use this repair matrix after classification: Classification Smallest reasonable action Verification WRONG WORKSPACE Correct the selected agent/profile path or perform a reviewed migration A new main session resolves the intended opaque workspace ID MISSING ON DISK Seed or create the optional curated file only if required A new session reports present , not merely a successful write command UNSUPPORTED FILE TYPE Replace the alias with an approved regular in workspace file Sandbox and host sessions agree on eligibility SCOPE EXCLUDED Preserve the privacy boundary Main private session loads it; shared session does not BOOTSTRAP LOAD FAILURE Inspect permissions, runtime view, and bootstrap preparation /context detail reports a nonzero injected copy BOOTSTRAP TRUNCATED Curate or deliberately adjust prompt budgets Required action sensitive canary remains in the injected portion SEARCH STALE Rebuild or wait for the index according to the active backend Index freshness and canary retrieval both pass RETRIEVAL MISS Inspect source coverage and retrieval configuration The same bounded canary returns by opaque ID Do not stop at “the command succeeded.” The outcome is a fresh session receipt showing the intended workspace, eligible file, correct scope, non missing bootstrap state, and—only when search is required—a current index plus canary retrieval. One limitation remains: this receipt proves transport and availability, not semantic truth. It cannot establish that a remembered decision is correct, current, or still authorized. Action sensitive memory still needs an owner, scope, expiry, and approval boundary. Where Sidewisp fits This is the kind of evidence contract an AI agent health layer should present: first failed layer, impact, freshness, confidence, smallest safe action, and post action verification. It should not upload MEMORY.md , reveal private paths, or call a reindex a recovery before the expected memory behavior returns. Sidewisp is currently in private preview. Its production monitoring engine and OpenClaw adapter are not shipped in the current website repository, so Sidewisp does not currently inspect or repair this condition. The product direction is to add a health layer around existing runtimes and keep human authority over recovery. You can join the private preview waitlist if that boundary matches how you operate agents. Primary sources OpenClaw memory overview — file roles, startup loading, indexed daily notes, and bootstrap truncation. OpenClaw agent workspace — workspace resolution, sandbox seed eligibility, missing markers, prompt budgets, and private session scope. OpenClaw issue 9307 — historical 2026.2.2 3 incident evidence, retained only with that version boundary.