Update OpenClaw Without Losing Memory in 12 Minutes

Safely upgrade OpenClaw to the latest version while preserving your persistent memory files, configurations, and workspace data.
·
7 min read
·
Mark
·
AI Agent

Problem: Updating OpenClaw Risks Losing Your AI's Memory

You need to update OpenClaw to get bug fixes and new features, but you're worried about losing your agent's persistent memory, custom configurations, and workspace files built up over weeks of use.

You'll learn:

  • How to safely backup OpenClaw's memory and configuration
  • The correct update process that preserves all data
  • How to verify your memory survived the update

Time: 12 min | Level: Intermediate

Why Memory Persists (But You Should Still Backup)

OpenClaw stores all persistent data as plain Markdown files in your workspace directory (default ~/clawd) and configuration in ~/.openclaw/. The update process only touches the application code, not your data files.

Common symptoms when things go wrong:

  • Memory files appear empty after update
  • Configuration reverted to defaults
  • Session history disappeared
  • Custom skills stopped working

What's at risk:

  • MEMORY.md - Curated long-term memory
  • memory/YYYY-MM-DD.md - Daily logs
  • ~/.openclaw/openclaw.json - Configuration
  • ~/.openclaw/credentials/ - API keys and OAuth tokens
  • Session transcripts and indexed data

Solution

Step 1: Backup Your State Directory

# Create timestamped backup directory
BACKUP_DIR="$HOME/openclaw-backups/$(date +%Y-%m-%d-%H%M)"
mkdir -p "$BACKUP_DIR"

# Backup state directory (config, credentials, sessions)
cp -r ~/.openclaw "$BACKUP_DIR/state"

# Backup workspace (memory files)
cp -r ~/clawd "$BACKUP_DIR/workspace"

Expected: You'll see two new directories in ~/openclaw-backups/2026-02-06-HHMM/

