小智 ESP32 服务器集成 PowerMem 记忆组件：配置、用户画像与源码级原理

• 后端
• 物联网
• 语音
• 人工智能
• AI 应用
• AI Agent
• RAG

【免费下载链接】xiaozhi-esp32-server

本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.

项目地址：
https://gitcode.com/gh_mirrors/xia/xiaozhi-esp32-server

点击查看 免费下载

PowerMem 是 OceanBase 开源的 Agent 记忆组件，它通过本地 LLM 完成记忆总结与向量检索，为 AI 代理提供高效的记忆管理能力。本指南以 xiaozhi-esp32-server 项目中 docs/powermem-integration.md 为核心，结合仓库内 powermem 记忆提供方的真实源码与配置，完整讲解 PowerMem 的安装、四种典型配置方案（通义千问 / 智谱免费方案 / OpenAI / OceanBase）、设备记忆隔离与用户画像（UserMemory）的工作原理，并给出可验证的测试方法，帮助你在 ESP32 后端服务上快速落地持久化记忆能力。

PowerMem 是什么

PowerMem 是由 OceanBase 开源、基于本地 LLM 进行记忆总结与智能检索的 Agent 记忆组件。在 xiaozhi-esp32-server 中，它作为 Memory 模块的一个可选提供方（provider），被封装在 powermem.py 中，实现与 mem0ai、mem_local_short 等记忆组件同等的插拔接口。

费用说明

PowerMem 本身开源免费，实际费用取决于你选择的 LLM 与数据库：

• 使用 SQLite + 免费 LLM（如智谱 glm-4-flash）= 完全免费；
• 使用云端 LLM 或云端数据库 = 按对应服务收费。

性能提示：PowerMem 配合 OceanBase 使用可实现最大性能释放，SQLite 仅建议在资源不足的情况下使用。

功能特性

• 本地总结：通过 LLM 在本地完成记忆总结和提取，数据不经过第三方记忆平台；
• 用户画像：通过 UserMemory 自动提取用户信息（姓名、职业、兴趣等），并持续更新用户画像；
• 智能遗忘：基于艾宾浩斯遗忘曲线，自动"遗忘"过时噪声信息；
• 多种存储后端：支持 OceanBase（推荐，最佳性能）、SeekDB（推荐，AI 应用存储一体）、PostgreSQL、SQLite（轻量备选）；
• 多种 LLM 支持：通义千问、智谱（glm-4-flash 免费）、OpenAI 等；
• 智能检索：基于向量搜索的语义检索能力；
• 私有部署：完全支持本地私有化部署；
• 异步操作：高效的异步记忆管理。

安装与依赖

PowerMem 已添加到项目依赖中。仓库的 requirements.txt 中声明了 powermem>=0.3.1（该版本约束与文档所述"用户画像功能需 0.3.0+"一致）。如果需要手动安装：

pip install powermem

从源码结构看，记忆模块采用"目录即提供方"的动态加载机制：memory.py 中的 create_instance 会根据配置的 type 名称，从 core/providers/memory/{class_name}/{class_name}.py 动态导入并实例化对应的 MemoryProvider 类。因此，只要 selected_module.Memory 指向 powermem，服务启动时就会自动加载 powermem.py 中定义的 MemoryProvider。

配置说明

基础配置

在 config.yaml 中，selected_module 下的 Memory 字段用于选择记忆组件，默认是 nomem（不开启记忆）。切换到 PowerMem 需要做两步配置：

selected_module:
Memory: powermem

Memory:
powermem:
type: powermem
# 是否启用用户画像功能
# 用户画像支持: oceanbase、seekdb、sqlite (powermem 0.3.0+)
enable_user_profile: true

# ========== LLM 配置 ==========
llm:
provider: openai # 可选: qwen, openai, zhipu 等
config:
api_key: 你的LLM API密钥
model: qwen-plus
# openai_base_url: https://api.openai.com/v1 # 可选，自定义服务地址

# ========== Embedding 配置 ==========
embedder:
provider: openai # 可选: qwen, openai 等
config:
api_key: 你的嵌入模型API密钥
model: text-embedding-v4
openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
# embedding_dims: 1024 # 向量维度，非1536时需配置

# ========== Database 配置 ==========
vector_store:
provider: sqlite # 可选: oceanbase(推荐), seekdb(推荐), postgres, sqlite(轻量)
config: {} # SQLite 无需额外配置

这段配置与 config.yaml 中 Memory.powermem 的默认示例完全对应，可直接复制使用。

配置参数详解

LLM 配置

Embedding 配置

Database 配置

记忆模式说明

PowerMem 支持两种记忆模式：

版本说明：PowerMem 0.3.0+ 版本，用户画像功能支持 OceanBase、SeekDB、SQLite 三种存储后端。

源码中的两种配置风格

从 powermem.py 的初始化逻辑可以看出，PowerMem 支持两种配置风格，项目中均已兼容：

