Memory Architecture

+15 Mana ✨
OpenClaw Memory Documentation(DOCUMENTATION)

Introduction

OpenClaw's memory system is built on plain Markdown files — the files themselves are the source of truth, not a database or opaque store. This design makes memory inspectable, editable, and version-controllable. This lesson explains the two memory layers and when each is loaded into context.

Key Concepts

  • Daily Logs — append-only Markdown files stored at memory/YYYY-MM-DD.md that capture the day's interactions.
  • MEMORY.md — a curated, evergreen file containing long-term knowledge that persists across sessions.
  • Append-Only — daily logs are never edited after creation; new entries are appended at the bottom.
  • Private Sessions — only private sessions load MEMORY.md, preventing long-term memory from leaking into shared or group contexts.

Real World Context

Think of daily logs as a developer's scratch notes — quick, timestamped entries that capture what happened today. MEMORY.md is more like a personal wiki: carefully maintained, containing only the information that remains relevant over time. Just as a developer might jot down debugging steps in a daily journal but only promote important findings to a team knowledge base, OpenClaw separates ephemeral and enduring memory.

Deep Dive

OpenClaw's memory philosophy is radical in its simplicity: everything is a Markdown file stored on disk.

File Storage Layout

All memory files live under the agent's session directory:

text
~/.openclaw/agents/<agentId>/sessions/
├── sessions.json          # Session index and metadata
├── <SessionId>.jsonl      # Raw session transcript
└── memory/
    ├── MEMORY.md           # Long-term curated memory
    ├── 2025-06-15.md       # Daily log for June 15
    └── 2025-06-16.md       # Daily log for June 16

Before exploring each layer, note that this flat-file approach means you can open any of these files in a text editor, inspect them, and even edit them directly. The files are the source of truth.

Daily Logs

Daily logs follow the naming convention memory/YYYY-MM-DD.md and are strictly append-only:

markdown
# 2025-06-16

## 10:32 AM — User asked about deployment
- Discussed Docker configuration
- Recommended multi-stage builds

## 2:15 PM — Debugging session
- Identified memory leak in worker process
- Root cause: unclosed database connections

When a session starts, OpenClaw loads today's log and yesterday's log into the context window. This gives the agent recent continuity — it remembers what happened today and can reference yesterday's context — without bloating the prompt with weeks of history.

MEMORY.md — Long-Term Memory

The MEMORY.md file contains curated, evergreen knowledge:

markdown
# Agent Memory

## User Preferences
- Prefers TypeScript over JavaScript
- Uses Vim keybindings
- Timezone: UTC+1

## Project Context
- Main repo: github.com/acme/app
- Deployment target: AWS ECS
- CI: GitHub Actions

Unlike daily logs, MEMORY.md is actively edited and maintained. Old or irrelevant information is removed, and new evergreen facts are added. Critically, MEMORY.md is only loaded in private sessions. Group chats and shared sessions do not receive long-term memory, which prevents personal preferences and private context from leaking into multi-user environments.

Loading Rules Summary

The loading behaviour can be summarised as follows:

text
Session Start:
  ├── Always load: today.md + yesterday.md (daily logs)
  ├── Private session? → Also load MEMORY.md
  └── Group/shared session? → Skip MEMORY.md

This two-tier approach balances context richness with privacy and token efficiency.

Common Pitfalls

  • Treating daily logs as editable — daily logs are append-only by design. Editing them breaks the chronological record and can confuse the agent's sense of timeline.
  • Putting ephemeral information in MEMORY.md — MEMORY.md is for evergreen facts. Temporary details like "meeting at 3 PM today" belong in daily logs, not long-term memory.
  • Expecting MEMORY.md in group sessions — MEMORY.md only loads in private sessions. If your agent needs shared long-term context in group chats, use a different mechanism.

Best Practices

  • Curate MEMORY.md regularly — remove outdated information and keep it focused on facts that remain true over time.
  • Let daily logs accumulate naturally — do not prune them manually; the memory system handles context loading automatically by only reading today and yesterday.
  • Use private sessions for personalised interactions — since MEMORY.md only loads in private sessions, personal preferences and user-specific context should be managed through private channels.

Summary

  • OpenClaw memory is built on plain Markdown files — the files are the source of truth.
  • Daily logs (memory/YYYY-MM-DD.md) are append-only and capture ephemeral interactions; today and yesterday are loaded at session start.
  • MEMORY.md stores curated, evergreen knowledge and is only loaded in private sessions.
  • Session transcripts are stored as JSONL files alongside the memory directory.
  • The flat-file design makes memory fully inspectable and editable with standard tools.
✓ Completed