Critical files backed up:

  • Configuration: ~/.openclaw/openclaw.json
  • Credentials: ~/.openclaw/credentials/*.json
  • Memory index: ~/.openclaw/memory/<agentId>.sqlite
  • Sessions: ~/.openclaw/agents/<agentId>/sessions/*.jsonl
  • Workspace memory: ~/clawd/MEMORY.md and ~/clawd/memory/*.md

If using custom paths:

# Check your actual paths first
openclaw config get agents.defaults.workspace
openclaw config get agents.defaults.memorySearch.store.path

# Adjust backup commands accordingly

Step 2: Stop the Gateway Service

# Stop the running gateway
openclaw gateway stop

# Verify it stopped
openclaw gateway status

Expected: Status shows "Gateway is not running" or similar

Platform-specific verification:

# macOS (if using launchd)
launchctl list | grep openclaw

# Linux/WSL2 (if using systemd)
systemctl --user status openclaw-gateway

If it won't stop:

# Find and kill the process
ps aux | grep openclaw
kill -9 <PID>

Step 3: Run the Update

Recommended method (re-run installer):

# This auto-detects your install and upgrades in place
curl -fsSL https://openclaw.bot/install.sh | bash -- --no-onboard

Alternative: Update via npm (if globally installed):

# Check your current version first
openclaw --version

# Update to latest
npm i -g openclaw@latest

# Or update to specific version
npm i -g openclaw@2026.1.30

For source installs (git checkout):

# Let OpenClaw handle the update
openclaw update

# Or manual equivalent
cd ~/openclaw  # your git repo location
git fetch origin
git checkout main
git pull
pnpm install
pnpm build

Why --no-onboard matters: Prevents the onboarding wizard from running again, which could reset certain configurations.

Expected output:

  • Download progress bar
  • Dependency installation
  • Build completion messages
  • "openclaw doctor" running automatically

Step 4: Run Doctor and Verify Config

# Check for config migrations and health issues
openclaw doctor

# Review your configuration
openclaw config get agents.defaults.memorySearch

Expected: Doctor should report "All checks passed" or specific migration notices

What doctor does:

  • Migrates deprecated config keys automatically
  • Checks memory index integrity
  • Verifies gateway service configuration
  • Warns about security issues

If migrations occurred:

# Review what changed
diff ~/.openclaw/openclaw.json "$BACKUP_DIR/state/.openclaw/openclaw.json"

Common migrations in 2026:

  • .clawdbot paths → .openclaw paths
  • Legacy session storage formats
  • Memory search provider defaults
  • OAuth credential structures

Step 5: Restart Gateway and Test Memory

# Start the gateway
openclaw gateway restart

# Wait a few seconds for startup
sleep 5

# Check health
openclaw health

Expected: Health check shows all services green

Test memory persistence:

# Check memory files exist
ls -lh ~/clawd/MEMORY.md
ls -lh ~/clawd/memory/

# Verify memory search works (via CLI message)
openclaw message "What do you remember about my preferences?"

# Check memory index status
openclaw memory status

You should see:

  • Memory files with same timestamps as before update
  • Memory search returning relevant results
  • Session history intact

Step 6: Verify Vector Index Integrity

# Check memory search backend status
openclaw config get memory.backend

# If using QMD backend, verify it's running
qmd --version
openclaw memory rebuild  # Force reindex if needed

# If using built-in SQLite
ls -lh ~/.openclaw/memory/*.sqlite

Expected: Memory database file size should be similar to pre-update

If memory search fails:

# Force rebuild the index
openclaw memory rebuild --force

# Or switch embedding providers
openclaw config set agents.defaults.memorySearch.provider openai
openclaw gateway restart

Why rebuilds might be needed: Embedding model changes or index format updates can trigger automatic reindexing. This is normal and preserves your data.

Verification

Complete verification checklist:

# 1. Gateway running
openclaw gateway status

# 2. Memory files intact
wc -l ~/clawd/MEMORY.md  # Line count should match
md5sum ~/clawd/MEMORY.md  # Compare checksum with backup

# 3. Configuration preserved
openclaw config get agents.defaults.workspace
openclaw config get memory

# 4. Credentials work
openclaw message "Test message"  # Should authenticate successfully

# 5. Memory search functional
openclaw message "Search your memory for 'test'"

You should see:

  • Gateway status: Running
  • Memory files: Same content as before
  • Config: Your customizations intact
  • Test message: Delivered successfully
  • Memory search: Returns results from old entries

Troubleshooting Common Issues

Memory Files Empty After Update

Symptom: MEMORY.md exists but has no content

Fix:

# Restore from backup
cp "$BACKUP_DIR/workspace/clawd/MEMORY.md" ~/clawd/MEMORY.md
cp -r "$BACKUP_DIR/workspace/clawd/memory/" ~/clawd/

# Rebuild index
openclaw memory rebuild
openclaw gateway restart

Gateway Won't Start

Symptom: openclaw gateway status shows failed

Fix:

# Check logs for specific error
openclaw logs --tail 50

# Common issues:
# 1. Port already in use
lsof -i :18789
kill -9 <PID>

# 2. Config syntax error
openclaw doctor --fix

# 3. Permission issues
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

Memory Search Not Working

Symptom: "memory_search" tool unavailable

Fix:

# Check embedding provider configuration
openclaw config get agents.defaults.memorySearch.provider

# Reset to working defaults
openclaw config set agents.defaults.memorySearch.provider openai
openclaw config set agents.defaults.memorySearch.enabled true

# Verify API key available
echo $OPENAI_API_KEY

# Rebuild index
openclaw memory rebuild

Session History Missing

Symptom: Past conversations not accessible

Fix:

# Restore sessions from backup
cp -r "$BACKUP_DIR/state/.openclaw/agents/*/sessions/" \
      ~/.openclaw/agents/main/sessions/

# If using QMD for session indexing
openclaw config get memory.qmd.sessions.enabled
qmd update  # Trigger reindex

What You Learned

  • OpenClaw stores memory as plain Markdown files separate from the application code
  • The update process preserves your data but backups provide safety
  • openclaw doctor handles most migrations automatically
  • Memory indexes may need rebuilding if embedding models change

Key insight: Your data lives in ~/.openclaw/ and ~/clawd/, which updates never delete. The actual risk is configuration changes requiring manual adjustment.

