The Memory System

Understand how OpenClaw memory works and build a knowledge base that grows over time.

Read this when your agent forgets things between sessions or when you want it to build up context over time.

How memory works

OpenClaw uses file-based memory. There are no embeddings, no vector databases, no magic — just text files that your agent reads at startup and can write to during sessions.

Here's the full lifecycle:

Session start
    │
    ▼
Read files into context
    ├── SOUL.md        (personality & rules — always)
    ├── USER.md        (who you are — always)
    ├── MEMORY.md      (past session notes — always)
    └── HEARTBEAT.md   (standing instructions — always)
    │
    ▼
Conversation
(context window holds all of the above
 plus the live exchange)
    │
    ▼
Session ends
    │
    ▼
session_end hook fires (if configured)
    │
    ▼
Agent writes to MEMORY.md
(new facts, decisions, summary —
 only if something worth saving happened)

The key files:

File	Location	Purpose
`SOUL.md`	`~/.openclaw/SOUL.md`	Permanent personality and behavior rules
`USER.md`	`~/.openclaw/USER.md`	Who you are and how you like to work
`MEMORY.md`	`~/.openclaw/workspace/MEMORY.md`	Growing notes from past sessions
`HEARTBEAT.md`	`~/.openclaw/workspace/HEARTBEAT.md`	Standing instructions — what to always track

All are plain text and editable by you.

MEMORY.md

MEMORY.md is where session knowledge accumulates. Your agent reads it at the start of every session, so facts written there are always in context.

To make your agent write to it, add to SOUL.md:

## Memory
Write to MEMORY.md after each session if:
- You learned something new about me or my work
- I explicitly said "remember this" or "save this"
- A decision was made that will affect future sessions

Format:
## [Date] — [Topic]
[1-3 bullet points of key facts]

Then read and prune it monthly. Remove outdated entries. The file should be useful, not a dump.

Session hooks

For automatic memory writes (without telling the agent each time), use a session end hook:

{
  "hooks": {
    "session_end": "Review this conversation. Write a 2-3 line summary to MEMORY.md if anything important was discussed, decided, or learned. Skip if it was just a quick factual question."
  }
}

With this set, your agent writes session notes automatically after every substantive conversation.

HEARTBEAT.md

HEARTBEAT.md is for standing context — things that are always true or always being tracked. Unlike MEMORY.md (which grows), HEARTBEAT.md is curated.

Example content:

# Standing Context

## Current priorities
- Working on [project] — deadline [date]
- Trying to [habit/goal]

## Always track
- Note any tasks I mention and add to tasks.md
- Flag if I mention something I've worried about before

## Recurring context
- Weekly team meeting is Monday at 10am
- [Other recurring facts]

Keep it under 50 lines. The agent reads this every session.

Memory limits

The agent can only use what fits in its context window. For Claude Sonnet, that's large (200k tokens), but MEMORY.md will hit practical limits around 10,000 words.

Signs your MEMORY.md is too large:

Responses start ignoring things you know are in MEMORY.md
Sessions feel slower to start

Fix: prune old entries. Move domain knowledge to topic-specific files (project-alpha.md, fitness-notes.md) and reference them in HEARTBEAT.md.

Which approach to use

Approach	Best for	Tradeoff
Single `MEMORY.md`	Simple setups, early-stage agents	Gets unwieldy past ~10k words; prune monthly
Domain files (`projects/`, `research/`)	Multi-topic agents, research-heavy use	Requires routing instructions in SOUL.md
`HEARTBEAT.md` only	Stable standing context (recurring meetings, goals)	You maintain it manually — doesn't self-update
`USER.md`	Facts that are always true about you	Curated by you, not written by the agent

Most setups start with single MEMORY.md + HEARTBEAT.md and split into domain files once MEMORY.md exceeds 200 entries.

Domain-specific memory files

Instead of one giant MEMORY.md, split by domain:

~/.openclaw/workspace/
├── MEMORY.md          ← recent session notes
├── HEARTBEAT.md       ← standing instructions
├── projects/
│   ├── project-alpha.md
│   └── project-beta.md
├── research/
│   └── rag-notes.md
└── household/
    ├── tasks.md
    └── meal-plan.md

Tell the agent which files to read for specific topics:

## Domain files
For project questions: read from workspace/projects/
For research questions: check workspace/research/
For household logistics: check workspace/household/

Full memory stack example

SOUL.md includes:

## Memory system
- Read HEARTBEAT.md for standing context
- Read MEMORY.md for recent session notes
- For project work, check workspace/projects/[relevant file]
- Write to MEMORY.md after sessions that matter
- Write to the relevant domain file if domain knowledge was added

This gives you a structured, scalable memory system that actually works.

On this page