skip to content

Memory Files & Search

Curated MEMORY.md, daily memory logs and the memory tools that search them, plus the flush that saves notes before compaction. Interviewers ask what is remembered and who can read it.

part ofAI coding toolsread it →
on this pageshow

explore

questions

5

In OpenClaw, how does the curated MEMORY.md differ from the daily memory/YYYY-MM-DD.md files, and when does each reach the model?

level: juniorimportance: must knowfreq 18%

answer

  1. curated layer versus working layer
  2. what is injected at session start
  3. dated notes stay on disk
  4. today and yesterday after /new
  5. reached through the memory tools

basics

~20 s

MEMORY.md is the short curated file of durable facts and decisions, injected when a private session starts. Daily memory/YYYY-MM-DD.md files hold detailed running notes that are indexed and fetched with memory_search and memory_get, not injected every turn.

solid answer

~40 s

In an OpenClaw workspace (default `~/.openclaw/workspace`), `MEMORY.md` is the compact long-term layer: durable non-profile facts, standing decisions and short summaries. It is one of the bootstrap files, so it is injected at the start of a private direct-message session and dropped from group, channel, cron and sub-agent sessions. The `memory/YYYY-MM-DD.md` files are the working layer: detailed notes, observations and session summaries. They are indexed for `memory_search` and read with `memory_get`; apart from today's and yesterday's notes, which are re-primed after a bare `/new` or `/reset`, they enter context only when the agent fetches them. The model remembers only what is written to disk, and an oversized `MEMORY.md` is truncated in the injected copy while the file itself stays intact.

go deeper

for a junior

Recall the two files and their jobs: MEMORY.md is the short curated summary injected at the start of a private session, daily logs are detailed notes reached through memory_search and memory_get.

for a middle

Explain what is injected and what is fetched: MEMORY.md as a bootstrap file, daily notes indexed for search, and the re-priming of today's and yesterday's notes after a bare /new or /reset.

for a senior

Show you manage the token cost: spot a MEMORY.md being truncated with /context detail or openclaw doctor, move detail into dated notes, and know the curated file is withheld from group and channel sessions.

for a principal

Weigh what deserves the always-injected layer against what can wait for a search, since every line of MEMORY.md is paid for on each turn and shown to every private session of that agent.

