Agent Memory Setup

Set up a complete 3-tier memory system for any OpenClaw agent. Includes directory structure, memory files, semantic search, and context compaction.

Quick Start

# 1. Run setup script
bash scripts/setup_memory.sh /path/to/workspace

# 2. Copy AGENTS.md template to workspace
# (read references/AGENTS_TEMPLATE.md, adapt, write to workspace/AGENTS.md)

# 3. Add config to openclaw.json (see Step 3 below for exact JSON)

# 4. Restart
openclaw gateway restart

For full details, read the sections below.

When NOT to Use This Skill

• Backing up or exporting memory — this skill sets up memory, it doesn't handle backup/migration
• Memory is already set up — run the verification checklist in Step 4 instead of re-running setup
• Debugging a specific memory issue — check the Troubleshooting section directly
• Changing memory tier content — that's the agent's job during normal operation, not a setup task

Prerequisites

Before running setup, ensure:

• OpenClaw CLI is installed and on your PATH (openclaw --version). If not installed, the setup script will still create directories and memory files, but plugin installation and config changes must be done manually.
• Python 3.8+ (for QMD only — optional). Check with python3 --version. QMD provides semantic search (memory_search) over memory files. The core memory system (tiers, daily logs, Lossless Claw) works fully without it. If you can't install QMD (no Python, restricted server), you lose semantic search but keep everything else.
• Node.js 18+ (for OpenClaw and Lossless Claw plugin).

Platform Notes

• Linux: Fully supported. No special considerations.
• macOS: Fully supported. Config lives at ~/.openclaw/openclaw.json (same as Linux). The setup script uses POSIX-compatible date and mkdir — no GNU-specific flags.
• Windows (WSL2): Supported via WSL2 with Ubuntu or similar. Run everything inside WSL, not from Windows CMD/PowerShell. Gotcha: If your workspace is on a Windows-mounted drive (/mnt/c/...), file permissions may behave unexpectedly — prefer using a path inside the WSL filesystem (~/workspace) for reliable permission handling. The script's set -euo pipefail and mkdir -p work fine under WSL2.
• Windows (native): Not supported. OpenClaw requires a Unix shell.

Setup Steps

Step 1: Run the setup script

bash scripts/setup_memory.sh /path/to/agent/workspace

This creates:

• memory/, memory/hot/, memory/warm/ directories
• memory/hot/HOT_MEMORY.md (active session state)
• memory/warm/WARM_MEMORY.md (stable config & preferences)
• MEMORY.md (long-term archive)
• memory/YYYY-MM-DD.md (today's daily log)
• memory/heartbeat-state.json (heartbeat tracking)

It also checks for QMD and Lossless Claw, installing them if possible.

Step 2: Copy the AGENTS.md template

Read references/AGENTS_TEMPLATE.md and write it to the agent's workspace as AGENTS.md.