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
• Linux/macOS: ./scripts/install.sh -WorkspacePath
• The installer creates: MEMORY.md, HEARTBEAT.md, memory/ directory, templates, cron configs

1. 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

1. 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

1. 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

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

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