## Two layers in one workspace OpenClaw keeps memory as plain Markdown files in the agent's **workspace**, the folder the agent reads and writes (default `~/.openclaw/workspace`). There is no hidden state: if a fact was never written to a file, the agent does not remember it in the next session. Two of those files carry most of the weight, and they are built for different jobs. - **`MEMORY.md`** is the **curated** layer. It holds durable facts that are not about the user's profile, standing decisions, and short summaries that should be in front of the model when a conversation starts. - **`memory/YYYY-MM-DD.md`** (or `memory/YYYY-MM-DD-<slug>.md`) is the **working** layer, one file per day: detailed notes, observations, session summaries and raw context that may matter later. - Stable preferences and profile facts belong in `USER.md`, a separate user-model file with its own small budget, not in either of these. ## How each one reaches the model `MEMORY.md` is a **bootstrap file**: OpenClaw reads it when the session's prompt is built and injects it. That only happens in a private direct-message session. (On the native Codex harness OpenClaw points the model at the memory tools instead of pasting the file, when those tools are available.) For group, channel, cron and sub-agent sessions, OpenClaw drops the root `MEMORY.md` from the bootstrap set, so the curated layer is not pasted into a room full of other people. The daily files are **not injected on every turn**. They are indexed, and the agent reaches them through two tools: 1. `memory_search` finds relevant chunks by meaning and keywords, even when the wording differs. 2. `memory_get` reads a specific memory file or a line range from it. The main automatic exception: after a bare `/new` or `/reset`, OpenClaw re-primes the recent daily notes, today's and yesterday's by default, under a small character budget, so a fresh session is not blind to what happened a few hours ago. | | `MEMORY.md` | `memory/YYYY-MM-DD.md` | |---|---|---| | Role | curated long-term summary | detailed daily working notes | | Reaches the model | injected at private-session start | `memory_search` / `memory_get` on demand | | Group and channel sessions | not injected | reachable if the memory tools are allowed | | Search ranking | evergreen | decays with age | | Size pressure | truncated in the injected copy | no prompt cost until fetched | ## Why the split matters for cost Everything injected at session start costs tokens on every turn of that session. A curated file of a few hundred lines is affordable; a year of daily logs is not. That is why the documentation describes `MEMORY.md` as **not** a transcript, daily log or exhaustive archive. If `MEMORY.md` grows past the bootstrap file budget, OpenClaw keeps the file on disk intact but truncates the copy it injects. The model then sees only the shortened copy until it reads or searches memory directly. Treat that as a signal to move detail into `memory/*.md`, keep only a durable summary in `MEMORY.md`, or raise the bootstrap limits on purpose. `/context list`, `/context detail` and `openclaw doctor` show raw against injected sizes and whether truncation happened. The limits themselves belong with the bootstrap files. ## How material moves between the layers 1. **The agent writes as it works.** Asking it to "remember that the boiler is serviced in March" makes it write a note; the generated workspace instructions encourage recording durable facts. 2. **The pre-compaction flush** appends durable notes to today's daily file before a long conversation is summarised. 3. **Dreaming**, a background sweep that is on by default, scores short-term recall signals and promotes only items that pass its gates into `MEMORY.md`, writing a human-readable account to `DREAMS.md`. It can be switched off with `plugins.entries.memory-core.config.dreaming.enabled: false`. So the daily files are where material lands first, and `MEMORY.md` is where the small, durable part of it ends up. ## A worked example Suppose the owner mentions that the boiler service has moved to March and that they now prefer reminders in the morning. - The reminder preference is a profile fact, so it belongs in `USER.md` as a directive. - The service month is a durable non-profile fact; one line in `MEMORY.md` keeps it in front of the agent in every private session. - The surrounding detail (the engineer's name, the quote, the alternatives discussed) goes in that day's `memory/2026-10-06.md`. A week later a fresh private session already knows the month from `MEMORY.md`. The engineer's name costs nothing until someone asks; then the agent searches, finds the dated note and reads the few lines it needs. ## Common mistakes - Treating `MEMORY.md` as a log and appending everything to it, then wondering why the injected copy is truncated. - Expecting last month's daily note to be in context without a search. - Assuming the agent remembers a conversation that nobody wrote down. - Assuming a group chat sees the curated file the way a private chat does.

  • What happens when MEMORY.md grows past the bootstrap file budget?
    The file on disk stays intact, but the copy injected into the prompt is truncated, so the model sees only part of it until it reads or searches memory. Use `/context list`, `/context detail` or `openclaw doctor` to see raw against injected size, then move detail into `memory/*.md`, keep a short summary in `MEMORY.md`, or raise the bootstrap limits deliberately.
  • How does a fact from a daily note end up in MEMORY.md without the owner editing the file?
    Through dreaming, the background consolidation sweep that `memory-core` runs on a managed cron job and that is on by default. Candidates must pass score, recall-frequency and query-diversity gates before promotion into `MEMORY.md`, and the sweep writes its summaries to `DREAMS.md` for review. Disable it with `plugins.entries.memory-core.config.dreaming.enabled: false`.

MEMORY.md is the index card pinned above the desk, read every time you sit down; the daily logs are dated notebooks in the drawer, opened only after you look something up.

  • Every daily memory file is injected into the prompt on every turn.
  • MEMORY.md is the right place for raw transcripts and detailed daily logs.
  • The model remembers past sessions even when nothing was written to a file.
  • A truncated MEMORY.md means the rest of the file was deleted from disk.
  • MEMORY.md is injected into group chat sessions exactly as in a private chat.
open as a page

In OpenClaw, what do the memory_search and memory_get tools each do, and why does an agent usually call them in that order?

level: middleimportance: should knowfreq 10%

basics

~20 s

memory_search ranks indexed memory chunks by meaning and exact terms and returns snippets with their paths; memory_get reads a named memory file or line range. The agent searches to locate a note, then reads only the lines it needs.

open as a page

In OpenClaw, what does the automatic memory flush before compaction do, where does it write, and when is it skipped?

level: seniorimportance: should knowfreq 7%

basics

~20 s

Shortly before compaction, OpenClaw runs a silent turn telling the agent to append durable notes to today's memory/YYYY-MM-DD.md. It is on by default and skipped when disabled, when the workspace is read-only or absent, and on heartbeat turns and CLI backends.

open as a page

An OpenClaw owner asks "what did we decide about the trip last month?" and the agent finds nothing; how do you diagnose the miss?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Confirm a note from that month exists under memory/, that tool policy allows memory_search and the agent called it, then test the index with openclaw memory status --deep and openclaw memory search, rebuilding with openclaw memory index --force.

open as a page

When one OpenClaw agent serves a small team over private DMs and a shared channel, how do you decide what it writes to memory and who can read it?

level: principalimportance: nice to knowfreq 4%

basics

~20 s

Treat the agent's memory as one shared notebook: MEMORY.md reaches every direct-message session but not group or channel sessions, and memory_search reaches all notes wherever tool policy allows it. Keep private facts out or give them their own agent.

open as a page