Limitations:

  • Breaking changes between major versions may require manual config edits
  • Embedding model updates force reindexing (preserves data, takes time)
  • QMD backend requires separate binary updates

Next steps:

Advanced: Automated Backup Script

Save this as ~/bin/openclaw-backup.sh:

#!/bin/bash
set -euo pipefail

# Configuration
BACKUP_BASE="${OPENCLAW_BACKUP_DIR:-$HOME/openclaw-backups}"
RETENTION_DAYS=7
TIMESTAMP=$(date +%Y-%m-%d-%H%M)
BACKUP_DIR="$BACKUP_BASE/$TIMESTAMP"

# Detect state directory (handles legacy paths)
STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
if [ -d "$HOME/.moltbot" ] && [ ! -d "$HOME/.openclaw" ]; then
    STATE_DIR="$HOME/.moltbot"
fi

# Get workspace path from config (or default)
WORKSPACE=$(openclaw config get agents.defaults.workspace 2>/dev/null || echo "$HOME/clawd")

echo "🦞 OpenClaw Backup Starting..."
echo "State: $STATE_DIR"
echo "Workspace: $WORKSPACE"
echo "Destination: $BACKUP_DIR"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Backup state (config, credentials, indexes)
echo "📦 Backing up state directory..."
tar czf "$BACKUP_DIR/state.tar.gz" \
    -C "$(dirname "$STATE_DIR")" \
    "$(basename "$STATE_DIR")"

# Backup workspace (memory files)
if [ -d "$WORKSPACE" ]; then
    echo "📦 Backing up workspace..."
    tar czf "$BACKUP_DIR/workspace.tar.gz" \
        -C "$(dirname "$WORKSPACE")" \
        "$(basename "$WORKSPACE")"
fi

# Save version info
openclaw --version > "$BACKUP_DIR/version.txt"
openclaw gateway status > "$BACKUP_DIR/status.txt" 2>&1 || true

# Cleanup old backups
echo "🧹 Removing backups older than $RETENTION_DAYS days..."
find "$BACKUP_BASE" -maxdepth 1 -type d -mtime +"$RETENTION_DAYS" -exec rm -rf {} \;

# Summary
BACKUP_SIZE=$(du -sh "$BACKUP_DIR" | cut -f1)
echo "✅ Backup complete: $BACKUP_SIZE at $BACKUP_DIR"

Usage:

# Make executable
chmod +x ~/bin/openclaw-backup.sh

# Run before updates
~/bin/openclaw-backup.sh

# Automate with cron (daily at 2 AM)
echo "0 2 * * * $HOME/bin/openclaw-backup.sh" | crontab -

Channel Management

OpenClaw has three update channels:

Stable (recommended for production):

openclaw update --channel stable

Beta (new features, minor bugs):

openclaw update --channel beta

Dev (bleeding edge, expect breakage):

openclaw update --channel dev

Check current channel:

openclaw config get update.channel

Why channel matters for memory:

  • Stable: Migrations well-tested, safest for production memory
  • Beta: New memory features may require index rebuilds
  • Dev: Can introduce breaking changes to memory schema

Rollback If Something Breaks

Restore from backup:

# Stop gateway
openclaw gateway stop

# Restore state and workspace
BACKUP_DIR="$HOME/openclaw-backups/2026-02-06-1430"  # your backup
cp -r "$BACKUP_DIR/state/.openclaw" ~/
cp -r "$BACKUP_DIR/workspace/clawd" ~/

# Downgrade to previous version
npm i -g openclaw@<previous-version>

# Restart
openclaw doctor
openclaw gateway restart

Pin to specific version:

# Find working version
npm view openclaw versions

# Install specific version
npm i -g openclaw@2026.1.29

# Prevent auto-updates
openclaw config set update.checkOnStart false

Source install rollback:

cd ~/openclaw  # your repo
git log --oneline  # find working commit
git checkout <commit-hash>
pnpm install
pnpm build
openclaw gateway restart

Tested on OpenClaw 2026.1.30, Node.js 22.x, macOS Sequoia, Ubuntu 24.04