🧠 Memory Never Forget 🧠

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

jujitao@jujitao

Install

openclaw skills install @jujitao/memory-never-forget

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

Temporal (Atkinson-Shiffrin 3-stage model) — what to keep vs. what to prune
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):

json

{
  "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:

text

- [Title](path) — one-line description (<150 chars)

Memory File Format

Every classified memory file must have frontmatter:

yaml

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

Verify first: When referencing a file, function, or path — check it still exists
Trust current state: If memory conflicts with current observation, trust what you see now
Update or delete: When a memory is outdated, fix or remove it immediately
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

text

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

text

- 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

text

- 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

text

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

bash

# 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

🧠 Memory Never Forget 🧠

Install

🧠 Memory Never Forget v4.13

Overview

Core Components

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

2. Memory Palace — Structured Views

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

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

Two Orthogonal Dimensions

Dimension 1: Temporal Layering

Dimension 2: Content Classification (4 Types)

What to Save / What NOT to Save

✅ Save

❌ Don't Save

MEMORY.md = Long-Term Index Only

Memory File Format

Memory Drift Caveat

Memory → Knowledge Sublimation

When to Sublimate

Session Lifecycle

Session Start

During Conversation

Session End

Workspace Structure

Three-Layer Principle

Example Interactions

OpenClaw Commands

Changelog

Related skills