PowerMem + OpenClaw: maximum token savings for AI agents.

OpenClaw Memory (PowerMem) Plugin

This plugin lets OpenClaw use long-term memory via the PowerMem HTTP API: intelligent extraction, Ebbinghaus forgetting curve, multi-agent isolation.

Follow the steps in order: install and start PowerMem, then install the plugin, configure OpenClaw, and verify.

Prerequisites

• OpenClaw installed (CLI + gateway working)
• PowerMem server: install and run it separately (choose one of the two methods below)
• For PowerMem’s “intelligent extraction”: configure LLM + Embedding API keys in PowerMem’s .env (e.g. Qwen / OpenAI)

Step 1: Install and start PowerMem

Choose Option A (pip) or Option B (Docker).

Option A: Install with pip (run server locally)

Best if you already have Python 3.11+.

1. Install PowerMem

pip install powermem

2. Prepare config

In any directory where you want to keep config (e.g. ~/powermem):

mkdir -p ~/powermem && cd ~/powermem
# Copy from PowerMem repo: if you cloned it, run: cp /path/to/powermem/.env.example .env

If you did not clone the PowerMem repo, create a .env with at least: database + LLM + Embedding. Here is a minimal working example (OceanBase + Qwen; replace with your API key and DB credentials):

# Create .env in ~/powermem (replace your_api_key_here and your_password)
cat > .env << 'EOF'
TIMEZONE=Asia/Shanghai
DATABASE_PROVIDER=oceanbase

OCEANBASE_HOST=127.0.0.1
OCEANBASE_PORT=2881
OCEANBASE_USER=root@sys
OCEANBASE_PASSWORD=your_password
OCEANBASE_DATABASE=powermem
OCEANBASE_COLLECTION=memories

LLM_PROVIDER=qwen
LLM_API_KEY=your_api_key_here
LLM_MODEL=qwen-plus

EMBEDDING_PROVIDER=qwen
EMBEDDING_API_KEY=your_api_key_here
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIMS=1536
EOF

Replace your_api_key_here with your Qwen API key and your_password with your OceanBase password. For SQLite (simplest local setup). For OpenAI or others, see PowerMem’s .env.example for LLM_* and EMBEDDING_*.

3. Start the HTTP server

Run this in the same directory as .env:

cd ~/powermem   # or wherever .env lives
powermem-server --host 0.0.0.0 --port 8000

You should see something like Uvicorn running on http://0.0.0.0:8000. Leave this terminal open.

4. Verify PowerMem

In a new terminal:

curl -s http://localhost:8000/api/v1/system/health

If you get JSON (e.g. with "status":"healthy"), PowerMem is ready.

Option B: Run with Docker (no Python needed)

Best if you have Docker and prefer not to install Python.

1. Clone PowerMem and prepare .env

git clone https://github.com/oceanbase/powermem.git
cd powermem
cp .env.example .env

Edit .env and set at least:

• LLM_API_KEY, LLM_PROVIDER, LLM_MODEL
• EMBEDDING_API_KEY, EMBEDDING_PROVIDER, EMBEDDING_MODEL

Database can stay default; OceanBase is recommended (see .env.example).

2. Start the container

From the powermem project root (same level as .env):

docker-compose -f docker/docker-compose.yml up -d

3. Verify

curl -s http://localhost:8000/api/v1/system/health

JSON response means the server is up. API docs: http://localhost:8000/docs.

Install options

• One-click (Linux/macOS): See INSTALL.md for install.sh (curl or run from repo root).
• Let OpenClaw install it: Copy skills/install-powermem-memory/SKILL.md to ~/.openclaw/skills/install-powermem-memory/, then tell OpenClaw 「安装 PowerMem 记忆」 or “Install PowerMem memory”.
• Manual: Steps below.

Step 2: Install the plugin into OpenClaw

On your machine (use your actual plugin path):

# Install from npm (recommended for end users; OpenClaw downloads the package from the npm registry)
openclaw plugins install openclaw-extension-powermem

# Install from a local directory (e.g. cloned repo)
openclaw plugins install /path/to/openclaw-extension-powermem

# For development (symlink, no copy)
openclaw plugins install -l /path/to/openclaw-extension-powermem

Note: Running npm i openclaw-extension-powermem in a Node project only adds the package to that project’s node_modules; it does not register the plugin with OpenClaw. To use this as an OpenClaw plugin, you must run openclaw plugins install openclaw-extension-powermem (or install from a path as above), then restart the gateway.

After install, run openclaw plugins list and confirm memory-powermem is listed. The plugin uses default config when none is set: baseUrl: "http://localhost:8000", autoCapture, autoRecall, and inferOnAdd enabled — so you do not need to edit ~/.openclaw/openclaw.json for the typical setup (PowerMem on localhost:8000).

Step 3: Configure OpenClaw (optional)

If you use PowerMem at http://localhost:8000 with the default options, skip this step. To customize (e.g. different URL, API key, or CLI mode), edit OpenClaw's config (e.g. ~/.openclaw/openclaw.json) and add or merge the plugins section.

Example (JSON):

