🧠 Memory Never Forget 🧠

Memory system v4.13: Dual-layer structure (todos for execution + knowledge for strategy) with Dream/Refinement memory mechanisms.

🧠 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:

Mechanism	Trigger	Write to disk?	Purpose
Active Memory	Every reply (before_prompt_build)	❌ Read-only	Real-time recall, inject relevant memories into current conversation
Dream (memory-core)	Daily 12:30 cron	✅ MEMORY.md (Deep phase)	Decide which memories promote or decay
Refinement (13:00)	Daily 13:00 cron (user-defined)	✅ Writeable	Verify Dream results, fill gaps

⚠️ 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."

Phase	Output	Writes files?	Description
Light	Dream Diary prose entries	→ DREAMS.md	Organize session-corpus, 4 parallel sessions
REM	Theme reflections	→ DREAMS.md	Extract recurring themes
Deep	6-dimensional weighted scoring signals	✅ → MEMORY.md	Only phase that writes to MEMORY.md

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	Framework	Mechanism	Purpose
Temporal (how long)	Atkinson-Shiffrin 3-stage model	Dream (memory-core) Deep phase	Decay — what to keep vs. prune
Content (where)	4-type taxonomy	Refinement 13:00 + agent proactive writes	Storage — where to put for retrieval

Dimension 1: Temporal Layering

Stage	Human Equivalent	Implementation	TTL	Action
Sensory	~0.25 sec perception	Current input context	Instant	Filter immediately
Short-term	Recent	Model context window 10 turns	10 turns	Pass through working filters
Working	Recent ~7 days	memory/YYYY-MM-DD.md + Active Memory	7 days	Extract signal → promote or decay
Long-term	Permanent	MEMORY.md (index) + classified files	Permanent	Periodic review, prune when stale

Dimension 2: Content Classification (4 Types)

Written by: agent proactively during conversation (not automatic)

Type	Directory	Content Example	When to Write
user	memory/user/	User profile (role, preferences, knowledge, goals)	When learning user preferences/profile
feedback	memory/feedback/	Lessons (corrections, confirmations, style)	When user corrects or confirms
project	memory/project/	Project decisions/reasoning (raw material)	When project has new progress/decision
reference	memory/reference/	External resources (links, tools, locations)	When discovering new tools/resources

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 (<150 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

Trigger	Detection Signal	Result
Project complete	All tasks marked done, 3+ related project memories	Merge into knowledge/project-postmortem.md
Project state tracking	New progress/blockers/resource needs	Update knowledge/project-tracker.md directly (skip sublimation)
Feedback patterns	3+ related feedback entries (e.g., all about reply style)	Merge into knowledge/user-work-style-guide.md
User depth	User memory accumulates role, preferences, habits over time	Expand to knowledge/user-playbook.md
Periodic review	Dream detects high density of related memories in one category	Suggest: "Found 5 related feedback entries → merge into knowledge?"

---

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	Changes
v4.13	Dual-layer structure established (2026-04-18): Added three-layer principle (todos execution + knowledge strategy + memory classified); removed ongoing-projects.md, replaced with knowledge/project-tracker.md for strategic view; updated Workspace Structure and Sublimation description
v4.12b	Source-verified major correction (2026-04-17): Clarified three-mechanism division (Active Memory trigger/read-only, Dream Deep唯一写MEMORY.md, Refinement as user-defined cron); corrected Deep/Light/REM phase descriptions; removed non-existent file references; updated Active Memory source-level description
v4.12	Dual-Layer Dream Verification: Official Dream (12:30) + Refined Verify (13:00) cross-checking. Verification reports in memory/dreaming/verify/. Hallucination and drift prevention.
v4.11	Full integration with OpenClaw 4.11 ecosystem, Active Memory + Memory Palace + Dream Consolidation
v3.2	Memory sublimation system, 5-phase consolidation
v2.2	Memory-Knowledge layering + Atkinson-Shiffrin integration
v1.0	Initial release — Atkinson-Shiffrin three-stage model

---

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