🧠 Memory Never Forget v4.13

A full-featured memory system for OpenClaw, integrating Active Memory retrieval, Memory Palace structured views, and a Dual-Layer Dream Verification mechanism — delivering "proactive memory + global view + verifiable consolidation."

Core Logic: Active Memory = Memory Butler, Memory Palace = Knowledge Palace, Dual-Layer Dream = Verification & Consolidation Expert

Three-Layer Separation: todos.md = Execution Layer | knowledge/ = Strategy Layer | memory/ = Classified Memory Layer

License: MIT-0 | Updated: 2026-04-18 | v4.13: Added dual-layer structure

Overview

This skill manages memory across two orthogonal dimensions:

1. Temporal (Atkinson-Shiffrin 3-stage model) — what to keep vs. what to prune
2. Content (4-type taxonomy) — where to store for fast retrieval

Three independent mechanisms work together:

⚠️ v4.12b source-verified correction (2026-04-17): Clarified actual division of three mechanisms

Core Components

1. Active Memory — Proactive Recall (Source-Verified)

Trigger mechanism:

• Hooked to before_prompt_build, auto-triggers before every reply
• Spawns a read-only sub-agent with only memory_search + memory_get permissions
• Builds query from current user message, searches recall index (memory/.dreams/short-term-recall.json)
• Searched summaries are prepended to prompt before model generates reply
• Results cached 15 seconds (cacheTtlMs) to avoid repeated recall in same turn

Key constraints:

• ❌ Read-only, produces no files
• ❌ Cannot call other tools
• Only affects current conversation context, not persisted

Configuration (openclaw.json → plugins.entries.active-memory.config):

{
  "enabled": true,
  "queryMode": "recent",      // message | recent | full
  "promptStyle": "balanced",  // balanced | strict | contextual | recall-heavy | precision-heavy | preference-only
  "maxSummaryChars": 220,
  "recentUserTurns": 2,
  "recentAssistantTurns": 1,
  "timeoutMs": 15000
}

2. Memory Palace — Structured Views

Provides multi-dimensional views of your agent's long-term memory:

• Timeline — chronological view of work progress
• Projects — aggregated by project
• Technology — organized by tech domain
• Custom — user-defined dimensions

3. Dream (memory-core) — Temporal Layering (Source-Verified)

Trigger: 30 12 * * * (cron), sessionTarget="main", payload="systemEvent: __openclaw_memory_core_short_term_promotion_dream__"

Three phases (Light → REM → Deep):

Source quote (formatPhaseGuide):
"deep is the only stage that writes durable entries to MEMORY.md. DREAMS.md is for human-readable dreaming summaries and diary entries."

Deep phase promotion parameters (adjust in cron job description):

• minScore: 0.500 (tune based on your promotion rate)
• minRecallCount: 3
• minUniqueQueries: 3
• recencyHalfLifeDays: 14
• maxAgeDays: 30
• limit: 10

⚠️ The following files are NEVER generated (source-verified):

• ❌ memory/dreaming/deep/YYYY-MM-DD.md
• ❌ memory/dreaming/light/YYYY-MM-DD.md
• ❌ memory/dreaming/rem/YYYY-MM-DD.md

4. Refinement (User-Defined Cron) — Content Classification

Trigger: 0 13 * * * (user-defined cron), sessionTarget="isolated"

Nature: User-written AI agent prompt, not an OpenClaw native mechanism

Responsibilities:

• Read Dream outputs (DREAMS.md, session-corpus)
• Verify conflicts, hallucinations, outdated entries
• Classify new memories into 4 categories (user/feedback/project/reference)
• Write verification report to memory/dreaming/verify/YYYY-MM-DD.md

⚠️ Note: Verification reports' "supplementary promotion suggestions" are text only and won't automatically write to MEMORY.md. Manual promotion required.

Two Orthogonal Dimensions

Dimension 1: Temporal Layering

Dimension 2: Content Classification (4 Types)

Written by: agent proactively during conversation (not automatic)

Important: Project execution state tracking (blockers, needs, progress) → write directly to knowledge/project-tracker.md (strategy layer); only project experience, decision reasoning, retrospective summaries → sublimate to memory/project/ (classified memory layer)

What to Save / What NOT to Save

✅ Save

• User's role, preferences, responsibilities, knowledge
• User corrections ("not like that", "should be this way")
• User confirmations ("yes exactly", "perfect, keep that")
• Project decisions and the reasoning (not just what, but why)
• New tools, links, resources
• External system locations and their purpose

❌ Don't Save

