OpenClaw Memory System#

What This Skill Does#

Implements a complete file-based memory architecture that persists across OpenClaw sessions. Agents wake up with full context instead of starting from zero.

When to Trigger#

• User says "my agent forgets everything"
• User wants to set up memory for their agent
• User mentions MEMORY.md, daily notes, cron inbox, or heartbeat routines
• User asks how to make agent remember between sessions
• Setting up a new agent workspace
• Configuring cron jobs for memory extraction

Installation (Agent Instructions)#

When this skill triggers, the agent should:

1. Run the installer script from the skill directory:
   • Windows: ./scripts/install.ps1 -WorkspacePath <workspace>
   • Linux/macOS: ./scripts/install.sh -WorkspacePath <workspace>
   • The installer creates: MEMORY.md, HEARTBEAT.md, memory/ directory, templates, cron configs
2. Verify installation by checking these files exist:
   • MEMORY.md — curated long-term memory
   • HEARTBEAT.md — periodic check routines
   • memory/cron-inbox.md — cross-session message bus
   • memory/heartbeat-state.json — state tracking
   • memory/YYYY-MM-DD.md — today's daily notes
3. Seed MEMORY.md with operator context:
   • Operator name, timezone, communication preferences
   • Active projects, priorities, decisions
   • Important people, relationships, boundaries
   • Tool preferences, coding style, review rules
4. Configure cron jobs (optional but recommended):
   • Nightly memory extraction: 23:00 daily
   • Heartbeat check: every 30 minutes
   • Use ./scripts/setup-cron.ps1 or ./scripts/setup-cron.sh

Directory Structure After Install#

text

workspace/
|-- MEMORY.md                 # Curated long-term memory
|-- HEARTBEAT.md              # Periodic check routines
|-- memory/
|   |-- YYYY-MM-DD.md         # Daily raw logs
|   |-- cron-inbox.md         # Cross-session messages
|   |-- heartbeat-state.json  # Timestamps
|   |-- diary/                # Personal reflections
|   |-- platform-posts.md     # External post tracking
|   └── strategy-notes.md     # Adaptive playbook

Daily Workflow#

On Every Session Start#

1. Read MEMORY.md — who you are, operator context, priorities
2. Read memory/YYYY-MM-DD.md (today + yesterday) — recent context
3. Check memory/cron-inbox.md — messages from other sessions

During the Session#

1. Write everything significant to memory/YYYY-MM-DD.md:

   • Decisions made, lessons learned
   • Errors encountered and how fixed
   • New projects started, completed milestones
   • Changes to operator preferences or context
   • Format: ## HH:MM -- Brief title
   • Be raw and verbose — this is working memory

Before Session Ends#

1. Check if cron inbox needs processing
2. If significant events occurred, append a summary to MEMORY.md under relevant sections

Heartbeat Routine#

The heartbeat script ( scripts/heartbeat-check.ps1 or .sh) runs periodically and:

1. Processes memory/cron-inbox.md entries into daily notes
2. Clears the inbox after processing
3. Updates memory/heartbeat-state.json with timestamps
4. Checks for stale or completed cron jobs

Memory Extraction#

The nightly cron ( scripts/memory-extract.ps1 or .sh) at 23:00:

1. Reads today's daily notes
2. Looks for significant keywords: decided, lesson, milestone, completed, shipped, fixed, breakthrough
3. Extracts matching entries with context
4. Appends to MEMORY.md under a dated "Daily Extracts" section
5. Marks daily notes as extracted

Writing Good Daily Notes#

• Timestamp every entry: ## HH:MM -- What happened
• Include context: what triggered it, what was decided, rationale
• Don't censor — this is raw working memory, not curated wisdom
• Significant entries will be extracted automatically
• Review MEMORY.md weekly to remove outdated info

Security Rules#

• MEMORY.md may contain operator-specific info — only load in trusted (direct) sessions
• Skip MEMORY.md in group chats or shared contexts
• Never share operator personal details externally without approval
• Keep private info private

Customization#

Adjust Extraction Keywords#

Edit scripts/memory-extract.ps1 (or .sh) $significanceKeywords array:

• Default: decided, lesson learned, important, breakthrough, milestone, completed, shipped, fixed
• Add domain-specific keywords as needed

Add New Heartbeat Checks#

Edit HEARTBEAT.md and scripts/heartbeat-check.* to add custom periodic checks:

• Service health checks
• File cleanup routines
• External API status checks

Change Cron Schedule#

Edit scripts/setup-cron.ps1 or scripts/setup-cron.sh:

• Memory extraction: default 23:00
• Heartbeat: default every 30 min
• Daily notes reminder: default 09:00

Troubleshooting#

Agent still forgets between sessions:

• Verify AGENTS.md includes "Read MEMORY.md on every session"
• Check that MEMORY.md file exists and is readable
• Ensure daily notes are being written

Cron inbox not processing:

• Check heartbeat-state.json for last run timestamp
• Verify cron jobs are scheduled (run ./scripts/setup-cron.*)
• Check if heartbeat-check script exists and is executable

Memory extraction not running:

• Verify cron job is scheduled
• Check that daily notes exist for extraction
• Review extraction keywords if nothing is being picked up

Templates#

All templates live in templates/:

• MEMORY.md — Long-term memory structure
• HEARTBEAT.md — Periodic routines
• daily-notes.md — Daily log format
• cron-inbox.md — Cross-session message format
• heartbeat-state.json — State tracking JSON
• platform-posts.md — External post tracking
• strategy-notes.md — Adaptive playbook

Copy these during installation; do not modify originals.

Cross-Platform#

Scripts provided for both PowerShell (Windows) and Bash (Linux/macOS):

• *.ps1 — PowerShell scripts
• *.sh — Bash scripts

Always check both versions exist when editing.

Scripts Reference#

ScriptPurposeinstall.ps1 / install.shOne-command setupsetup-cron.ps1 / setup-cron.shConfigure automated cron jobsmemory-extract.ps1 / memory-extract.shNightly extraction from daily notesheartbeat-check.ps1 / heartbeat-check.shPeriodic inbox processing

All scripts support -WorkspacePath for custom directories and -DryRun for preview.