How OpenClaw Memory Actually Works
(And How to Fix It)

The three memory layers

OpenClaw's memory system has three layers, each serving a different purpose:

Layer 1: Knowledge Graph (~/life/)

Entity-based storage for durable facts — organised by PARA (Projects, Areas, Resources, Archives). Think of this as your agent's long-term brain. Each person, company, or project gets its own folder with a summary.md for quick context and an items.json for atomic facts.

Facts here never get deleted — they decay in retrieval priority over time (hot → warm → cold) but remain in the files.

Layer 2: Daily Notes (memory/YYYY-MM-DD.md)

Raw timeline of everything that happens. Your agent writes here continuously during conversations. This is the working memory — what happened today, what decisions were made, what tasks are in progress.

Layer 3: Tacit Knowledge (MEMORY.md)

How you operate — your preferences, patterns, and permanent decisions. Not facts about the world; facts about you. Things like "Mark prefers direct communication" or "never resurface dropped ideas."

Why your agent forgets things

Here's the gap most people hit: the heartbeat is the extraction engine. During each heartbeat run, the agent is supposed to read recent conversations, pull out durable facts, and write them to the knowledge graph and MEMORY.md.

If the heartbeat isn't running — or if it ran but didn't extract anything — those facts only live in the raw session file. When a /new or /reset starts a fresh session, that raw history is gone from active context.

The typical failure modes:

• Heartbeat not configured — nothing ever gets extracted
• Heartbeat model too weak — it runs but produces poor extractions
• Session reset before extraction — information is trapped in an old session file
• MEMORY.md empty — permanent decisions aren't persisted anywhere

The fix: a proper setup

Step 1: Create your memory directories

mkdir -p ~/life/{projects,areas/{people,companies},resources,archives}
mkdir -p ~/.openclaw/workspace/memory

Step 2: Set up a MEMORY.md with permanent context

Create ~/.openclaw/workspace/MEMORY.md with the things you never want your agent to forget:

# MEMORY.md

## About Me
- Name: [Your name]
- Timezone: [Your timezone]
- Communication style: direct/formal/casual

## Permanent Decisions
- [Things that should never be reversed or re-suggested]

## Business Context
- Company: [Name]
- Focus: [What you're building]

Step 3: Configure your heartbeat to extract facts

Your HEARTBEAT.md should include a fact extraction step:

## Fact Extraction (every heartbeat)
1. Check for new conversations since last extraction
2. Extract durable facts to ~/life/ entities
3. Update memory/YYYY-MM-DD.md with timeline entries
4. Update MEMORY.md if new permanent patterns emerge

Step 4: Run the heartbeat regularly

Every 10–30 minutes is the sweet spot. Too frequent wastes tokens; too infrequent means long gaps where facts can be lost.

openclaw cron add \
  --name heartbeat \
  --every 10m \
  --session isolated \
  --message "Run HEARTBEAT.md" \
  --model google/gemini-2.5-flash \
  --announce

The session transcript fallback

If you suspect facts were lost in a reset, they're not completely gone. Raw session files live at ~/.openclaw/agents/main/sessions/ as .jsonl files. Your agent can read these to reconstruct what happened — just ask it to check the session files for a specific time period.