OpenClaw Memory (PowerMem) Plugin

PowerMem + OpenClaw: maximum token savings for AI agents.

OpenClaw Memory (PowerMem) Plugin

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

Default: CLI mode — the plugin runs pmem locally (no powermem-server). Use HTTP mode when you already run a shared PowerMem API (teams / enterprise).

Follow the steps in order: install PowerMem, then install the plugin, configure OpenClaw (defaults work for CLI + ~/.openclaw/powermem/powermem.env), and verify.

Prerequisites

OpenClaw installed (CLI + gateway working)
PowerMem installed (pip install powermem) with pmem available — either on PATH when you start the gateway, or via absolute pmemPath in plugin config
.env for PowerMem with at least database + LLM + Embedding (see PowerMem .env.example); for individuals, prefer ~/.openclaw/powermem/powermem.env and SQLite

Step 1: Install and start PowerMem

Choose Option A (CLI, recommended for OpenClaw individuals), Option B (HTTP + pip), or Option C (Docker).

Option A: CLI + SQLite (recommended for individuals)

No HTTP server. Matches the plugin’s default (mode: cli).

Install PowerMem (venv recommended):

python3 -m venv ~/.openclaw/powermem/.venv
source ~/.openclaw/powermem/.venv/bin/activate
pip install powermem

Config — From a clone of this repo, run bash install.sh (or the curl one-liner under Install options below) to create an optional ~/.openclaw/powermem/powermem.env template, or copy from PowerMem’s .env.example. Set LLM_* and EMBEDDING_* when not relying on OpenClaw-injected models.
If pmem exists only inside the venv, set pmemPath in the plugin config to the absolute path of pmem in that venv.
Verify — With venv activated: pmem --version. After gateway start: openclaw ltm health.

Option B: Install with pip (run HTTP server locally)

Use this when you want a standalone API or are not using CLI mode. Best if you already have Python 3.11+ on the machine.

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 Tongyi Qwen API key (and set your_password and other DB fields as needed for OceanBase). For OpenAI or other providers, 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 C: 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: OceanBase is recommended.

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):
```
curl -fsSL https://raw.githubusercontent.com/ob-labs/memory-powermem/main/install.sh | bash
```
From a clone: cd /path/to/memory-powermem && bash install.sh. Non-interactive: same URL but pipe to bash -s -y. Another OpenClaw instance: bash -s -- --workdir ~/.openclaw-second. Details and troubleshooting: OpenClaw skill install-memory-powermem-full (skills/install-memory-powermem-full/).
OpenClaw skill — quickstart (install-memory-powermem): Copy skills/install-memory-powermem/SKILL.md to ~/.openclaw/skills/install-memory-powermem/, then say 「PowerMem 快速安装」 / “PowerMem quickstart” or “Minimal install memory-powermem” / “Install memory powermem minimal”.
OpenClaw skill — full guide (install-memory-powermem-full): Copy skills/install-memory-powermem-full/SKILL.md (and its sibling .md files in that folder if you mirror the repo) to ~/.openclaw/skills/install-memory-powermem-full/, then say 「安装 PowerMem 记忆」 / “Install PowerMem memory”. The quickstart and full-guide skills are independent; use whichever fits your workflow.
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; downloads and installs from the official npm registry)
openclaw plugins install memory-powermem

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

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

Note: Running npm i memory-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 memory-powermem (or install from a path as above), then restart the gateway.

After install, run openclaw plugins list and confirm memory-powermem is listed. With no plugins.entries["memory-powermem"].config, the plugin uses defaults: mode: "cli", envFile under ~/.openclaw/powermem/powermem.env, pmemPath: "pmem", plus autoCapture / autoRecall / inferOnAdd enabled. Ensure pmem is on PATH (or set pmemPath) and the env file exists and is valid.

Step 3: Configure OpenClaw (optional)

If you use CLI mode with the default paths and pmem on PATH, you can skip this step. Customize for HTTP, a different URL/API key, or a non-default envFile / pmemPath.

CLI (default):

{
  "plugins": {
    "slots": { "memory": "memory-powermem" },
    "entries": {
      "memory-powermem": {
        "enabled": true,
        "config": {
          "mode": "cli",
          "envFile": "/home/you/.openclaw/powermem/powermem.env",
          "pmemPath": "pmem",
          "autoCapture": true,
          "autoRecall": true,
          "inferOnAdd": true
        }
      }
    }
  }
}

HTTP (shared server):

"config": {
  "mode": "http",
  "baseUrl": "http://localhost:8000",
  "autoCapture": true,
  "autoRecall": true,
  "inferOnAdd": true
}

