Install Powermem Memory

Step-by-step guide to install and configure the PowerMem long-term memory plugin (full path, options, troubleshooting). After setup, the plugin auto-captures...

PowerMem Memory Guide

This skill folder includes supplementary docs:

• powermem-intro.md — What PowerMem is, features, vs file-based memory.
• config-reference.md — Config keys, state dir, commands.

How It Works

• Auto-Capture: After a conversation, the plugin sends valuable user/assistant text to PowerMem (optional infer / intelligent extraction).
• Auto-Recall: Before each turn, it searches memories and can inject a <relevant-memories> block into context.

When User Asks to Install

Recommended order (TO C): (1) OpenClaw installed and default model + provider auth configured. (2) Python 3.10+ verified (python3 --version) before venv / pip install. (3) pip install powermem and pmem available to the gateway (PATH or pmemPath). (4) Install the memory-powermem plugin. No powermem.env is required for the default path.

The curl install.sh deploys the plugin and OpenClaw entries; with -y it may still create ~/.openclaw/powermem/powermem.env as an optional template—it does not run pip install powermem. That file is not required if the user relies on OpenClaw-injected LLM + default SQLite.

1. Check OpenClaw
   openclaw --version. If missing: npm install -g openclaw, openclaw onboard.
   Ensure agents.defaults.model is set (e.g. openai/gpt-4o-mini) and the corresponding provider / API key works for normal chat—the plugin reuses that for PowerMem when useOpenClawModel is true (default).

2. Check Python (required before venv / pip)
   PowerMem needs Python 3.10 or newer. Run python3 --version first; the minor version must be ≥ 10 (e.g. 3.10.x, 3.12.x). Optional strict check:

   python3 -c "import sys; assert sys.version_info >= (3, 10), 'Need Python 3.10+'; print(sys.version.split()[0], 'OK')"
   

   If it fails: upgrade Python or use a specific binary (e.g. python3.12) for all commands below instead of python3.

3. Install PowerMem (CLI — default)

   • Venv recommended: e.g. python3 -m venv ~/.openclaw/powermem/.venv && source ~/.openclaw/powermem/.venv/bin/activate.
   • pip install powermem.
   • Defaults: Plugin injects SQLite at <OpenClaw stateDir>/powermem/data/powermem.db and LLM + embedding env vars derived from OpenClaw. Typical stateDir is ~/.openclaw unless the user uses another instance (OPENCLAW_STATE_DIR, --workdir).
   • Optional envFile: Path to a PowerMem .env for extra tuning. If the file exists, pmem loads it; OpenClaw-derived vars still override the same keys when useOpenClawModel is true.
   • useOpenClawModel: false: Disables injection; user must supply a complete PowerMem config via .env and/or environment variables.
   • Verify: pmem --version. If the gateway does not inherit the venv, set pmemPath to the absolute path of pmem.

4. HTTP path (enterprise / shared server)

   • Same Python 3.10+ requirement as CLI; then pip install powermem, .env in server working directory, powermem-server --host 0.0.0.0 --port 8000.
   • Check: curl -s http://localhost:8000/api/v1/system/health.

5. Install the plugin
   openclaw plugins install /path/to/memory-powermem, or install.sh from INSTALL.md.

6. Configure OpenClaw

   CLI — minimal (recommended, matches plugin defaults):
   Do not set envFile unless you need a file. Example:

   openclaw config set plugins.enabled true
   openclaw config set plugins.slots.memory memory-powermem
   openclaw config set plugins.entries.memory-powermem.config.mode cli
   openclaw config set plugins.entries.memory-powermem.config.pmemPath pmem
   openclaw config set plugins.entries.memory-powermem.config.useOpenClawModel true --json
   openclaw config set plugins.entries.memory-powermem.config.autoCapture true --json
   openclaw config set plugins.entries.memory-powermem.config.autoRecall true --json
   openclaw config set plugins.entries.memory-powermem.config.inferOnAdd true --json
   

   CLI — optional .env override file:

   openclaw config set plugins.entries.memory-powermem.config.envFile "$HOME/.openclaw/powermem/powermem.env"
   

   (Only matters if that path exists; OpenClaw can still override LLM keys when useOpenClawModel is true.)

   HTTP:

   openclaw config set plugins.entries.memory-powermem.config.mode http
   openclaw config set plugins.entries.memory-powermem.config.baseUrl http://localhost:8000
   

   Optional: apiKey if the server uses auth.

7. Verify
   Restart gateway, then in another terminal:

   openclaw plugins list
   

   Confirm memory-powermem is listed and its status is loaded. If it is missing or not loaded, fix install/slot config and restart the gateway before running LTM checks.

   openclaw ltm health
   openclaw ltm add "I prefer coffee in the morning"
   openclaw ltm search "coffee"
   

Available Tools

Tool	Description
memory_recall	Search long-term memories. Params: query, optional limit, scoreThreshold.
memory_store	Save text; optional infer. Params: text, optional importance.
memory_forget	Delete by memoryId or by query search.

Configuration (summary)

Field	Default	Description
mode	cli	cli or http.
baseUrl	—	Required for HTTP; if mode omitted and baseUrl set → HTTP.
apiKey	—	HTTP server auth.
envFile	—	Optional CLI .env (used only if file exists).
pmemPath	pmem	CLI binary path.
useOpenClawModel	true	Inject LLM/embedding from OpenClaw + default SQLite under state dir.
recallLimit	5	Max memories per recall.
recallScoreThreshold	0	Min score 0–1.
autoCapture / autoRecall / inferOnAdd	true	Auto memory pipeline and infer on add.

Daily Operations

openclaw gateway

openclaw ltm health
openclaw ltm add "Some fact to remember"
openclaw ltm search "query"

openclaw config set plugins.slots.memory none
openclaw config set plugins.slots.memory memory-powermem

Restart the gateway after slot or plugin config changes.

Troubleshooting

Symptom	Fix
Python < 3.10	Run step 2 first; upgrade Python or use python3.11 / python3.12 for venv and pip install. Do not skip the version check.
pip install powermem fails	Confirm Python 3.10+, clean venv. See PowerMem issues.
pmem not found	Activate venv or set pmemPath to the full binary.
openclaw ltm health unhealthy (CLI)	Confirm agents.defaults.model and provider keys in OpenClaw; gateway version should expose plugin config + runtime.modelAuth. Or set useOpenClawModel: false and a full envFile.
Health OK but add/search errors	Embedding/LLM mismatch for your provider—see gateway logs; try optional PowerMem .env from .env.example.
Wrong SQLite file / instance	Data is under that OpenClaw instance’s stateDir (OPENCLAW_STATE_DIR / --workdir).
HTTP mode	Server running, baseUrl correct, apiKey if enabled.
openclaw plugins list: no memory-powermem, or status is not loaded	Re-run plugin install; set plugins.enabled true and plugins.slots.memory = memory-powermem; restart gateway; run openclaw plugins list again until memory-powermem shows loaded.