Summary

Memory management is currently left to users via AGENTS.md instructions or third-party skills, but it's fundamental enough to warrant first-class support in OpenClaw. This proposal describes a battle-tested three-layer memory architecture that has been running in production for 2+ months.

Problem

Every OpenClaw user eventually hits the same wall:

• Context compaction wipes conversation history mid-session
• Decisions and lessons learned are forgotten between sessions
• Active tasks fall through the cracks after compaction or restart
• Users end up reinventing memory systems in AGENTS.md (see the proliferation of memory skills on ClawHub)

Related: #9142, #50096

Proposed Architecture

Three memory layers, managed automatically by OpenClaw:

memory/
├── YYYY-MM-DD.md          # Daily notes (raw, append-only)
├── active_context.md       # Working memory (current tasks, blockers)
├── channel_context/        # Per-channel summaries (multi-channel setups)
│   └── {channel-name}.md
└── pending_tasks.json      # Structured task tracker

MEMORY.md                   # Long-term memory (curated, distilled)

Layer 1: Daily Notes

Raw log of decisions, discoveries, errors, and context. One file per day, append-only. Cheap to write, easy to search.

Layer 2: Active Context

Working memory — what's in progress, what's blocked, what just completed. The fastest way to resume after compaction or session restart. Should be readable from any channel/session.

Layer 3: Long-Term Memory (MEMORY.md)

Curated knowledge distilled from daily notes. Organized by topic, not date. Periodically consolidated via a four-phase distillation cycle (Orient → Gather → Consolidate → Prune).

Session Start Behavior

On session start, OpenClaw would automatically load:

1. memory/active_context.md
2. Today's + yesterday's daily notes
3. MEMORY.md (configurable: main session only, or always)
4. Channel context if applicable

Distillation Cycle

Periodic consolidation (weekly or when 3+ unprocessed daily notes accumulate):

1. Orient: Read MEMORY.md to understand current state
2. Gather: Read unconsolidated daily notes
3. Consolidate: Extract lasting knowledge into MEMORY.md
4. Prune: Remove outdated/superseded entries

This could run as a built-in heartbeat task or scheduled maintenance.

Production Experience

This architecture has been running for 2+ months in a daily-driver OpenClaw setup with:

• 30+ cron jobs across financial tracking, monitoring, and automation
• Multi-channel integration (5+ channels)
• Daily context compactions survived without losing critical context
• Weekly automated distillation via heartbeat

Key findings:

• active_context.md is the single most valuable file — it eliminates 90% of "what was I doing?" moments after compaction
• Channel context files prevent cross-channel confusion in multi-channel setups
• The distillation cycle keeps MEMORY.md from growing unbounded while retaining important lessons
• pending_tasks.json catches promises that would otherwise be forgotten

What "Built-in" Would Look Like

1. openclaw init creates the memory/ structure automatically
2. Session start loads memory files before the first user message (configurable depth)
3. Heartbeat integration triggers distillation when conditions are met
4. Compaction awareness flushes active context before compaction to preserve state
5. Config options: which layers to use, MEMORY.md visibility scope, distillation frequency

Reference Implementation

A skill implementing this pattern is available on ClawHub: adaptive-memory. It includes setup scripts and a detailed distillation guide. This could serve as the starting point for a core implementation.

Security Considerations

• Memory files must never contain secrets/credentials (enforced by convention + optional lint)
• MEMORY.md visibility should be configurable (e.g., main session only vs. all sessions)
• Memory files may be version-controlled — treat as semi-public by default