为AI智能体构建长效记忆系统：PowerMem与OpenClaw集成实战

1. 项目概述：为AI智能体构建长效记忆系统

在AI智能体（Agent）的开发与应用中，一个核心的挑战是如何让它们像人类一样，拥有持续、稳定且可检索的长期记忆。想象一下，你每天都会遇到一位新来的同事，每次见面你都需要重新自我介绍，他也会忘记你的喜好和之前讨论过的项目细节——这就是没有长期记忆的AI智能体的工作状态。它们每次对话都像是一次“重启”，无法积累经验，也无法提供真正个性化、连贯的服务。

ob-labs/memory-powermem这个项目，正是为了解决这个问题而生。它是一个为 OpenClaw 智能体平台设计的记忆插件，其核心是将 OceanBase 开源的PowerMem记忆引擎与 OpenClaw 无缝集成。简单来说，它给 OpenClaw 智能体装上了一颗“海马体”，让智能体不仅能记住单次对话的上下文（短期记忆），更能将重要的信息、用户偏好、操作经验结构化地存入一个外部数据库，并在未来的互动中智能地回忆起来。

这个组合的价值在于“增效”与“降本”。对于开发者或终端用户而言，它意味着：

• 体验提升：你的AI助手会记得你“喜欢喝美式咖啡”、“上周讨论过某个项目的技术架构”，并在合适的时机主动提及或应用这些知识，交互变得自然且有连续性。
• 成本优化：通过智能提取（Intelligent Extraction）和艾宾浩斯遗忘曲线（Ebbinghaus Forgetting Curve）管理，系统只存储和回忆高价值信息，避免了将大量冗余对话历史全部塞给大语言模型（LLM）所带来的高昂令牌（Token）消耗。这就是其口号“maximum token savings for AI agents”的由来。
• 灵活部署：它支持多种模式，从个人开发者本地运行的轻量CLI模式，到团队共享的HTTP服务模式，再到容器化的Docker部署，适应不同场景的需求。

无论你是在构建一个个人效率助手，还是一个需要服务多用户、多场景的企业级智能体应用，为智能体添加一个可靠的长效记忆系统，都是从“玩具”走向“工具”的关键一步。接下来，我将为你详细拆解如何部署、配置并深度使用这套系统。

2. 核心架构与设计思路解析

在深入动手之前，理解memory-powermem插件与 PowerMem 引擎是如何协同工作的，能帮助你在后续配置和排查问题时事半功倍。这套架构的核心思想是“插件桥接，引擎服务”。

2.1 双核驱动：OpenClaw 插件与 PowerMem 引擎

整个系统可以清晰地分为两层：

1. OpenClaw 插件层 (memory-powermem)：这是一个标准的 OpenClaw 插件，扮演着“适配器”和“控制器”的角色。它的主要职责是：

   • 协议转换：将 OpenClaw 内部关于记忆操作的调用（如“存储”、“回忆”），转换为 PowerMem 引擎能理解的指令。
   • 生命周期管理：根据配置，在智能体会话开始前自动注入相关记忆（autoRecall），在会话结束后自动捕获对话要点并存储（autoCapture）。
   • 提供工具：向 OpenClaw 智能体暴露一系列工具函数（如memory_recall,memory_store），使智能体在推理过程中能主动进行记忆的读写操作。

2. 记忆引擎层 (PowerMem)：这是系统的“大脑”和“仓库”，一个独立运行的记忆服务。它负责所有重度的记忆处理逻辑：

   • 智能提取：当一段文本被送入存储时，PowerMem 可以调用 LLM 对其进行分析，提取出关键实体（如人物、地点、事件）、用户意图、偏好等结构化信息，而不仅仅是存储原始文本。这大大提升了后续检索的准确性和效率。
   • 向量检索：利用文本嵌入模型（Embedding Model）将记忆内容转换为高维向量，并存储在向量数据库中。当需要回忆时，通过计算查询文本与记忆向量之间的相似度，找到最相关的内容。
   • 记忆管理：应用艾宾浩斯遗忘曲线等算法，对记忆的重要性、新鲜度进行动态评分和管理，模拟人类的记忆衰减过程，让更相关、更重要的记忆更容易被想起。
   • 多租户隔离：通过userId和agentId等机制，逻辑上隔离不同用户、不同智能体的记忆空间，确保隐私和数据安全。

