🧠 Memory Never Forget 🧠

---

name: memory-never-forget description: "Memory system v4.13: Dual-layer structure (todos for execution + knowledge for strategy) with Dream/Refinement memory mechanisms." metadata: { "openclaw": { "emoji": "🧠" } }

---

🧠 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 — 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*