解析优先级为：如果配置中已存在 vector_store 则直接采用；否则回退到 database；再否则由 database_provider（默认 sqlite）自动构造。LLM 与 Embedding 同理，若未提供嵌套的 llm/embedder 对象，则从 llm_api_key、llm_model、dashscope_base_url、openai_base_url 等扁平字段自动拼装。此外，对于 qwen 提供商，base_url 走 dashscope_base_url，其余提供商走 openai_base_url，对应字段的优先级为 embedding_xxx_base_url > embedding_base_url > xxx_base_url。

四种典型部署配置

使用通义千问（推荐）

Memory:
powermem:
type: powermem
enable_user_profile: true
llm:
provider: qwen
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: qwen-plus
embedder:
provider: openai
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: text-embedding-v4
openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
vector_store:
provider: sqlite
config: {}

说明：通义千问的文本模型与 Embedding 模型（text-embedding-v4）共用百炼平台的 API Key；Embedding 通过 DashScope 的 OpenAI 兼容模式访问，因此 embedder.provider 填 openai 并指定 openai_base_url 为百炼兼容地址即可。

使用智谱免费 LLM（完全免费方案）

智谱提供免费的 glm-4-flash 模型，配合 SQLite 可实现完全免费使用：

Memory:
powermem:
type: powermem
enable_user_profile: true
llm:
provider: openai # 使用 openai 兼容模式
config:
api_key: xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx
model: glm-4-flash
openai_base_url: https://open.bigmodel.cn/api/paas/v4/
embedder:
provider: openai
config:
api_key: xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx
model: embedding-3
openai_base_url: https://open.bigmodel.cn/api/paas/v4/
vector_store:
provider: sqlite
config: {}

使用 OpenAI

Memory:
powermem:
type: powermem
enable_user_profile: true
llm:
provider: openai
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: gpt-4o-mini
openai_base_url: https://api.openai.com/v1
embedder:
provider: openai
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: text-embedding-3-small
openai_base_url: https://api.openai.com/v1
vector_store:
provider: sqlite
config: {}

使用 OceanBase（最佳性能方案）

OceanBase 是 PowerMem 的最佳搭档，可实现最大性能释放。部署方式支持开源本地部署与云服务两种。配置如下：

Memory:
powermem:
type: powermem
enable_user_profile: true
llm:
provider: qwen
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: qwen-plus
embedder:
provider: openai
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: text-embedding-v4
openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
vector_store:
provider: oceanbase
config:
host: 127.0.0.1
port: 2881
user: root@test
password: your_password
db_name: powermem
collection_name: memories # 默认值
embedding_model_dims: 1536 # 嵌入向量维度，必需参数

注意两点：

• embedding_model_dims 为必需参数，必须与所用嵌入模型的输出维度一致。仓库 config.yaml 中有更具体的示例提示：以智谱为例，embedding-2 的维度是 1024，embedding-3 的维度是 2048；若创建表时维度错误，需删除 collection_name 指定的表或更换表名重建。
• embedding_dims（LLM/Embedding 小节内的注释项）用于非 1536 维度的向量配置，与 OceanBase 的 embedding_model_dims 需保持一致。

设备记忆隔离

PowerMem 会自动使用设备 ID（device_id）作为 user_id 进行记忆隔离。这意味着：

• 每个设备拥有独立的记忆空间；
• 不同设备之间的记忆完全隔离；
• 同一设备的多次对话可以共享记忆上下文。

在源码层面，记忆提供方的 role_id 由 base.py 的 init_memory(role_id, llm) 注入；powermem.py 在保存记忆时以 self.role_id 作为 user_id 调用 PowerMem 的 add，查询时同样以 self.role_id 作为 user_id 调用 search，从而实现"每台设备一个独立记忆空间"的隔离语义。

用户画像（UserMemory）

PowerMem 提供 UserMemory 类，可自动从对话中提取用户画像信息。

版本说明：PowerMem 0.3.0+ 版本，用户画像功能支持 OceanBase、SeekDB、SQLite 三种存储后端。

启用用户画像

在配置中设置 enable_user_profile: true 即可启用：

Memory:
powermem:
type: powermem
enable_user_profile: true # 启用用户画像
llm:
provider: qwen
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: qwen-plus
embedder:
provider: openai
config:
api_key: sk-xxxxxxxxxxxxxxxx
model: text-embedding-v4
openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
vector_store:
provider: sqlite # 用户画像支持: oceanbase、seekdb、sqlite
config: {}

用户画像能力

工作原理

启用用户画像后，小智在查询记忆时会自动返回两类内容：

源码级工作流程

在 powermem.py 中可以完整看到用户画像模式的实现链路：

