memory-orchestrator

name

memory-orchestrator

description

Three-layer memory system for OpenClaw agents with automatic Dream consolidation. Orchestrates LCM (lossless context), task files, and daily logs into a coherent architecture with periodic self-maintenance. Use when setting up a new OpenClaw instance's memory system, when the user asks about memory/context management, or when configuring plugins for persistent agent memory. Covers plugin installation, config, cron jobs, Dream consolidation, file conventions, and cross-platform (WhatsApp/webchat) context continuity.

Memory Orchestrator

Three-layer memory system that gives OpenClaw agents persistent, cross-session, cross-platform memory — with automatic Dream consolidation to prevent memory bloat.

Architecture Overview

Layer 1: LCM (session-internal)    → auto DAG summaries, never loses context
Layer 2: Task files + daily logs (cross-session) → dense snapshots + event journal
Layer 3: MEMORY.md (long-term)     → curated high-level overview

Each layer serves a different density/scope tradeoff. See references/architecture.md for the full design.

Quick Setup

1. Install plugins

# Lossless Context Management (session-internal, DAG summaries)
openclaw plugins install @martian-engineering/lossless-claw

2. Configure

Apply this config patch (adjust summaryModel to your setup):

{
  "plugins": {
    "slots": {
      "contextEngine": "lossless-claw"
    },
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "config": {
          "freshTailCount": 32,
          "contextThreshold": 0.75,
          "incrementalMaxDepth": -1,
          "ignoreSessionPatterns": ["agent:*:cron:**"],
          "summaryModel": "anthropic/claude-haiku-4-5"
        }
      },
      "memory-core": {
        "enabled": true,
        "config": {
          "dreaming": { "enabled": true, "frequency": "0 4 * * *" }
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "memoryFlush": { "enabled": true }
      }
    }
  }
}

3. File structure

Create these directories in your workspace:

workspace/
├── MEMORY.md              # Long-term curated memory (weekly updates)
├── memory/
│   ├── YYYY-MM-DD.md      # Daily logs
│   └── tasks/             # Dense task snapshots
│       ├── project-a.md
│       └── project-b.md

4. Cron jobs (recommended)

Set up these automated memory maintenance jobs:

• Daily Memory Sync (23:00) — Scan all sessions, write daily log, backfill missing task files. Use a cheap/fast model (e.g., Gemini Flash).
• Weekly Compound (Sunday 22:00) — Distill weekly logs into MEMORY.md updates.

See references/cron-templates.md for ready-to-use cron job definitions.

Layer Details

Layer 1: LCM (Lossless Context Management)

What: Every message persisted to SQLite. Old messages auto-summarized into a DAG. Context assembled each turn = summaries + recent raw messages.

When it kicks in: Context usage hits contextThreshold (default 75%).

Agent tools: lcm_grep (search history), lcm_describe (inspect summary), lcm_expand (drill into details).

Key config: See references/lcm-tuning.md for parameter explanations.

Layer 2: Task Files

What: Dense markdown snapshots of active work, stored in memory/tasks/.

Convention:

• Create when user says "write task" or at end of substantial work sessions
• Naming: kebab-case (ta-leaderboard.md, openvla-exp.md)
• Load on-demand only (when task is mentioned)
• Mark [DONE] when complete, never delete
• Daily Sync auto-creates lightweight tasks for uncovered work

Layer 2: Daily Logs

What: memory/YYYY-MM-DD.md — chronological event journal.

Convention:

• Load today + yesterday at session start
• Append throughout the day
• Source for weekly compound → MEMORY.md

Layer 3: MEMORY.md

What: Curated high-level overview — project status, lessons learned, weekly summaries.

Convention:

• Update weekly (manually or via Weekly Compound cron)
• Only load in main/private sessions (contains personal context)
• Periodically review and prune stale entries

Cross-Platform Continuity

For setups with multiple chat surfaces (e.g., WhatsApp + webchat):

1. Webchat idle reset: Set session.resetByChannel.webchat.idleMinutes to 7+ days to prevent orphaned sessions
2. Task handoff: Complete deep work on webchat → "write task" → continue on WhatsApp seamlessly
3. Daily Sync backfill: Catches webchat work that wasn't manually task-filed

See references/cross-platform.md for the full WhatsApp + webchat cooperation model.

Dream Consolidation

OpenClaw Native Dreaming (2026.4.5+)

OpenClaw now ships with built-in dreaming under memory-core. Enable it with:

{
  "plugins": {
    "entries": {
      "memory-core": {
        "enabled": true,
        "config": {
          "dreaming": { "enabled": true, "frequency": "0 4 * * *" }
        }
      }
    }
  }
}

Native dreaming handles: recall promotion (weighted short-term → long-term), decay aging, daily-note chunking, dreams.md output, and /dreaming command.

Custom Dream Cron — Complements Native

For MEMORY.md line-count enforcement and task file archival, the custom Dream cron is still valuable. The four-step cycle runs weekly on-demand:

1. Orientation — Read MEMORY.md, assess current state
2. Consolidation — Update statuses, remove completed items, compress old reports, enforce absolute dates
3. Task File Review — Archive completed tasks to memory/tasks/archive/
4. Index — Ensure MEMORY.md stays under target line count, update timestamp

See references/dream-consolidation.md for details and references/cron-templates.md for the cron job definition.

Absolute Date Rule

All memory files (MEMORY.md, task files) must use YYYY-MM-DD format. Never write "today", "yesterday", or "last week" — these become meaningless after the session ends.

Maintenance

The Dream cron handles most maintenance automatically. For manual maintenance during heartbeats:

1. Review recent memory/YYYY-MM-DD.md files
2. Distill significant events into MEMORY.md
3. Check memory/tasks/ for stale ACTIVE tasks (>3 days no update)
4. Prune outdated MEMORY.md entries

Troubleshooting

• LCM not triggering: Check if context window is large enough (200k+ may rarely hit 75%). Lower contextThreshold to 0.6 for testing.
• Task files empty: Daily Sync may not be running. Check cron job status.
• Webchat context lost: Verify resetByChannel.webchat.idleMinutes is set high enough.