Lesson 3. Memory and Context#

Why you need this#

Imagine talking to someone who forgets everything after an hour. Inconvenient, right? OpenClaw’s memory system solves this problem: the assistant remembers important things, keeps notes, and can recall what you talked about yesterday or last week.

Two key concepts: context and memory#

Context — “working memory”#

Context is everything the model sees right now in the current conversation. Every model has a limit — the context window (how much text it can “hold in its head” at once).

Context includes:

System instructions (assistant behavior rules)
Current conversation history (your messages and responses)
Tool call results (search, files, commands)

To check how full the context window is:

/status          — brief overview
/context list    — what's loaded and how much space it takes

Memory — “notebook”#

Memory is files on disk that persist between conversations. Even when a session ends, memory records remain.

How memory works#

Memory in OpenClaw is just regular text files in Markdown format. They’re in the agent’s workspace folder (by default ~/.openclaw/workspace/).

Daily notes#

memory/2026-02-18.md    — today's notes
memory/2026-02-17.md    — yesterday's notes
memory/2026-02-16.md    — day before yesterday's notes
...

Each day is a separate file. When a session starts, the assistant reads today’s and yesterday’s notes.

Long-term memory (MEMORY.md)#

The MEMORY.md file in the workspace root is permanent memory for important things:

Your preferences
Key decisions
Facts that are always needed

Tip: If you want the assistant to remember something, just tell it: “Remember that …”. It will save it to the right file on its own.

Special files in the workspace#

AGENTS.md — “job description”#

This file describes who your assistant is and how it should behave:

# AGENTS.md

You are Maria's personal assistant.

## Rules
- Respond in English
- Be brief but informative
- If you don't know — honestly say so

The assistant reads this file on every launch and follows the written rules.

USER.md — “profile about you”#

This stores information about you that helps the assistant be more useful:

# USER.md

- Name: Maria
- Time zone: Europe/Moscow
- Preferred language: English
- Works as a designer at an IT company

MEMORY.md — “notebook”#

Permanent memory for important things:

# MEMORY.md

## Preferences
- Favorite restaurant: "The Oak" on Main Street
- Peanut allergy

## Projects
- Website redesign for "BuildCo" (deadline: March 2026)

HEARTBEAT.md — “checklist for checkups”#

Instructions for the assistant on what to check during periodic “pulses” (more details in Lesson 6):

# HEARTBEAT.md

- Check incoming emails
- Are there urgent tasks for today?

Sessions — “conversations”#

A session is one continuous conversation with the assistant. Each session has its own message history.

Managing sessions#

/new      — start a new conversation (the old one is saved)
/reset    — full reset (clear history)
/status   — information about the current session

Automatic session reset#

You can set sessions to reset automatically:

{
  session: {
    reset: {
      mode: "daily",        // reset daily
      atHour: 4,            // at 4 AM
      idleMinutes: 120      // or after 2 hours of inactivity
    }
  }
}

Compaction — “compressing” history#

When a conversation gets very long and approaches the context window limit, OpenClaw performs compaction — compresses the old part of the conversation into a brief summary.

How it works#

The assistant notices the window is filling up
Before compressing, it saves important notes to memory files (automatic “memory dump”)
Old messages are replaced with a short summary
New messages remain as they are

Manual compaction#

If you feel the assistant has gotten “confused” in a long conversation:

/compact                              — compress history
/compact Focus on the design questions   — compress with guidance on what to keep

Memory search#

OpenClaw can search through all memory files — even those not loaded in the current session. This works through vector search (semantic — by meaning, not just exact words).

For example, if you ask “when did we discuss the renovation?”, the assistant will find records even if they don’t contain the word “renovation” but have “construction work” or “apartment design.”

Memory search is enabled by default and works automatically.

Practical tips#

Ask it to remember — if something is important, say: “Remember this” or “Save to memory”
Edit files — AGENTS.md, USER.md, and MEMORY.md can be edited manually
Start a new session — if the conversation went off track, use /new
Use compaction — in long conversations, /compact will help “refresh” the context
Check the context — /context list shows what exactly the assistant sees

Lesson summary#

Context is what the model sees right now (limited by the window)
Memory is files on disk that persist between sessions
Daily notes are stored in memory/YYYY-MM-DD.md
Permanent memory is in MEMORY.md
AGENTS.md sets behavior rules, USER.md — information about you
Compaction compresses long conversations while preserving the essence
Memory search finds information by meaning, not just by words
Tell the assistant “remember” — and it will save the information to files

Next lesson: Assistant Tools