Use whenever the user wants persistent memory across OpenClaw sessions, mentions MEMORY.md, daily notes, cron inbox, heartbeat routines, agent identity, or '...
--- name: openclaw-memory-system description: "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.
don't have the plugin yet? install it then click "run inline in claude" again.