From c257a56303f31e697663826e36450ce49153e378 Mon Sep 17 00:00:00 2001 From: Teingi Date: Tue, 24 Mar 2026 10:17:32 +0800 Subject: [PATCH 1/2] docs(skills): rename minimal skill, decouple from full guide, require Python 3.10+ - Replace powermem-memory-quickstart with install-powermem-memory-minimal (aligned with install-powermem-memory). - Treat both skills as independently publishable; remove cross-references in SKILL bodies; minimal troubleshooting links to repo docs only. - Add mandatory Python 3.10+ checks before venv/pip in both skills. - Update INSTALL.md, README.md, and README_CN.md paths and copy. Made-with: Cursor --- INSTALL.md | 18 +++++----- README.md | 4 +-- README_CN.md | 4 +-- .../SKILL.md | 33 ++++++++++++++----- skills/install-powermem-memory/SKILL.md | 29 +++++++++------- 5 files changed, 55 insertions(+), 33 deletions(-) rename skills/{powermem-memory-quickstart => install-powermem-memory-minimal}/SKILL.md (51%) diff --git a/INSTALL.md b/INSTALL.md index 2ebf344..f08cdfd 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -43,23 +43,25 @@ The script will: 1) resolve OpenClaw workdir, 2) ask mode (**cli** / http) and p ## Quick Start (Let OpenClaw Install It) -Copy a **skill** into OpenClaw’s skills directory, then ask OpenClaw to follow it. +Copy **one** skill you want into OpenClaw’s skills directory, then ask OpenClaw to follow it. The two skills below are **independent** (each is complete for its scope; neither references the other). -### Easiest (C端 / personal users) +### OpenClaw skill — minimal install (`install-powermem-memory-minimal`) -Use the **minimal** skill—short steps, no `powermem.env` required: +Short steps, no `powermem.env` required. **Linux / macOS:** ```bash -mkdir -p ~/.openclaw/skills/powermem-memory-quickstart -cp /path/to/memory-powermem/skills/powermem-memory-quickstart/SKILL.md \ - ~/.openclaw/skills/powermem-memory-quickstart/ +mkdir -p ~/.openclaw/skills/install-powermem-memory-minimal +cp /path/to/memory-powermem/skills/install-powermem-memory-minimal/SKILL.md \ + ~/.openclaw/skills/install-powermem-memory-minimal/ ``` -Then say e.g. **「PowerMem 快速安装」** or **“PowerMem quickstart”**. +Then say e.g. **「PowerMem 快速安装」** / **“PowerMem quickstart”** or **「memory-powermem 最小安装」** / **“Minimal install memory-powermem”** / **“Install powermem memory minimal”**. -### Full install guide (more options & troubleshooting) +### OpenClaw skill — full guide (`install-powermem-memory`) + +Install, configuration options, tools, and troubleshooting (includes bundled reference docs in the skill folder). **Linux / macOS:** diff --git a/README.md b/README.md index c6039c2..a9e90a3 100644 --- a/README.md +++ b/README.md @@ -158,8 +158,8 @@ JSON response means the server is up. API docs: `http://localhost:8000/docs`. ## Install options - **One-click (Linux/macOS):** See [INSTALL.md](INSTALL.md) for `install.sh` (curl or run from repo root). -- **Let OpenClaw install it (simplest):** Copy [skills/powermem-memory-quickstart/SKILL.md](skills/powermem-memory-quickstart/SKILL.md) to `~/.openclaw/skills/powermem-memory-quickstart/`, then say **「PowerMem 快速安装」** or **“PowerMem quickstart”**. -- **Full documentation (troubleshooting and advanced topics):** [skills/install-powermem-memory/SKILL.md](skills/install-powermem-memory/SKILL.md) → **「安装 PowerMem 记忆」** / **“Install PowerMem memory”**. +- **OpenClaw skill (minimal install):** Copy [skills/install-powermem-memory-minimal/SKILL.md](skills/install-powermem-memory-minimal/SKILL.md) to `~/.openclaw/skills/install-powermem-memory-minimal/`, then say **「PowerMem 快速安装」** / **“PowerMem quickstart”** or **“Minimal install memory-powermem”** / **“Install powermem memory minimal”**. +- **OpenClaw skill (full guide):** Copy [skills/install-powermem-memory/SKILL.md](skills/install-powermem-memory/SKILL.md) (and its sibling `.md` files in that folder if you mirror the repo) to `~/.openclaw/skills/install-powermem-memory/`, then say **「安装 PowerMem 记忆」** / **“Install PowerMem memory”**. The minimal and full skills are **independent**; use whichever fits your workflow. - **Manual:** Steps below. --- diff --git a/README_CN.md b/README_CN.md index 32c8c80..0bb1203 100644 --- a/README_CN.md +++ b/README_CN.md @@ -159,8 +159,8 @@ curl -s http://localhost:8000/api/v1/system/health ## 安装方式 - **一键安装（Linux/macOS）：** 见 [INSTALL.md](INSTALL.md)，使用 `install.sh`（curl 或从仓库根目录执行）。 -- **交给 OpenClaw 安装（最省事）：** 将 [skills/powermem-memory-quickstart/SKILL.md](skills/powermem-memory-quickstart/SKILL.md) 复制到 `~/.openclaw/skills/powermem-memory-quickstart/`，然后说「**PowerMem 快速安装**」。 -- **完整说明（排错与进阶）：** [skills/install-powermem-memory/SKILL.md](skills/install-powermem-memory/SKILL.md) →「**安装 PowerMem 记忆**」。 +- **OpenClaw skill（最小安装）：** 将 [skills/install-powermem-memory-minimal/SKILL.md](skills/install-powermem-memory-minimal/SKILL.md) 复制到 `~/.openclaw/skills/install-powermem-memory-minimal/`，然后说「**PowerMem 快速安装**」或「**memory-powermem 最小安装**」或 **“Install powermem memory minimal”**。 +- **OpenClaw skill（完整指南）：** 将 [skills/install-powermem-memory/SKILL.md](skills/install-powermem-memory/SKILL.md)（若从仓库拷贝，建议连同该目录下其余 `.md` 一并放入 skill 目录）复制到 `~/.openclaw/skills/install-powermem-memory/`，然后说「**安装 PowerMem 记忆**」。最小安装与完整指南两个 skill **彼此独立**，按需选用其一即可。 - **手动安装：** 按下面步骤操作。 --- diff --git a/skills/powermem-memory-quickstart/SKILL.md b/skills/install-powermem-memory-minimal/SKILL.md similarity index 51% rename from skills/powermem-memory-quickstart/SKILL.md rename to skills/install-powermem-memory-minimal/SKILL.md index 9d1ab7d..7478cae 100644 --- a/skills/powermem-memory-quickstart/SKILL.md +++ b/skills/install-powermem-memory-minimal/SKILL.md @@ -1,20 +1,23 @@ --- -name: powermem-memory-quickstart -description: 最简单的 OpenClaw 长期记忆（PowerMem）安装步骤，面向个人用户；无需单独配置 powermem.env，复用 OpenClaw 里已配好的对话模型。 +name: install-powermem-memory-minimal +description: memory-powermem 最小安装步骤（OpenClaw + PowerMem 长期记忆），面向个人用户；无需单独配置 powermem.env，复用 OpenClaw 里已配好的对话模型。本 skill 可独立分发，不依赖其他安装类 skill。 triggers: - "PowerMem 快速安装" - "PowerMem 最简单安装" + - "memory-powermem 最小安装" - "怎么装 PowerMem 记忆" - "OpenClaw 记忆 怎么装" - "安装长期记忆" - "Quick install PowerMem" - "PowerMem quickstart" - "Easiest PowerMem setup" + - "Minimal install memory-powermem" + - "Install powermem memory minimal" --- # PowerMem 记忆 · 极简安装（个人用户） -你只要记住三件事：**OpenClaw 能正常聊天**、**本机装好 PowerMem**、**装上插件**。不用手写 `powermem.env`，记忆用的模型和 Key 会跟你在 OpenClaw 里配的一样。 +你只要记住几件事：**OpenClaw 能正常聊天**、**Python 先确认 ≥ 3.10**、**本机装好 PowerMem**、**装上插件**。不用手写 `powermem.env`，记忆用的模型和 Key 会跟你在 OpenClaw 里配的一样。 --- @@ -23,7 +26,18 @@ triggers: 1. **确认 OpenClaw 已经能用** 终端执行 `openclaw --version`，并且你已经在 OpenClaw 里配好了**平时对话用的模型**（能正常回复即可）。 -2. **安装 PowerMem（Python）** +2. **先检查 Python 版本（必须 ≥ 3.10）** + 在创建虚拟环境或执行 `pip install` **之前**必须先确认版本，否则后续容易装失败或运行异常： + ```bash + python3 --version + ``` + 输出应为 **Python 3.10.x、3.11.x、3.12.x** 等（次版本号 ≥ 10）。也可用下面命令做一次硬性校验（不通过会报错退出）： + ```bash + python3 -c "import sys; assert sys.version_info >= (3, 10), '需要 Python 3.10 或更高'; print(sys.version.split()[0], 'OK')" + ``` + 若版本不够：先升级本机 Python，或安装并使用 `python3.11` / `python3.12` 等满足要求的解释器，并将下面步骤里的 **`python3`** 换成实际命令（例如 `python3.12 -m venv ...`）。 + +3. **安装 PowerMem（Python）** 建议用虚拟环境，然后安装： ```bash python3 -m venv ~/.openclaw/powermem/.venv @@ -32,19 +46,19 @@ triggers: ``` 装好后执行 `pmem --version`，能输出版本就行。 -3. **让网关能找到 `pmem`** +4. **让网关能找到 `pmem`** 如果你启动 `openclaw gateway` 的终端**没有**激活上面的 venv，有两种简单办法二选一： - 每次开网关前先 `source ~/.openclaw/powermem/.venv/bin/activate`；或 - 在插件配置里把 **`pmemPath`** 写成 venv 里 `pmem` 的**完整路径**（装完后可用 `which pmem` 查看）。 -4. **一键装插件（推荐）** +5. **一键装插件（推荐）** 在 **Mac / Linux** 上执行（需已安装 OpenClaw）： ```bash curl -fsSL https://raw.githubusercontent.com/ob-labs/memory-powermem/main/install.sh | bash -s -y ``` 脚本会把插件放进 OpenClaw，并打开「用 OpenClaw 的模型驱动记忆」等默认选项。 -5. **重启网关并检查** +6. **重启网关并检查** ```bash openclaw gateway ``` @@ -64,10 +78,11 @@ triggers: | 情况 | 怎么办 | |------|--------| -| `pip install powermem` 报错 | 确认 Python ≥ 3.10；换干净 venv 再试。 | +| `python3 --version` 低于 3.10 | **先升级或换用** `python3.11` / `python3.12` 等，再重做「检查 Python」与 venv 步骤；不要跳过版本检查强行 `pip install`。 | +| `pip install powermem` 报错 | 再次确认 Python ≥ 3.10；换干净 venv 再试。 | | `pmem` 找不到 | 激活 venv，或配置 **`pmemPath`** 为绝对路径。 | | `ltm health` 不健康 | 确认 OpenClaw 里**默认模型**和 API Key 本身能聊天；升级 OpenClaw 到较新版本后再试。 | -| 想要更多选项（多实例、自建服务器等） | 看仓库里 **`skills/install-powermem-memory/SKILL.md`** 或根目录 **INSTALL.md**。 | +| 想要更多选项（多实例、HTTP、自建服务器等） | 查阅 **[memory-powermem](https://github.com/ob-labs/memory-powermem)** 仓库根目录的 **INSTALL.md** 与 **README**。 | --- diff --git a/skills/install-powermem-memory/SKILL.md b/skills/install-powermem-memory/SKILL.md index 1107020..6f0c782 100644 --- a/skills/install-powermem-memory/SKILL.md +++ b/skills/install-powermem-memory/SKILL.md @@ -1,6 +1,6 @@ --- name: install-powermem-memory -description: Step-by-step guide to install and configure the PowerMem long-term memory plugin. After setup, the plugin auto-captures conversation highlights and auto-recalls relevant memories. +description: Step-by-step guide to install and configure the PowerMem long-term memory plugin (full path, options, troubleshooting). After setup, the plugin auto-captures conversation highlights and auto-recalls relevant memories. This skill is self-contained and can be published independently of any minimal-install skill. triggers: - "安装 PowerMem 记忆" - "安装 PowerMem 记忆插件" @@ -20,8 +20,6 @@ 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. -**只想最少步骤的个人用户** → 用隔壁文件夹 **`skills/powermem-memory-quickstart/SKILL.md`**（更短、不写 `powermem.env`）。 - ## How It Works - **Auto-Capture**: After a conversation, the plugin sends valuable user/assistant text to PowerMem (optional infer / intelligent extraction). @@ -29,7 +27,7 @@ This skill folder includes supplementary docs: ## When User Asks to Install -**Recommended order (TO C):** (1) OpenClaw installed and **default model + provider auth** configured. (2) `pip install powermem` and `pmem` available to the gateway (PATH or `pmemPath`). (3) Install the **memory-powermem** plugin. **No `powermem.env` is required** for the default path. +**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. @@ -37,8 +35,14 @@ The curl **`install.sh`** deploys the plugin and OpenClaw entries; with **`-y`** `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. **Install PowerMem (CLI — default)** - - Python **3.10+**: `python3 --version`. +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: + ```bash + 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 `/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`). @@ -46,14 +50,14 @@ The curl **`install.sh`** deploys the plugin and OpenClaw entries; with **`-y`** - **`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`. -3. **HTTP path (enterprise / shared server)** - - `pip install powermem`, `.env` in server working directory, `powermem-server --host 0.0.0.0 --port 8000`. +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`. -4. **Install the plugin** +5. **Install the plugin** `openclaw plugins install /path/to/memory-powermem`, or **`install.sh`** from [INSTALL.md](https://github.com/ob-labs/memory-powermem/blob/main/INSTALL.md). -5. **Configure OpenClaw** +6. **Configure OpenClaw** **CLI — minimal (recommended, matches plugin defaults):** Do **not** set `envFile` unless you need a file. Example: @@ -86,7 +90,7 @@ The curl **`install.sh`** deploys the plugin and OpenClaw entries; with **`-y`** Optional: `apiKey` if the server uses auth. -6. **Verify** +7. **Verify** Restart **gateway**, then: ```bash @@ -136,7 +140,8 @@ Restart the gateway after slot or plugin config changes. | Symptom | Fix | |---------|-----| -| **`pip install powermem` fails** | Python 3.10+, clean venv. See [PowerMem issues](https://github.com/oceanbase/powermem/issues). | +| **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](https://github.com/oceanbase/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](https://github.com/oceanbase/powermem/blob/master/.env.example). | From 910918637e0a677d6d5d1ff44e01d150059a8821 Mon Sep 17 00:00:00 2001 From: Teingi Date: Tue, 24 Mar 2026 10:20:25 +0800 Subject: [PATCH 2/2] docs(skills): require memory-powermem loaded in plugins list before LTM checks - Verify step: run openclaw plugins list and confirm memory-powermem status is loaded. - Add troubleshooting for missing plugin or non-loaded state (minimal + full skills). Made-with: Cursor --- skills/install-powermem-memory-minimal/SKILL.md | 8 +++++++- skills/install-powermem-memory/SKILL.md | 10 ++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/skills/install-powermem-memory-minimal/SKILL.md b/skills/install-powermem-memory-minimal/SKILL.md index 7478cae..15e4959 100644 --- a/skills/install-powermem-memory-minimal/SKILL.md +++ b/skills/install-powermem-memory-minimal/SKILL.md @@ -62,7 +62,12 @@ triggers: ```bash openclaw gateway ``` - 另开终端： + 另开终端，**先**确认插件已被网关加载： + ```bash + openclaw plugins list + ``` + 输出里要有 **memory-powermem**，且其状态为 **loaded**（已加载）。若只有安装记录、状态不是 loaded，先按下面「若某一步失败」处理，**不要**跳过这步直接去测 `ltm`。 + 通过后再检查记忆健康并试写读： ```bash openclaw ltm health ``` @@ -81,6 +86,7 @@ triggers: | `python3 --version` 低于 3.10 | **先升级或换用** `python3.11` / `python3.12` 等，再重做「检查 Python」与 venv 步骤；不要跳过版本检查强行 `pip install`。 | | `pip install powermem` 报错 | 再次确认 Python ≥ 3.10；换干净 venv 再试。 | | `pmem` 找不到 | 激活 venv，或配置 **`pmemPath`** 为绝对路径。 | +| `plugins list` 没有 **memory-powermem**，或状态不是 **loaded** | 确认已执行安装脚本或 `openclaw plugins install`；`plugins.enabled` 为 true、`plugins.slots.memory` 为 **memory-powermem**；改完后**重启 gateway**，再执行 `openclaw plugins list` 复查。 | | `ltm health` 不健康 | 确认 OpenClaw 里**默认模型**和 API Key 本身能聊天；升级 OpenClaw 到较新版本后再试。 | | 想要更多选项（多实例、HTTP、自建服务器等） | 查阅 **[memory-powermem](https://github.com/ob-labs/memory-powermem)** 仓库根目录的 **INSTALL.md** 与 **README**。 | diff --git a/skills/install-powermem-memory/SKILL.md b/skills/install-powermem-memory/SKILL.md index 6f0c782..0ad59a9 100644 --- a/skills/install-powermem-memory/SKILL.md +++ b/skills/install-powermem-memory/SKILL.md @@ -91,7 +91,13 @@ The curl **`install.sh`** deploys the plugin and OpenClaw entries; with **`-y`** Optional: `apiKey` if the server uses auth. 7. **Verify** - Restart **gateway**, then: + Restart **gateway**, then in another terminal: + + ```bash + 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. ```bash openclaw ltm health @@ -147,4 +153,4 @@ Restart the gateway after slot or plugin config changes. | **Health OK but add/search errors** | Embedding/LLM mismatch for your provider—see gateway logs; try optional **PowerMem `.env`** from [.env.example](https://github.com/oceanbase/powermem/blob/master/.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. | -| **Plugin not loaded** | `plugins.slots.memory` = `memory-powermem`; restart gateway. | +| **`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**. |