🧠 Memory Never Forget 🧠

**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`):
```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:
```
- [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:

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

```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*