2.2 通信模式：CLI 与 HTTP 的选型考量

插件与引擎之间有两种通信模式，这是配置时需要做出的第一个关键选择：

• CLI 模式（默认，推荐个人使用）：

  • 工作原理：插件直接在本地系统进程内调用 PowerMem 的命令行接口pmem。这类似于你在终端里直接运行命令。
  • 优点：
    • 零延迟：进程内调用，没有网络开销，速度最快。
    • 部署简单：无需额外启动和维护一个 HTTP 服务，开箱即用。
    • 资源独立：记忆数据库（默认 SQLite）和 OpenClaw 应用数据通常放在一起（如~/.openclaw/下），管理方便。
  • 缺点：难以实现多进程或多机器间的记忆共享。适合单机、单用户的 OpenClaw 实例。

• HTTP 模式（推荐团队/生产环境）：

  • 工作原理：PowerMem 以一个独立的 HTTP 服务器（powermem-server）运行。插件通过发送 HTTP 请求（如POST /api/v1/memory）与之交互。
  • 优点：
    • 共享记忆：多个 OpenClaw 网关、甚至多个不同的应用，可以连接同一个 PowerMem 服务器，共享和交换记忆。这是实现“团队知识库”或“跨智能体协作”的基础。
    • 高可用与扩展：可以像部署任何 Web 服务一样，对 PowerMem 服务器进行负载均衡、监控和扩缩容。
    • 语言无关：任何能发送 HTTP 请求的客户端都可以使用记忆服务，不局限于 OpenClaw。
  • 缺点：需要额外维护一个服务，引入了网络依赖和潜在的故障点。

选择建议：如果你是个人开发者，正在本地调试一个智能体，CLI 模式是最简单直接的选择。如果你在部署一个需要服务多个用户、或者由多个智能体协作的系统，那么从一开始就搭建 HTTP 服务是更明智的。

2.3 记忆的智能生命周期：存储、回忆与遗忘

理解了架构和模式后，我们来看看记忆是如何被智能处理的。这不仅仅是“存”和“取”，而是一个完整的生命周期：

1. 捕获与提取：当autoCapture开启时，一次智能体会话结束后，最近的几轮对话会被送入 PowerMem。这里的关键是inferOnAdd选项。如果开启，PowerMem 会调用 LLM 对这段对话进行“消化”，提取出核心事实、用户状态变化、达成的结论等，生成一条结构化的“记忆摘要”，而非存储聊天记录原文。这步操作虽然消耗一次 LLM API 调用，但极大地提升了记忆质量。
2. 向量化与存储：提取出的文本（或原始文本）通过嵌入模型转化为向量，然后与元数据（如时间戳、来源会话、userId、agentId）一并存入数据库。PowerMem 支持 OceanBase、PostgreSQL（带向量扩展）等作为后端。
3. 回忆与评分：当autoRecall开启，在新会话开始时，系统会将用户的第一条消息（或上一条消息）作为查询，在向量数据库中进行相似度搜索。同时，系统会结合艾宾浩斯曲线等因素，对记忆的“活性”进行评分，让近期频繁使用的、重要的记忆排名更靠前。
4. 经验升华：autoExperience是一个高级功能。对于某些任务型的对话，PowerMem 可以尝试让 LLM 总结出“操作指南”或“经验教训”，并将其作为一条特殊的“经验”记忆存储。此后，当智能体遇到类似任务时，可以通过experienceRecall直接获取这份“攻略”，实现能力的快速复用。