{
  "plugins": {
    "slots": { "memory": "memory-powermem" },
    "entries": {
      "memory-powermem": {
        "enabled": true,
        "config": {
          "baseUrl": "http://localhost:8000",
          "autoCapture": true,
          "autoRecall": true,
          "inferOnAdd": true
        }
      }
    }
  }
}

CLI mode (no server): To use the PowerMem CLI instead of the HTTP server (same machine, no powermem-server), set "mode": "cli" and optionally envFile / pmemPath:

"config": {
  "mode": "cli",
  "envFile": "/path/to/powermem/.env",
  "pmemPath": "pmem",
  "autoCapture": true,
  "autoRecall": true,
  "inferOnAdd": true
}

Notes:

• HTTP (default): baseUrl is required; PowerMem HTTP base URL without /api/v1, e.g. http://localhost:8000. If PowerMem has API key auth, add "apiKey": "your-key".
• CLI: Set mode to "cli". Optional: envFile (path to PowerMem .env), pmemPath (default pmem). Requires pmem on PATH and a valid PowerMem config (e.g. .env).
• Restart the OpenClaw gateway (or Mac menubar app) after changing config.

Step 4: Verify plugin and PowerMem connection

In a terminal:

# Check PowerMem reachability
openclaw ltm health

If there are no errors and you see a healthy status, the plugin is talking to PowerMem.

Then try a manual add and search:

# Add a memory
openclaw ltm add "I prefer a cup of Americano every morning"

# Search by content
openclaw ltm search "coffee"

If search returns the line you added (or similar), the full flow (PowerMem → plugin → OpenClaw) is working.

Config options (optional)

| Option | Required | Description | |---------------|----------|-------------| | mode | No | Backend: "http" (default) or "cli". Use cli to run pmem locally without a server. | | baseUrl | Yes (http) | PowerMem API base URL when mode is http, e.g. http://localhost:8000, no /api/v1 suffix. | | apiKey | No | Set when PowerMem server has API key authentication enabled (http mode). | | envFile | No | CLI mode: path to PowerMem .env file. Optional; pmem discovers if omitted. | | pmemPath | No | CLI mode: path to pmem executable; default pmem. | | userId | No | User isolation (multi-user); default openclaw-user. | | agentId | No | Agent isolation (multi-agent); default openclaw-agent. | | autoCapture | No | Auto-store from conversations after agent ends; default true. | | autoRecall | No | Auto-inject relevant memories before agent starts; default true. | | inferOnAdd | No | Use PowerMem intelligent extraction when adding; default true. |

Auto-capture: When a conversation ends, user/assistant text is sent to PowerMem with infer: true. PowerMem extracts and stores memories. At most 3 chunks per session (each up to 6000 chars).

Agent tools

Exposed to OpenClaw agents:

• memory_recall — Search long-term memories by query.
• memory_store — Save information (with optional infer).
• memory_forget — Delete by memory ID or by search query.

OpenClaw CLI (when plugin enabled)

• openclaw ltm search <query> [--limit n] — Search memories.
• openclaw ltm health — Check PowerMem server health.
• openclaw ltm add "<text>" — Manually store one memory.

Troubleshooting

1. openclaw ltm health fails or cannot connect

• Ensure PowerMem is running (Option A terminal still open, or Docker container up).
• Ensure baseUrl matches the real address: use http://localhost:8000 for local (avoid 127.0.0.1 unless you know it matches).
• If OpenClaw and PowerMem are on different machines, use PowerMem’s host IP or hostname instead of localhost.

2. Add/search returns nothing or 500

• Check PowerMem terminal or Docker logs; often LLM/Embedding not configured or wrong API key.
• Ensure LLM_API_KEY and EMBEDDING_API_KEY in .env are set and valid.

3. Plugin installed but OpenClaw not using memory

• Confirm plugins.slots.memory is memory-powermem and plugins.entries["memory-powermem"].enabled is true.
• Restart the gateway (or OpenClaw app) after config changes.

4. Agent does not search memory until I ask it to

• With autoRecall: true, the plugin injects system guidance so the agent is told to use memory_recall (or injected <relevant-memories>) when answering about past events, preferences, or people. Ensure autoRecall is not set to false.
• Auto-recall runs before each turn using the current user message (or the last user message if the prompt is very short). If you still see the agent answering without checking memory, try being explicit once (e.g. "check your memory for …") and ensure the run uses the plugin (e.g. web UI after /new uses the same gateway and plugin).

5. Agent tries to read memory/YYYY-MM-DD.md and gets ENOENT

• OpenClaw's built-in session-memory hook writes session snapshots to workspace memory/YYYY-MM-DD-slug.md. When you use PowerMem as the memory slot, the agent may still be told (by workspace docs or inference) to load those files, causing failed read calls. Disable the hook so only PowerMem is used: run openclaw hooks disable session-memory, or set hooks.internal.entries["session-memory"].enabled to false in ~/.openclaw/openclaw.json. Restart the gateway after changing config.

Development

cd /path/to/openclaw-extension-powermem
pnpm install
pnpm lint   # type-check
pnpm test   # run tests (if any)

License

Apache License 2.0. See LICENSE.