• ❌ Code patterns, architecture, file paths (derivable from codebase)
• ❌ Git history (git log is the authoritative source)
• ❌ Debugging solutions (the fix is in the code)
• ❌ Anything already documented elsewhere
• ❌ Ephemeral task state (write to todos.md instead)
• ❌ Raw conversation content

MEMORY.md = Long-Term Index Only

MEMORY.md is the index of long-term memories only, never content. Format:

- [Title](path) — one-line description (\x3C150 chars)

Memory File Format

Every classified memory file must have frontmatter:

---
name: Memory name
description: One-line description (used to judge relevance)
type: user|feedback|project|reference
created: YYYY-MM-DD
---

## Rule / Fact
(the content)

## Why
(reason / motivation)

## How to apply
(when and how to use this memory)

Memory Drift Caveat

Memories can become stale. Rules:

1. Verify first: When referencing a file, function, or path — check it still exists
2. Trust current state: If memory conflicts with current observation, trust what you see now
3. Update or delete: When a memory is outdated, fix or remove it immediately
4. Absolute dates: Convert relative dates ("yesterday", "last week") to absolute dates

Memory → Knowledge Sublimation

Not all mature memories should decay. Some evolve into knowledge.

When to Sublimate

Session Lifecycle

Session Start

1. Sensory: Read current input
2. Short-term: Last 10 turns from context window
3. Working: Read memory/today.md + memory/yesterday.md
4. Long-term: Read MEMORY.md index

Note: Active Memory runs before the above (in before_prompt_build hook)

During Conversation

- New info → write to working memory (today's daily log)
- Learned something worth remembering → update MEMORY.md index + save classified file
- User preference → update USER.md + memory/user/
- Task/priority change → update todos.md
- Need to retrieve → find in MEMORY.md index → read classified file

Session End

- Summarize → write to memory/today.md (working memory)
- Identify items for long-term → update classified files
- Update MEMORY.md index
- Mark items for Dream review (decay candidates)

Workspace Structure

workspace/
├── MEMORY.md              # long-term memory index (written by Dream Deep phase)
├── USER.md                # user info
├── SOUL.md                # AI identity
├── todos.md               # ★ Execution layer: today's tasks + long-term tracking (user-facing)
├── HEARTBEAT.md           # daily reminders
├── memory/
│   ├── memory-types.md    # this file (or link to SKILL.md)
│   ├── user/              # long-term user memories (written by agent)
│   ├── feedback/          # long-term feedback (written by agent)
│   ├── project/           # long-term project memories (written by agent, post-sublimate)
│   ├── reference/         # long-term references (written by agent)
│   ├── palace/            # Memory Palace views
│   │   ├── timeline.md
│   │   ├── projects.md
│   │   ├── technology.md
│   │   └── custom.md
│   ├── dreaming/
│   │   └── verify/        # Verification reports (written by Refinement 13:00)
│   ├── .dreams/           # Internal machine data (NOT human-readable)
│   │   ├── phase-signals.json    # Deep phase scoring signals
│   │   ├── events.jsonl          # memory_search event log
│   │   ├── session-ingestion.json # session-corpus metadata
│   │   └── short-term-recall.json # Active Memory recall index
│   └── YYYY-MM-DD.md     # working memory (daily logs)
└── knowledge/             # ★ Strategy layer (project blockers/progress/resources/suggestions)
    └── project-tracker.md # Project panorama, user-facing

Three-Layer Principle

• todos.md = Execution layer: what to do today, tracking each node (user-maintained)
• knowledge/ = Strategy layer: where projects are stuck, what resources needed, suggestions
• memory/ = Classified memory layer: experience distillation, decision retrospectives, pattern discovery

Each layer has its own purpose, no duplication.

Example Interactions

User provides important info:

User: "I'm a data analyst, mostly working with Python" → Working: log in today's daily log → Long-term: save to memory/user/user-profile.md, update MEMORY.md index

User corrects you:

User: "Don't use Markdown tables, use lists" → Working: log in today's daily log → Long-term: save to memory/feedback/no-tables.md, update MEMORY.md index

Project decision:

Decision: approach A over B because lower cost → Working: log decision context → Long-term: save to memory/project/decision.md with reasoning

Looking up a past date:

User: "What did we do last Tuesday?" → Active Memory auto-recalls → read memory/YYYY-MM-DD.md for that date

OpenClaw Commands

# Check Active Memory status
openclaw plugins list | grep active-memory

# Check Dream status
openclaw dreaming status

# Toggle Dream on/off
openclaw dreaming on
openclaw dreaming off

# Manually trigger Dream Consolidation
openclaw memory dream

Changelog

Version: v4.13 | Updated: 2026-04-18 | Three layers: todos execution + knowledge strategy + memory classified