这个设计精妙之处在于，它把昂贵的 LLM 推理用在了刀刃上（提取和升华），而日常的回忆则依靠高效的向量检索完成，从而在保证智能的同时，实现了“maximum token savings”。

3. 实战部署：从零开始搭建记忆系统

理论清晰后，我们进入实战环节。我将以最常见的个人开发场景为例，带你完整走通CLI 模式的安装与配置流程。即便你选择 HTTP 模式，前期的基础准备也是相通的。

3.1 基础环境准备与检查

在开始安装任何新组件前，做好准备工作能避免很多后续的“坑”。

• 确认 OpenClaw 安装：这是前提。确保你的 OpenClaw 命令行工具和网关服务可以正常运行。打开终端，执行openclaw --version和openclaw gateway status（或启动网关），确保一切就绪。
• Python 环境：PowerMem 引擎是 Python 编写的。虽然 CLI 模式的“捆绑”安装可能不需要你手动安装 Python，但为了灵活性和问题排查，建议确保系统中有 Python 3.11+ 版本。在终端输入python3 --version或python --version进行确认。
• 网络通畅：安装过程中需要从 PyPI 下载powermem包，从 npm 下载插件。请确保你的网络环境能够访问这些仓库。

注意：如果你在 macOS 上使用 Homebrew 安装了 OpenClaw，它可能自带了 Python 环境。但如果你计划未来使用 HTTP 模式或进行深度定制，一个独立的 Python 虚拟环境（venv）是最佳实践，它可以避免包依赖冲突。

3.2 安装 PowerMem 记忆引擎

这是核心步骤。我们采用项目推荐的Option A: CLI + SQLite方式，这也是对 OpenClaw 个人用户最友好的方案。

步骤 1：创建并激活虚拟环境我强烈建议为 PowerMem 创建独立的虚拟环境，即使使用 CLI 模式。这能保证其依赖库不会影响系统或其他项目。

# 在用户目录下为 OpenClaw 相关组件创建一个统一的配置目录 mkdir -p ~/.openclaw/powermem cd ~/.openclaw/powermem # 创建 Python 虚拟环境，环境目录命名为 .venv python3 -m venv .venv # 激活虚拟环境 # 在 macOS/Linux 上： source .venv/bin/activate # 激活后，你的命令行提示符前通常会显示 `(.venv)`。 # 在 Windows 的 PowerShell 上： # .venv\Scripts\Activate.ps1

激活后，后续所有pip命令安装的包都将仅限于这个虚拟环境内。

步骤 2：安装 PowerMem 包在激活的虚拟环境中，运行安装命令：

pip install powermem

安装完成后，可以验证一下pmem命令行工具是否可用：

pmem --version

如果显示出版本号（例如powermem 0.1.0），说明引擎安装成功。

步骤 3：配置环境变量（关键步骤）PowerMem 需要知道三件事：用什么数据库存、用什么 LLM 做智能提取、用什么模型做向量化。这些通过环境变量配置。插件提供了便捷的安装脚本。

# 回到你的项目目录，或者任意你喜欢的位置，获取安装脚本并运行 # 方式一：直接通过 curl 运行（推荐，最方便） curl -fsSL https://raw.githubusercontent.com/ob-labs/memory-powermem/main/install.sh | bash # 方式二：如果你已经克隆了 memory-powermem 仓库 # cd /path/to/memory-powermem # bash install.sh

这个脚本会做两件事：

1. 在~/.openclaw/powermem/目录下创建一个powermem.env文件的模板。
2. 引导你进行一些基础配置。

步骤 4：编辑配置文件现在，用文本编辑器打开~/.openclaw/powermem/powermem.env文件。你会看到一个包含很多选项的模板。对于 CLI 模式且希望与 OpenClaw 共享配置的个人用户，我们只需要关注最简配置：

