Skill: Memory Mastery

Owner: koatora20

Summary: Implements a three-layer memory system with daily logs, curated long-term notes, and optional vector search for persistent, searchable agent context across s...

Tags: latest:1.0.0

Version history:

v1.0.0 | 2026-02-09T16:35:40.793Z | user

Initial release: 3-layer memory system (daily logs + long-term memory + vector search) for OpenClaw agents. Includes audit, setup, and maintenance scripts.

Archive index:

Archive v1.0.0: 7 files, 9797 bytes

Files: scripts/audit.sh (3425b), scripts/maintenance.sh (3812b), scripts/setup.sh (5756b), SKILL.md (6992b), templates/heartbeat-memory.md (527b), templates/memory-rules.md (1572b), _meta.json (133b)

File v1.0.0:SKILL.md

Memory Mastery - OpenClaw Memory System

A three-layer memory architecture for persistent context across sessions.

What This Is

This skill implements a structured memory system for OpenClaw agents, enabling them to maintain context and continuity across sessions through a three-layer architecture:

• L1 (Daily Logs): memory/YYYY-MM-DD.md - Append-only daily notes
• L2 (Long-Term Memory): MEMORY.md - Curated, permanent knowledge
• L3 (Vector Search): memory_search - Semantic search via memory-core plugin

Why You Need This

Without this system:

• Agents wake up "fresh" every session, forgetting previous conversations
• Context is lost between restarts
• Repeated questions about preferences, past decisions, and project status
• No searchable history of what happened when

With this system:

• Persistent memory across all sessions
• Daily logs capture everything; long-term memory preserves what matters
• Vector search finds relevant context instantly
• Automatic prompts to save memory before compaction
• Privacy-safe (MEMORY.md only loads in private sessions)

Before You Install

Prerequisites

• OpenClaw workspace initialized
• Write access to workspace directory
• (Optional) memory-core plugin for L3 vector search
• (Optional) Embedding API key for vector search

Diagnostic Check

Run the audit script to see your current memory state:

bash scripts/audit.sh

This will output JSON showing:

• Whether MEMORY.md exists and its size
• Whether memory/ directory exists and file count
• Whether memory_search is available

Pros & Cons

✅ Advantages

1. Persistent Context: Agents remember across sessions
2. Two-Layer Freshness: Daily logs for raw data, curated memory for insights
3. Semantic Search: Find relevant memories by meaning, not just keywords
4. Auto-Flush: Prompts to save before compaction (prevents memory loss)
5. Weekly Maintenance: Structured review process keeps memory current
6. Privacy Protection: MEMORY.md only loads in main sessions (not shared contexts)

⚠️ Disadvantages

1. MEMORY.md Bloat: Can grow large over time, increasing token usage
2. Embedding API Cost: L3 vector search requires external API (e.g., Voyage)
3. Disk Usage: Daily logs accumulate (mitigate with archiving)
4. Maintenance Required: L2 becomes stale if not reviewed regularly
5. Manual Curation: Requires discipline to update MEMORY.md from daily logs

Installation

Interactive Setup

IMPORTANT: This will modify your workspace. You will be asked to confirm before proceeding.

1. Review the diagnostic output:

   bash scripts/audit.sh
   

2. Understand what will change:

   • Creates memory/ directory (if missing)
   • Creates MEMORY.md from template (backs up existing)
   • Appends memory rules to AGENTS.md
   • Appends maintenance tasks to HEARTBEAT.md

3. Run setup:

   bash scripts/setup.sh /Users/ishikawaryuuta/.openclaw/workspace
   

4. The script will:

   • Show you what it plans to do
   • Ask for confirmation (y/n)
   • Back up existing files before modification
   • Report success or failure

What Gets Created/Modified

Created:

• memory/ directory
• MEMORY.md (if missing; existing files are backed up)

Modified:

• AGENTS.md - Appends memory system rules
• HEARTBEAT.md - Appends weekly maintenance task

Backups:

• Existing files are backed up with .backup-TIMESTAMP suffix

Usage

Daily Workflow

At the start of each session, the agent should:

1. Read memory/YYYY-MM-DD.md (today + yesterday)
2. Read MEMORY.md (main session only)

During the session:

• Write to memory/YYYY-MM-DD.md as things happen
• Update MEMORY.md for significant decisions or insights

Before compaction:

• Agent is prompted to save important context to memory

Weekly Maintenance

Run the maintenance helper:

bash scripts/maintenance.sh

This scans the last 7 days of daily logs and suggests items to integrate into MEMORY.md.

Manual review:

1. Read suggested items
2. Update MEMORY.md with distilled insights
3. Remove outdated information from MEMORY.md

Memory Search (L3)

If you have the memory-core plugin installed:

