MEMORY.md, Day 8 of the Free Comprehensive OpenClaw Course

How does an OpenClaw agent actually remember things?

OpenClaw memory.md is the long-term file, but the full memory system is three files working together. MEMORY.md for durable facts the agent should always know, daily notes for running context the agent generates as it goes, and a dreaming process that runs periodically to promote things from daily notes into MEMORY.md when they prove durable.

The flow on every conversation:

1. The agent loads MEMORY.md (small, curated, durable facts).
2. The agent loads recent daily notes (running context from the last few days).
3. The agent uses hybrid search (keyword plus embedding) to surface older daily notes that match the current conversation.
4. The agent has a working context that includes long-term, recent, and topically-relevant memory all at once.

That hybrid search is the trick that makes the system feel like it remembers everything without paying the token cost of actually loading everything.

What goes in MEMORY.md versus daily notes?

The split:

MEMORY.md holds facts that should always be in the agent's working context. Your name, your role, the people in your life, your business, the products and clients the agent should know about, recurring projects, the agent's own permissions and current goals. If the agent should know it on the first message of every conversation, it goes here. Keep this file small, every token in it is paid on every prompt. A 4k-token MEMORY.md is healthy, a 14k-token one is bloated and probably has things that should have been pruned or moved to daily notes.

Daily notes hold the running history the agent generates. Conversation summaries, task updates, things you mentioned in passing, things the agent decided. These are not in the working context by default, the agent surfaces them via hybrid search when they become relevant. Daily notes can grow to any size, the embedding index handles retrieval.

The dreaming process runs on a schedule (configurable, default once a day) and looks at daily notes for things that have been referenced repeatedly. If something keeps coming up, dreaming promotes it into MEMORY.md so it stops needing to be searched for.

Concrete examples of MEMORY.md entries

What good MEMORY.md entries actually look like. The format is human-readable markdown, organised into sections the agent can reference:

# MEMORY.md

## Identity
- Adhiraj Hangal, USC engineer, founder of OpenClaw Consult.
- Lives in San Francisco, time zone America/Los_Angeles.
- Authored PR #76345 to openclaw/openclaw, merged into core.

## People
- Maya, business partner. Reachable on Slack as @maya.
- Tom, lead engineer at AcmeCorp (current consulting client).
  Prefers async, replies slowly to email, fast to Slack DMs.
- Sarah, accountant. Quarterly tax meeting first Monday of
  every quarter at 10am PT.

## Active projects
- Q2 2026: ship the Stripe-payment Skill for AcmeCorp.
- Ongoing: weekly newsletter, drafts due Thursday 5pm PT.
- Side: bootcamp content rewrite, target 1500 words per lesson.

## Recurring rules
- Calendar holds Wednesdays for deep work, decline meetings.
- Inbox zero by Friday 6pm.
- Weekly review on Sunday 8pm, reflect on the past week.

## Recent decisions
- 2026-04-15: switched the agent to two-tier routing,
  Sonnet plus Haiku. Bill dropped from $73 to $17 a month.
- 2026-04-22: enabled prompt caching, additional 30% savings.

Five sections, roughly 200 words, around 350 tokens. Every fact is durable, every fact is something the agent should know on the first message of any conversation. No stale notes, no rambling, no transient context. This is what a healthy MEMORY.md looks like.

What is the OpenClaw dreaming system?

The dreaming system is the agent's curation loop. It runs on its own schedule, reads recent daily notes, and decides what should be promoted into MEMORY.md, what should be summarised, and what can be allowed to fade. It is the closest thing the agent has to consolidation, the same shape biological brains do during sleep.

The dreaming pass is its own paid API call, so the schedule is a cost decision. Once a day is the default and works for most personal agents. More often than that and you are paying for promotion of things that have not yet proven durable. Less often and the MEMORY.md gets stale.