• 初始化（第 124-131 行）：enable_user_profile: true 时实例化 UserMemory（同步 SDK），否则实例化 AsyncMemory（异步 SDK），并把模式写入日志；
• 保存记忆（第 186-206 行）：UserMemory.add 是同步接口，通过 asyncio.to_thread 包装以避免阻塞事件循环；若返回结果携带 profile_extracted 标志，则把新提取的 profile_content 缓存到 last_profile_content；
• 查询记忆（第 251-271 行）：先调用 get_user_profile() 拼装 【用户画像】 段，再以 limit=30 搜索相关记忆，逐条格式化时间戳后按 updated_at/created_at 降序排列，输出 【相关记忆】 段；
• 画像获取（第 322-384 行）：采用"缓存优先"策略——缓存命中直接返回；缓存为空时才调用 UserMemory.profile()，优先取 profile_content，为空则回退到 topics 并序列化为 JSON 字符串。缓存机制避免了每次查询都发起一次画像拉取，是查询性能优化的关键。

另外，保存与查询都会对 ASR 输出的 JSON 格式内容（如带情绪/语言标签的识别结果）做一次解析，提取其中的 content 字段后再交给 PowerMem，确保记忆内容是纯文本。

与其他记忆组件的对比

从仓库 config.yaml 看，Memory 节下同时预置了 mem0ai、powermem、nomem、mem_local_short 四种提供方，按需在 selected_module.Memory 中切换即可。选择建议：注重隐私选 mem_local_short；需要持久化向量记忆且可控成本选 powermem；nomem 则完全关闭记忆。

常见问题排查

1. API 密钥错误

如果出现 API key is required 错误，请检查：

• llm.config.api_key 与 embedder.config.api_key 是否正确填写；
• API 密钥是否有效（注意通义千问与智谱的 Key 格式不同）。

2. 模型不存在

如果出现模型不存在的错误，请确认：

• llm.config.model 与 embedder.config.model 名称是否正确；
• 对应的模型服务是否已开通（如通义千问的 text-embedding-v4、智谱的 embedding-3 需在平台开通相应权限）。

3. 连接超时

如果出现连接超时，可以尝试：

• 检查网络连接；
• 如果使用代理，为 llm 与 embedder 分别配置 openai_base_url（或 qwen 场景的 dashscope_base_url）。

4. 初始化失败时排查

powermem.py 对两类初始化失败做了区分：ImportError 提示"PowerMem not installed. Please install with: pip install powermem"，其他异常则输出 Failed to initialize PowerMem 及详细堆栈。初始化失败时 use_powermem 会被置为 False，后续 save_memory/query_memory 会打印警告并安全跳过，不会导致服务崩溃——这是"记忆组件降级可用"的容错设计。

测试验证

可以在虚拟环境中测试 PowerMem 是否正常工作：

# 激活虚拟环境
source .venv/bin/activate

# 测试 PowerMem 导入
python -c "from powermem import AsyncMemory; print('PowerMem 导入成功')"

# 测试 UserMemory 导入（用户画像功能）
python -c "from powermem import UserMemory; print('UserMemory 导入成功')"

仓库还提供了针对记忆链路的自动化测试 test_memory.py：

• 默认 Mock 模式从配置构造真实 provider，但外部 SDK 调用走 shim，不会真正发起请求；
• 测试 test_memory_provider_constructs_from_config 校验 provider 能从配置实例化且属于 MemoryProviderBase；
• 测试 test_memory_provider_exposes_save_and_query 校验 provider 必须实现 save_memory / query_memory 两个接口（与 base.py 的抽象方法约定一致）；
• 测试 test_memory_save_and_query_roundtrip 验证 save 后 query 不抛异常；
• 若需调用真实记忆服务，设置环境变量 RUN_LIVE_API_TESTS=1 即可切换到 Live 模式。

进一步阅读

• 提供方实现：powermem.py
• 记忆基类与接口约定：base.py
• 动态加载机制：memory.py
• 完整配置示例：config.yaml
• 依赖声明：requirements.txt
• 记忆链路测试：test_memory.py
• 其他记忆组件：mem0ai 与 mem_local_short 位于 memory 目录 下的同名子目录中，可对比阅读实现差异。

赞

分享

• 后端
• 物联网
• 语音
• 人工智能
• AI 应用
• AI Agent
• RAG

【免费下载链接】xiaozhi-esp32-server

本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.

项目地址：
https://gitcode.com/gh_mirrors/xia/xiaozhi-esp32-server

点击查看 免费下载

相关推荐

• Homepage 集成 Channels DVR Server 服务组件：配置、数据指标与源码级原理解析

  Homepage 集成 Channels DVR Server 服务组件：配置、数据指标与源码级原理解析 Channels DVR Server 是 Homep

  前端

• Apache APISIX 集成 Nacos 服务发现：从配置到源码级原理

  Apache APISIX 集成 Nacos 服务发现：从配置到源码级原理 导读：本文以 Apache APISIX 官方文档 docs/en/latest/d

  API网关
  后端
  云原生
  微服务

• Homepage 集成 Gotify 服务组件：配置指南与源码级实现解析

  Homepage 集成 Gotify 服务组件：配置指南与源码级实现解析 Gotify 是一款自托管的轻量级消息推送服务，通常与各类自动化任务、监控告警协同使用

  前端

上一篇：
虎符台终极指南：三步快速掌握全面战争MOD管理神器

下一篇：
BongoCat自定义模型快速上手指南

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考