# ~/.openclaw/powermem/powermem.env # 1. 数据库配置 - 使用 SQLite，最简单，无需安装其他数据库服务 DATABASE_PROVIDER=sqlite SQLITE_DATABASE=/home/your_username/.openclaw/powermem/memories.db # 指定一个具体的路径 # 2. LLM 配置 - 这里我们选择“继承”OpenClaw的配置，这是插件的一个便利功能 # 将 LLM_PROVIDER 设置为 ‘openclaw’，插件会自动使用 OpenClaw 网关中配置的默认模型。 LLM_PROVIDER=openclaw # LLM_API_KEY 和 LLM_MODEL 无需在此设置，它们将从 OpenClaw 获取。 # 3. 嵌入模型配置 - 同样继承 OpenClaw 的配置 EMBEDDING_PROVIDER=openclaw # EMBEDDING_API_KEY 和 EMBEDDING_MODEL 也无需在此设置。 # 时区设置 TIMEZONE=Asia/Shanghai

关键解释：

• DATABASE_PROVIDER=sqlite：SQLite 是一个文件数据库，无需启动服务，数据库文件就是上面的.db文件。这对于个人开发完全足够。
• LLM_PROVIDER=openclaw和EMBEDDING_PROVIDER=openclaw：这是本方案的精髓。你不需要在 PowerMem 的配置里重复填写昂贵的 API Key。插件在运行时，会将 OpenClaw 网关配置中agents.defaults.model指定的模型及其 API 密钥“注入”给 PowerMem 使用。这意味着你只需要在 OpenClaw 中配置一次模型，记忆引擎和对话智能体共享同一套配置。

重要提示：请将SQLITE_DATABASE的路径中的your_username替换为你自己系统的用户名。你可以使用pwd命令查看当前绝对路径。

3.3 安装并配置 OpenClaw 记忆插件

引擎就绪，现在来安装连接器。

步骤 1：安装插件打开一个新的终端窗口（注意：这里不需要激活之前的 Python 虚拟环境，因为这是 Node.js/npm 操作），使用 OpenClaw 命令行工具安装插件：

# 从 npm 官方仓库安装（最推荐的方式） openclaw plugins install memory-powermem

安装过程会自动从 npm 下载插件包，并将其注册到你的 OpenClaw 系统中。安装成功后，可以通过以下命令查看已安装的插件列表：

openclaw plugins list

你应该能在列表中看到memory-powermem，并且其enabled状态为true。

步骤 2：理解默认配置安装完成后，插件已经可以工作了！因为它有一套合理的默认配置：

• mode: "cli"：使用 CLI 模式。
• pmemPath: "bundled"：使用插件自带的 npm 版powermemCLI 工具（这是一个独立版本，无需你之前安装的 Python 包）。
• useOpenClawModel: true：自动从 OpenClaw 注入模型配置（这正是我们在.env文件中设置openclaw提供商的原因）。
• envFile: "~/.openclaw/powermem/powermem.env"：自动寻找我们刚才创建的配置文件。
• autoCapture和autoRecall均为true：开启自动记忆捕获和回忆。

这意味着，如果你完全按照上述步骤操作，现在重启 OpenClaw 网关后，你的智能体就已经具备了长期记忆能力，无需任何额外配置。

步骤 3：（可选）自定义配置如果你想修改默认行为，需要编辑 OpenClaw 的主配置文件。该文件通常位于~/.openclaw/openclaw.json。