The output of dreaming is visible, the runtime writes a summary of what it promoted into a sibling log file. Read it occasionally, it shows you what the agent thinks is important about your life, which is informative even when it is wrong.

The dreaming process, step by step

The dreaming pass on a typical schedule:

1. Trigger fires (default 3am local time, configurable).
2. Runtime loads the last 30 days of daily notes.
3. Runtime sends them to the smart-tier model with the prompt: "Read these daily notes. Identify themes that have appeared more than three times. Identify facts that have stayed stable across multiple days. Identify decisions that should be remembered long-term."
4. Model returns a list of promotion candidates.
5. Each candidate is appended to MEMORY.md under the appropriate section, with a citation back to the daily note that established it.
6. Runtime writes a dream-log entry: "Promoted X facts, considered Y, rejected Z."

The cost per dreaming pass on Claude Sonnet, with 30 days of daily notes at maybe 5k tokens, is roughly $0.15. Over a month of nightly passes, that is $4.50. Cheap compared to the value of a MEMORY.md that stays current.

Token cost math for memory

The math that explains why MEMORY.md hygiene matters. Assume a personal agent with a heartbeat firing every 15 minutes (96 ticks a day) plus 20 user prompts a day. That is 116 prompts daily. MEMORY.md is sent on every prompt.

If MEMORY.md is 4k tokens, you send 464k tokens of MEMORY.md per day. At Claude Sonnet input pricing of roughly $3 per million tokens, that is $1.40 a day, $42 a month, just for sending MEMORY.md. With prompt caching enabled, this drops to roughly $4 a month.

If MEMORY.md is 14k tokens, you send 1.6M tokens per day. That is $4.90 a day, $147 a month, without caching. With caching, around $14 a month.

The 4k-versus-14k bloat decision is the difference between $4 a month and $14 a month, just on memory tokens. Across a year, that is $120. Across multiple agents, multiply. The hygiene matters.

Memory flush triggers and how to tune them

Three triggers cause the runtime to rebuild the embedding index over daily notes. The first, manual flush via openclaw memory flush. Run this any time you edit daily notes by hand. The second, file-watch flush, the runtime watches the daily notes folder and rebuilds the index incrementally on every saved file. The third, scheduled flush, a full rebuild runs every 24 hours by default to catch anything the watcher missed.

Tune the schedule with memory.flush_interval: 12h in your AGENTS.md. Tighter on busy agents (lots of daily-note churn), looser on quiet ones. The flush itself is cheap, embedding rebuild on a year of daily notes takes maybe 30 seconds and costs a few cents.

Memory flush and bloat, the operations side

Two operational notes. The embedding index for daily notes is built incrementally, but if you edit the files by hand (which is fine, they are markdown), run openclaw memory flush to rebuild the index. Otherwise the agent's hybrid search returns stale embeddings.

And on bloat, MEMORY.md silently doubles your token bill if you never prune it. Treat it like git history, a long log of decisions but with the dead branches pruned. Once a month or so, open the file, delete the things that are no longer true, condense the rambling sections, move durable facts to the top. The dreaming process is supposed to do some of this automatically, but it is conservative, it never deletes, it only promotes. Manual pruning is part of operating an OpenClaw agent.

How this connects to your full agent

Memory is what makes the agent feel like it knows you. Soul (openclaw soul.md) makes the agent sound like a person, memory makes the agent sound like the person who has known you for a year. Together they produce the "wait, this actually feels like an assistant" moment.

The cost shape from this lesson connects directly to openclaw cost optimization on day 4. Memory bloat is one of the four levers that swing the bill, and it is the only one the agent cannot fix on its own. The dreaming process helps, but pruning is on you. Make it a monthly habit.

The next file in the workspace contract is openclaw agents.md on day 9, the operating manual. Memory tells the agent who you are, agents.md tells the agent what it can do. Both load on every prompt, both deserve careful curation. The full reference for every workspace file lives in openclaw workspace files on day 16.