// Search for relevant memories
memory_search("project decisions about X")

This uses vector embeddings to find semantically similar content across all memory files.

File Structure

workspace/
├── MEMORY.md                    # L2: Long-term curated memory
├── memory/                      # L1: Daily logs
│   ├── 2026-02-09.md
│   ├── 2026-02-10.md
│   └── heartbeat-state.json     # Heartbeat tracking
├── AGENTS.md                    # Includes memory rules
└── HEARTBEAT.md                 # Includes maintenance tasks

Maintenance Scripts

audit.sh

Purpose: Diagnose current memory state
Usage: bash scripts/audit.sh
Output: JSON summary of memory system status

setup.sh

Purpose: Install memory system in workspace
Usage: bash scripts/setup.sh <workspace_path>
Safety: Non-destructive, backs up existing files, asks for confirmation

maintenance.sh

Purpose: Suggest L2 integration candidates from recent L1 logs
Usage: bash scripts/maintenance.sh
Output: List of items to review for MEMORY.md

Privacy & Security

• MEMORY.md contains personal context and should ONLY be loaded in private/main sessions
• Daily logs can contain sensitive information; avoid sharing raw logs
• Vector embeddings are stored by the memory-core plugin (check plugin docs for data handling)

Troubleshooting

MEMORY.md is too large

• Archive old sections to memory/archive/
• Distill multiple related items into single entries
• Remove outdated information

Daily logs pile up

• Create memory/archive/YYYY-MM/ and move old logs
• Keep 30-90 days active, archive the rest

Memory search not working

• Check if memory-core plugin is installed
• Verify embedding API key is configured
• Re-index if necessary (see plugin docs)

Setup fails

• Check workspace path is correct
• Ensure write permissions
• Review error messages in script output

Advanced: Customization

Modify Templates

Edit files in templates/ before running setup:

• MEMORY.md.template - Customize section structure
• memory-rules.md - Adjust memory rules
• heartbeat-memory.md - Change maintenance frequency

Extend Scripts

All scripts are pure bash, zero dependencies. Modify as needed for your workflow.

Support

This is a self-contained skill. Refer to:

• Script source code (heavily commented)
• OpenClaw AGENTS.md for memory system rules
• memory-core plugin docs for L3 vector search

---

Version: 1.0
Compatibility: OpenClaw (macOS/Linux)
Dependencies: None (L3 requires memory-core plugin + embedding API)

File v1.0.0:_meta.json

{ "ownerId": "kn70hcm6kss09g9b4pe5rq3ybd80qp15", "slug": "memory-mastery", "version": "1.0.0", "publishedAt": 1770654940793 }

File v1.0.0:templates/heartbeat-memory.md

🧠 Memory Maintenance (Memory Mastery)

Run every few days during heartbeats:

1. Read memory/YYYY-MM-DD.md files from the past week

2. Identify significant decisions, lessons, or insights

3. Update MEMORY.md with distilled learnings

4. Remove outdated info from MEMORY.md that's no longer relevant

5. Optional: run bash skills/memory-mastery/scripts/maintenance.sh for suggestions

Think of it like reviewing a journal and updating your mental model.

Daily files = raw notes. MEMORY.md = curated wisdom.

File v1.0.0:templates/memory-rules.md

🧠 Memory System (Memory Mastery)

Three-Layer Architecture

| Layer | Location | Purpose | |-------|----------|---------| | L1 | memory/YYYY-MM-DD.md | Daily log (append-only) | | L2 | MEMORY.md | Long-term curated memory | | L3 | memory_search | Vector search (memory-core plugin) |

Session Startup

1. Read memory/YYYY-MM-DD.md for today and yesterday
2. In main/private sessions: also read MEMORY.md
3. Never load MEMORY.md in group chats (security)

Writing Rules

1. On task completion → Append to today's memory/YYYY-MM-DD.md (L1)
2. Important decisions → Write to L1 AND update MEMORY.md (L2)
3. "Remember this" → Write to file immediately. No mental notes!
4. Mistakes & lessons → Record in L1 + update relevant docs
5. Text > Brain — if you want to remember it, WRITE IT DOWN 📝

Searching

• Use memory_search tool to semantically search across all memory files
• After searching, use memory_get to pull specific lines for context

Weekly Maintenance

Every 5-7 days (during heartbeat or when prompted):

1. Review recent memory/YYYY-MM-DD.md files
2. Identify decisions, lessons, and insights worth keeping long-term
3. Update MEMORY.md with distilled learnings
4. Remove outdated info from MEMORY.md
5. Run bash skills/memory-mastery/scripts/maintenance.sh for suggestions

Security

• MEMORY.md contains personal context — NEVER load in shared/group sessions
• Don't exfiltrate memory contents to external services
• API keys in memory should be references, not raw values