{ "plugins": { "slots": { "memory": "memory-powermem" // 确保 memory 插槽指向我们安装的插件 }, "entries": { "memory-powermem": { "enabled": true, "config": { "mode": "cli", // “bundled” 使用插件自带的npm版本。“auto”会从系统PATH查找pmem命令。 // 如果你想使用我们之前在虚拟环境中安装的 Python 版 pmem，可以指定绝对路径。 // "pmemPath": "/Users/your_username/.openclaw/powermem/.venv/bin/pmem", "pmemPath": "bundled", // 指定我们创建的环境变量文件路径 "envFile": "/home/your_username/.openclaw/powermem/powermem.env", "autoCapture": true, "autoRecall": true, "inferOnAdd": true // 存储时进行智能提取，推荐开启 } } } } }

修改配置文件后，必须重启 OpenClaw 网关才能使更改生效。

3.4 验证与初步测试

配置完成后，让我们进行端到端的验证，确保每个环节都畅通无阻。

步骤 1：检查服务健康状态在终端中，使用 OpenClaw 插件提供的长时记忆管理命令：

openclaw ltm health

如果一切正常，你会看到类似{“status”: “healthy”, “mode”: “cli”}的 JSON 输出。如果失败，通常会显示连接错误或配置错误，请根据错误信息回溯检查上述步骤。

步骤 2：手动测试记忆存储与检索让我们模拟智能体的操作，手动添加和搜索一条记忆：

# 添加一条记忆 openclaw ltm add "我的项目负责人叫张三，他每周三下午有团队周会" # 搜索相关记忆 openclaw ltm search "张三的会议安排"

如果搜索命令返回了你刚刚添加的那条记忆（或相似度很高的内容），恭喜你！这证明从插件调用，到 PowerMem 引擎处理（向量化、存储），再到检索的整个链路已经完全打通。

步骤 3：在智能体对话中观察启动你的 OpenClaw 网关，并开始与一个智能体对话。

1. 首先，告诉它一些信息，例如：“记住，我最喜欢的编程语言是 Python。”
2. 结束当前对话（或等待其自动结束，取决于你的会话设置）。
3. 开启一个新的对话会话。注意，这是测试长期记忆的关键，因为新会话的上下文是空的。
4. 在新会话中提问：“我之前最喜欢用什么编程语言？” 观察智能体的回复。如果autoRecall工作正常，智能体在回答前，其系统提示中会被注入相关的记忆，它应该能回答出“Python”。你可以在 OpenClaw 的调试界面或日志中，查看智能体是否调用了memory_recall工具。

至此，一个具备长效记忆能力的个人 AI 智能体开发环境已经搭建完成。你可以开始基于此，开发能记住用户习惯、项目上下文和个人偏好的复杂智能体应用了。

4. 高级配置与生产环境部署

在个人环境跑通后，如果你需要将这套系统用于团队协作或生产环境，那么 HTTP 模式和一些高级功能就是必须掌握的。这部分我们将深入探讨如何搭建一个共享的、稳健的记忆服务。

4.1 HTTP 模式部署详解

HTTP 模式的核心是独立运行powermem-server。这里我以Docker 部署为例，因为它能提供最好的环境一致性和可移植性。

步骤 1：准备 Docker 环境与配置文件首先，确保你的服务器或开发机上安装了 Docker 和 Docker Compose。

# 1. 克隆 PowerMem 主仓库（不是 memory-powermem 插件仓库） git clone https://github.com/oceanbase/powermem.git cd powermem # 2. 复制环境变量模板 cp .env.example .env

现在，编辑.env文件。生产环境配置与个人开发有显著不同：

# ~/powermem/.env TIMEZONE=Asia/Shanghai # ---------- 数据库配置 ---------- # 生产环境强烈推荐使用 OceanBase 或 PostgreSQL（需 pgvector 扩展），而非 SQLite DATABASE_PROVIDER=oceanbase # 假设你已部署 OceanBase 数据库 OCEANBASE_HOST=your_ob_host OCEANBASE_PORT=2881 OCEANBASE_USER=root@sys OCEANBASE_PASSWORD=your_strong_password OCEANBASE_DATABASE=powermem OCEANBASE_COLLATION=utf8mb4_general_ci # ---------- LLM 配置 ---------- # 生产环境应使用自己的 API Key，不再依赖 OpenClaw 注入 LLM_PROVIDER=openai # 或 qwen, azure_openai 等 LLM_API_KEY=sk-your-openai-api-key LLM_MODEL=gpt-4o-mini # 根据实际情况选择模型 LLM_BASE_URL=https://api.openai.com/v1 # 如果是第三方代理，可修改 # ---------- 嵌入模型配置 ---------- EMBEDDING_PROVIDER=openai EMBEDDING_API_KEY=sk-your-openai-api-key # 可与 LLM 相同 EMBEDDING_MODEL=text-embedding-3-small EMBEDDING_DIMS=1536 # 必须与所选 embedding 模型的维度一致 # ---------- 服务器安全配置 ---------- # 启用 API 密钥认证，保护你的记忆服务 AUTH_ENABLED=true AUTH_API_KEYS=your_shared_secret_key_1,your_shared_secret_key_2

关键点：

• 数据库：OceanBase 是项目原生推荐，性能强大。如果选择 PostgreSQL，需确保安装了pgvector扩展，并将DATABASE_PROVIDER改为postgresql，并配置对应的POSTGRES_*参数。
• 认证：AUTH_ENABLED=true和AUTH_API_KEYS至关重要。这能防止未经授权的访问。多个密钥用逗号分隔，方便不同客户端使用。

步骤 2：使用 Docker Compose 启动服务PowerMem 仓库提供了编排好的docker-compose.yml文件。

# 在 powermem 项目根目录下执行 docker-compose -f docker/docker-compose.yml up -d

这个命令会启动两个容器：一个是 PowerMem 应用本身，另一个是 OceanBase 数据库（如果你在.env中配置了DATABASE_PROVIDER=oceanbase且使用了默认的 compose 文件）。-d参数表示后台运行。

步骤 3：验证服务服务启动后，进行健康检查：

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

更直观的方式是访问 API 文档页面：http://你的服务器IP:8000/docs。这是一个交互式的 Swagger UI，你可以在这里直接测试所有 API 端点。

4.2 OpenClaw 插件端 HTTP 模式配置

服务端跑起来后，需要在每个 OpenClaw 实例中修改插件配置，使其指向这个共享服务。 修改~/.openclaw/openclaw.json：

{ "plugins": { "slots": { "memory": "memory-powermem" }, "entries": { "memory-powermem": { "enabled": true, "config": { "mode": "http", "baseUrl": "http://your_server_ip:8000", // 替换为你的 PowerMem 服务器地址 "apiKey": "your_shared_secret_key_1", // 必须与服务器配置的 AUTH_API_KEYS 之一匹配 "httpApiVersion": "v2", // 推荐使用 v2，功能更丰富 "autoCapture": true, "autoRecall": true, "autoExperience": true, // 开启经验自动提取 "experienceRecall": true, // HTTP v2 特有功能：请求级配置，可覆盖默认数据库连接等 "requestConfig": { "memory_db": { "host": "your_ob_host", "port": 2881 } } } } } } }

配置完成后，同样需要重启 OpenClaw 网关。此时，所有连接到这个网关的智能体，都将使用远端的、共享的 PowerMem 记忆库。

4.3 多用户与多智能体隔离策略

在生产环境中，记忆隔离是硬性要求。PowerMem 通过userId和agentId两个维度来实现逻辑隔离。

• userId：代表最终用户。例如，不同登录你应用的用户，他们的记忆应该完全隔离。
• agentId：代表不同的智能体角色或任务。例如，一个“客服助手”和一个“编程导师”智能体，即使服务于同一个用户，它们的记忆也可能需要隔离。

在插件配置中，你可以手动指定，也可以使用"auto"让插件自动生成并持久化一个稳定ID。

"config": { // ... 其他配置 "userId": "user_123456", // 从你的用户系统获取 "agentId": "agent_customer_service", // 根据智能体类型设定 // 或者使用自动生成（存储在 ~/.openclaw/state/powermem/identity.json） // "userId": "auto", // "agentId": "auto" }

HTTP v2 的共享功能：这是团队协作的利器。假设agent_customer_service解决了一个复杂问题，并生成了宝贵的“经验”。通过agent_memory_share工具或 API，可以将这条经验共享给agent_technical_support。这样，技术支持智能体在遇到类似问题时，就能直接借鉴客服的经验，实现知识在团队智能体间的流动。

4.4 双写与本地缓存容灾策略

网络服务总有可能不稳定。dualWrite（双写）机制是一个提高可靠性的高级特性。当插件配置为 HTTP 模式时，可以开启此选项。

"config": { "mode": "http", "baseUrl": "http://your_server_ip:8000", "dualWrite": true, // 开启双写 "localDbPath": "/home/user/.openclaw/powermem/local_cache.db", // 本地 SQLite 路径 "localUserId": "auto", // 本地存储的命名空间，通常与 userId 一致 "localAgentId": "auto", "syncOnResume": true // 启动时同步未上传的记忆 }

工作原理：当智能体存储一条记忆时，插件会同时写入远程的 PowerMem HTTP 服务和本地的 SQLite 数据库。如果远程写入失败，记忆会先暂存在本地队列中。插件会在后台不断重试同步，直到成功。这确保了即使在网络闪断或服务器临时不可用的情况下，用户的记忆也不会丢失，并在恢复后能最终保持一致。

5. 常见问题排查与实战技巧

即使按照指南操作，在实际部署和开发中仍可能遇到各种问题。这里我总结了一份从实战中积累的排查清单和技巧。

5.1 安装与连接类问题

问题 1：openclaw ltm health命令失败，提示Command failed或连接错误。

• CLI 模式排查：

  • pmem命令未找到：运行which pmem或pmem --version。如果找不到，检查pmemPath配置。如果是bundled，确保插件安装正确。如果是自定义路径，确保该路径下的pmem可执行文件存在且有执行权限。
  • 环境变量文件错误：检查envFile指向的.env文件是否存在，语法是否正确（避免多余空格，确保是KEY=VALUE格式）。特别是检查LLM_PROVIDER=openclaw时，你的 OpenClaw 网关是否已正确配置了默认模型。
  • Python 依赖缺失：如果你使用自定义pmemPath指向一个 Python 虚拟环境，请确保该环境已激活，且已安装powermem包。可以手动在虚拟环境中运行pmem --version测试。

• HTTP 模式排查：

  • 服务未运行：在服务器上执行docker ps或ps aux | grep powermem-server，确认服务进程是否存在。
  • 网络不通：在 OpenClaw 所在机器上，使用curl http://server_ip:8000/api/v1/system/health测试连通性。检查防火墙是否放行了 8000 端口。
  • 认证失败：确认插件配置中的apiKey与服务器.env文件中AUTH_API_KEYS的某个值完全匹配（注意大小写和特殊字符）。
  • URL 错误：确保baseUrl是http://host:port格式，不要在后面添加/api/v1。

问题 2：记忆添加或搜索返回空结果或 500 错误。这通常是后端服务（PowerMem）内部错误。

• 查看服务日志：这是最直接的途径。
  • Docker:docker logs -f <powermem_container_id>
  • 直接运行: 去运行powermem-server的终端查看输出。
• 常见日志错误：
  • LLM API error/Embedding API error：LLM 或嵌入模型 API 密钥错误、额度不足、或网络超时。检查.env中的LLM_API_KEY,EMBEDDING_API_KEY及相关BASE_URL配置。
  • Database connection failed：数据库连接失败。检查数据库地址、端口、用户名密码，以及数据库实例是否已创建（例如，OceanBase 中需要先创建powermem数据库）。
• 测试 API：直接使用curl调用 PowerMem API，可以绕过插件，定位问题。

  # 添加记忆 curl -X POST http://localhost:8000/api/v1/memory \ -H “Content-Type: application/json” \ -H “X-API-Key: your_api_key” \ -d ‘{“text”: “test memory”, “userId”: “test”, “agentId”: “test”}’ # 搜索记忆 curl -X POST http://localhost:8000/api/v1/memory/search \ -H “Content-Type: application/json” \ -H “X-API-Key: your_api_key” \ -d ‘{“query”: “test”, “userId”: “test”, “agentId”: “test”}’

5.2 功能与行为类问题

问题 3：智能体似乎没有使用长期记忆，每次回答都像第一次聊天。

• 检查autoRecall配置：确保插件配置中“autoRecall”: true。如果为false，智能体不会在会话开始时自动注入记忆。
• 检查智能体工具列表：在 OpenClaw 的开发者工具或日志中，查看智能体的系统提示（System Prompt）是否包含了memory_recall等工具的描述。如果没有，可能是插件未正确加载或配置。
• 手动触发测试：在对话中，明确指示智能体：“请搜索一下我的记忆，看看我喜欢的编程语言是什么？” 如果它能正确调用工具并返回答案，说明记忆系统本身是通的，问题可能出在autoRecall的触发逻辑或智能体的初始提示词上。有些智能体模板可能覆盖了默认的工具调用指令。
• 禁用冲突的钩子：OpenClaw 有一个内置的session-memory钩子，它会将记忆写入工作区的 Markdown 文件。如果同时启用 PowerMem 和这个钩子，智能体可能会困惑。建议禁用内置钩子：openclaw hooks disable session-memory，然后重启网关。

问题 4：autoCapture好像没有生效，对话结束后没有生成记忆。

• 确认会话结束：autoCapture通常在智能体会话（Session）结束时触发。确保你的对话流程正确地结束了会话（例如，在 Web UI 中开始了新对话，或者调用了/new命令）。
• 检查记忆库：直接使用openclaw ltm search “”（空查询）或通过 PowerMem API 列出所有记忆，看看最近的对话是否被捕获。有时捕获了，但提取的内容（如果inferOnAdd开启）可能和你预期的关键词不同。
• 调整捕获量：autoCapture默认会捕获会话最后几轮对话。如果对话非常长，可能只捕获了末尾的一小部分。目前这是固定行为，对于超长对话，可能需要通过memory_store工具在对话中手动标记关键信息。

5.3 性能与优化技巧

• 向量模型选择：嵌入模型的速度和成本直接影响记忆检索性能。对于中文场景，text-embedding-3-small或text-embedding-v4是不错的选择。如果纯英文，text-embedding-3-small性价比很高。维度（EMBEDDING_DIMS）一定要与模型匹配，否则无法正确检索。
• 控制记忆数量与质量：不是所有对话都值得记忆。过度记忆会导致检索速度变慢和噪音增加。可以：
  • 在智能体逻辑中，有选择地调用memory_store，只存储明确重要的信息。
  • 利用inferOnAdd的智能提取功能，让 LLM 帮你提炼精华，而不是存储原始对话。
  • 定期通过memory_forget工具或管理 API 清理低价值、过时的记忆。
• 检索参数调优：memory_recall工具或 API 支持limit和scoreThreshold参数。
  • limit：控制返回的记忆条数，通常 3-5 条足够，避免提示词过长。
  • scoreThreshold：相似度分数阈值，低于此值的记忆将被过滤。可以避免注入不相关的记忆干扰智能体。需要根据实际测试找到一个平衡点。
• 使用“经验”记忆：对于重复性的任务流程，积极利用experience_store和autoExperience。将成功的解决方案总结成“经验”，其检索效率和对智能体的指导性，远高于零散的事实记忆。

一个实战技巧：调试记忆的注入内容如果你不确定智能体到底收到了哪些记忆，可以在 OpenClaw 网关的日志中设置更详细的日志级别，或者直接修改智能体的系统提示，要求它在思考过程中，将其收到的relevant_memories或工具调用的结果也输出出来。这能帮你直观地看到记忆系统的工作效果，从而进行针对性优化。

记忆系统的搭建和调优是一个持续的过程。开始时，可以从简单的 CLI 模式入手，快速验证想法。随着智能体复杂度和用户量的增长，再逐步迁移到 HTTP 共享服务，并引入双写、经验库、精细化的隔离策略等高级特性。这套由ob-labs/memory-powermem和 PowerMem 组成的工具链，为构建真正实用、智能的 AI 应用提供了坚实的内存基石。