Installation FAQ

The most common cause: the hourly checkpoint cron job didn't register because the OpenClaw gateway wasn't running at install time. Setup registers this job automatically, but silently skips it if the gateway is offline.

Check whether the job exists:

openclaw cron list | grep -i checkpoint

If nothing shows up, register it manually:

openclaw cron add \
  --name "memory-db: Auto-checkpoint" \
  --every 1h \
  --session isolated \
  --wake now \
  --message "exec python3 ~/clawd/skills/memory-db/auto-checkpoint.py --quiet --enable-inference-jobs"

The --enable-inference-jobs flag is required. Without it, the learning pipeline stays inactive even if the rest of the setup is correct.

The retrieval-learning system requires a config flag in the database. Verify it's set:

sqlite3 ~/memory.db "SELECT value FROM memory_config WHERE key='memory.learning.enabled';"

If it returns nothing, run migrations to apply the missing setting:

python3 ~/clawd/skills/memory-db/migrate.py migrate

This is safe to run on any existing install — it only applies what's missing.

Check your current version:

python3 --version

On Ubuntu/Debian systems that ship Python 3.8, install a newer version via the deadsnakes PPA:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.10
python3.10 setup.py install

On macOS, use Homebrew: brew install python@3.11

v2026.3.13+ OpenClaw 2026.3.13 enforces strict payload rules for cron jobs. Check your run log:

openclaw cron runs --id <job-id>

If you see "isolated job requires payload.kind=agentTurn" or errors mentioning exec payload kind, the job needs to be re-registered. The valid combinations are:

--session isolated → agentTurn payload (used by auto-checkpoint)
--session main → systemEvent payload

The exec payload kind is no longer valid. Remove the old job and register a new one with the command shown in the question above.

On newer installations the CLI is openclaw rather than clawdbot. Check which one is installed:

which clawdbot || which openclaw

If only openclaw is present, use openclaw cron add wherever the docs say clawdbot cron add — the flags are identical.

No — this is normal. The database is created empty. The bot writes to it during conversations, and the cron job checkpoints those conversations hourly.

After your first session, run stats.py again:

python3 ~/clawd/skills/memory-db/stats.py

You should see row counts in conversation_transcripts and conversation_log.

Setup automatically searches for your bot config file. Make sure ~/clawd/ exists and contains either AGENTS.md or SOUL.md. If your bot config is in a non-standard location, run setup from inside that directory.

The skill is already installed. To verify it's healthy:

python3 ~/clawd/skills/memory-db/setup.py check

To start over from scratch:

python3 ~/clawd/skills/memory-db/setup.py uninstall

Uninstall restores your bot config from backup and lets you choose what to do with memory.db — keep it, archive it, or delete it.

When upgrading, always run migrations after replacing the files:

python3 ~/clawd/skills/memory-db/migrate.py status
python3 ~/clawd/skills/memory-db/migrate.py migrate

Migrations are idempotent — running them again on an already-current DB does nothing. They only apply what's missing. Your data is never touched.

Windows is not supported. OpenClaw itself doesn't run natively on Windows, and the shell commands baked into the bot config are bash-specific.

Windows users: install WSL2 with Ubuntu, then follow the standard Linux instructions from inside the WSL2 terminal.