Notes:

CLI (default): You may omit mode and use CLI when baseUrl is empty; use envFile + pmemPath.
HTTP: When mode is http, baseUrl is required; if you set baseUrl without mode, the plugin treats it as HTTP. Do not append /api/v1 to baseUrl. If the server uses API key auth, add "apiKey".
Restart the OpenClaw gateway (or Mac menubar app) after changing config.

Step 4: Verify plugin and PowerMem connection

In a terminal:

# Check whether PowerMem is reachable
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 what you just added (or similar content), the full flow (install PowerMem → install plugin → configure OpenClaw) is working end to end.

OpenClaw plugin commands (reference)

Common CLI commands for managing plugins:

Command	Description
`openclaw plugins list`	List installed plugins; confirm `memory-powermem` is listed. Use `--json` for machine-readable output.
`openclaw plugins info <id>`	Show details for a plugin (e.g. `openclaw plugins info memory-powermem`).
`openclaw plugins uninstall <id>`	Remove the plugin (e.g. `openclaw plugins uninstall memory-powermem`). Use `--keep-files` to leave files on disk.
`openclaw plugins enable <id>`	Enable a disabled plugin.
`openclaw plugins disable <id>`	Disable a plugin without uninstalling.
`openclaw plugins doctor`	Diagnose plugin load and configuration issues.
`openclaw plugins update <id>`	Update a plugin installed from npm. Use `openclaw plugins update --all` to update all.

After installing, uninstalling, or changing config, restart the OpenClaw gateway for changes to take effect.

Config options (optional)

Option	Required	Description
`mode`	No	Backend: `"cli"` (default) or `"http"`. If omitted, non-empty `baseUrl` implies `http`.
`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: path to PowerMem `.env` (default when using plugin defaults: `~/.openclaw/powermem/powermem.env`).
`pmemPath`	No	CLI: 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 session ends, this round’s user/assistant text is sent to PowerMem (infer: true) for extraction and storage. At most 3 items per round, each up to about 6000 characters.

Agent tools

Exposed to OpenClaw agents:

memory_recall — Search long-term memories by query.
memory_store — Store one memory (optional intelligent extraction on write).
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 service health.
openclaw ltm add "<text>" — Manually store one memory.

Troubleshooting

1. openclaw ltm health fails or cannot connect

CLI: pmem on PATH or correct pmemPath; valid .env at envFile.
HTTP: PowerMem is running (HTTP server in a terminal, or Docker); baseUrl is correct (e.g. http://localhost:8000; watch for 127.0.0.1 vs localhost mismatches).
Remote server: use the 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 previous user message if the prompt is very short). If the agent still replies without querying memory, try saying explicitly once “check memory for …” to confirm the pipeline; ensure the Web session 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/memory-powermem
pnpm install
pnpm lint   # type-check
pnpm test   # run tests (if any)

License

Apache License 2.0. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github/workflows		.github/workflows
docs/images		docs/images
skills		skills
test		test
.gitignore		.gitignore
.npmrc		.npmrc
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
client-cli.ts		client-cli.ts
client.ts		client.ts
config.ts		config.ts
index.ts		index.ts
install.sh		install.sh
openclaw-plugin-sdk.d.ts		openclaw-plugin-sdk.d.ts
openclaw-powermem-env.ts		openclaw-powermem-env.ts
openclaw.plugin.json		openclaw.plugin.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

OpenClaw Memory (PowerMem) Plugin

Prerequisites

Step 1: Install and start PowerMem

Option A: CLI + SQLite (recommended for individuals)

Option B: Install with pip (run HTTP server locally)

Option C: Run with Docker (no Python needed)

Install options

Step 2: Install the plugin into OpenClaw

Step 3: Configure OpenClaw (optional)

Step 4: Verify plugin and PowerMem connection

OpenClaw plugin commands (reference)

Config options (optional)

Agent tools

OpenClaw CLI (when plugin enabled)

Troubleshooting

Development

License

About

Uh oh!

Releases 5

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

OpenClaw Memory (PowerMem) Plugin

Prerequisites

Step 1: Install and start PowerMem

Option A: CLI + SQLite (recommended for individuals)

Option B: Install with pip (run HTTP server locally)

Option C: Run with Docker (no Python needed)

Install options

Step 2: Install the plugin into OpenClaw

Step 3: Configure OpenClaw (optional)

Step 4: Verify plugin and PowerMem connection

OpenClaw plugin commands (reference)

Config options (optional)

Agent tools

OpenClaw CLI (when plugin enabled)

Troubleshooting

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages