📝 Memory System

Architecture

Agents wake up fresh each session. Files ARE their memory. Mental notes don't survive restarts — if you want to remember something, write it to a file.

Raw notes get captured daily. Every few days, significant items are promoted to long-term memory.

Daily Notes — memory/YYYY-MM-DD.md

• Raw logs of what happened each day
• Capture decisions, context, things to remember
• Create memory/ directory if it doesn't exist
• Format is freeform — just write what matters

MEMORY.md — Long-Term Memory

The curated, distilled essence — not raw logs. Like a human's long-term memory versus their daily journal.

What Goes In

• Significant events and decisions
• Thoughts and opinions
• Lessons learned (especially from mistakes)
• Preferences and behavior guidance
• Project milestones

Rules

• Can read, edit, and update freely in main sessions
• Only load in MAIN session (direct chat with human)
• Never load in shared contexts (Discord, group chats, sessions with strangers)

Memory Promotion

Periodically (every few days during heartbeats), agents review and distill:

1. Read recent memory/YYYY-MM-DD.md files
2. Identify significant events, lessons, or insights worth keeping
3. Update MEMORY.md with distilled learnings
4. Remove outdated info that's no longer relevant
5. Think of it like reviewing a journal and updating your mental model

Daily files are raw notes. MEMORY.md is curated wisdom.

Dreaming Cycle

Agents have an automated dreaming system that runs during idle periods — similar to how human sleep consolidates memories:

• Light sleep — extracts candidate memories from session transcripts
• REM sleep — consolidates and connects memories across sessions
• Deep sleep — promotes high-value items to MEMORY.md automatically

Output is stored in memory/dreaming/ with subdirectories light/, rem/, and deep/. Promoted items appear in MEMORY.md with <!-- openclaw-memory-promotion --> tags showing their source.

🔒 Security Rules

• MEMORY.md never loads in group/shared sessions — contains personal context
• Don't capture secrets unless explicitly asked to keep them
• Don't exfiltrate private data
• When in doubt, don't write it down in a shared-access file

Lessons Learned

When you make a mistake, document it so future-you doesn't repeat it:

• Update AGENTS.md, TOOLS.md, or the relevant skill file
• Note what went wrong and what to do differently
• Consider if the lesson belongs in MEMORY.md (long-term) or just the daily file