Agent Notebook

Use whenever the user wants persistent memory across OpenClaw sessions, mentions MEMORY.md, daily notes, cron inbox, heartbeat routines, agent identity, or 'my agent forgot everything.' Also trigger when setting up a new agent workspace, configuring memory extraction crons, or any time the user asks how to make their agent remember things between runs.

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

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

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

5. Check if cron inbox needs processing
6. 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

Script	Purpose
install.ps1 / install.sh	One-command setup
setup-cron.ps1 / setup-cron.sh	Configure automated cron jobs
memory-extract.ps1 / memory-extract.sh	Nightly extraction from daily notes
heartbeat-check.ps1 / heartbeat-check.sh	Periodic inbox processing

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