1. 项目概述PowerMem 是什么PowerMem 是一个为 AI Agent 设计的自进化记忆层系统它解决了传统 AI 对话系统健忘的核心痛点。想象一下你每天和同一个助手聊天但它永远记不住你昨天说过什么 - 这就是 PowerMem 要改变的状况。这个系统最吸引我的地方在于它的四步进化循环捕获Capture→存储Store→检索Retrieve→进化Evolve。不同于简单的聊天记录存储PowerMem 会主动分析、压缩和关联记忆让 Agent 真正成长。从技术架构看它包含三个关键组件服务端基于 Python 的 HTTP API 服务处理记忆的存储和检索向量数据库内置的 seekdb 或可选的 OceanBase/SQLite 存储客户端插件支持 Claude Code 和 OpenClaw 等主流 Agent 平台2. 环境准备与安装2.1 硬件与软件要求在开始前确保你的环境满足以下条件Linux 服务端最低配置CPU4核推荐 8 核以上用于向量计算内存8GB推荐 16GB存储50GB SSD向量索引会占用大量空间Python 3.11强烈建议使用 pyenv 管理版本特别注意如果使用内置 seekdb首次启动会下载约 2GB 的嵌入模型Windows 仅支持作为客户端连接不能运行服务端2.2 安装方式对比提供两种安装方案根据你的使用场景选择方案A生产环境推荐# 使用更快的 uv 替代 pip curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc # 安装完整功能包 uv pip install powermem[cli,server,mcp,seekdb]方案B开发环境git clone https://github.com/oceanbase/powermem.git cd powermem uv pip install -e .[cli,server,mcp,seekdb,dev]关键提示mcp扩展包是跨 Agent 通信的必备组件如果计划连接多个 Agent 平台必须安装2.3 组件功能详解安装时不同的 extras 提供不同能力扩展包功能说明是否必需clipmem 命令行工具是serverHTTP API 服务是mcp多 Agent 通信协议支持可选seekdb内置向量数据库可选dev开发工具测试/调试仅开发3. 服务端配置详解3.1 初始化配置运行交互式配置向导pmem config init这会生成.env配置文件以下是关键参数解析数据库配置# 使用 SQLite单机测试推荐 DATABASE_PROVIDERsqlite SQLITE_PATH/path/to/powermem.db # 或使用 OceanBase生产环境 DATABASE_PROVIDERoceanbase OB_HOST127.0.0.1 OB_PORT2881 OB_USERroot OB_PASSWORDyour_password大模型配置# OpenAI 兼容 API LLM_PROVIDERopenai LLM_API_KEYsk-xxx LLM_MODELgpt-4 OPENAI_LLM_BASE_URLhttps://api.yourproxy.com/v1 # 或使用 Anthropic LLM_PROVIDERanthropic ANTHROPIC_LLM_BASE_URLhttps://your-proxy.com嵌入模型配置核心# 硅基流动模型中文推荐 EMBEDDING_PROVIDERsiliconflow EMBEDDING_API_KEYsk-xxx EMBEDDING_MODELBAAI/bge-m3 EMBEDDING_DIMS1024 # 维度必须与模型匹配3.2 常见配置误区问题1SQLite 路径写成目录错误示例SQLITE_PATH/data/powermem/正确示例SQLITE_PATH/data/powermem/powermem.db问题2忘记设置 EMBEDDING_DIMS使用 seekdb 时必须明确指定向量维度否则启动报错问题3混合使用不同提供商的组件避免 OpenAI LLM Anthropic Embedding 的组合可能因 API 速率限制导致性能下降3.3 启动与监控启动生产级服务powermem-server \ --host 0.0.0.0 \ --port 8848 \ --workers 8 \ --log-level WARNING关键参数调优建议--workers通常设为 CPU 核数的 1.5 倍使用内置 seekdb 时workers 必须设为 1添加--preload参数可以加速首次响应验证服务健康状态curl -s http://localhost:8848/api/v1/system/health | jq # 预期输出{status:ok,version:1.2.0}4. 客户端集成实战4.1 Claude Code 集成步骤步骤1安装插件/plugin marketplace add oceanbase/powermem /plugin install memory-powermempowermem /reload-plugins步骤2Windows 特别处理修改 hooks.json 文件路径%USERPROFILE%\.claude\plugins\cache\powermem\memory-powermem\0.1.0\hooks\hooks.json{ hooks: { UserPromptSubmit: [ { hooks: [ { type: command, command: powershell.exe -NoProfile -ExecutionPolicy Bypass -File \${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.ps1\, timeout: 120 } ] } ] } }步骤3配置连接编辑settings.json{ env: { POWERMEM_BASE_URL: http://your-server:8848, POWERMEM_API_KEY: your-key, POWERMEM_AUTO_RECALL: true, POWERMEM_AUTO_STORE: true } }4.2 OpenClaw 集成技巧记忆测试命令/remember 重要信息我的API密钥是123-456仅测试用 /recall API密钥性能优化配置# 在 powermem.env 中增加 MAX_MEMORY_ITEMS5000 # 控制单用户记忆上限 MEMORY_COMPRESSION_THRESHOLD0.85 # 相似度阈值4.3 跨平台同步方案通过 MCP 协议实现 Claude Code 和 OpenClaw 的记忆共享在两台设备上安装 mcp 扩展包配置相同的MCP_GROUP_ID环境变量设置主节点pmem mcp enable --mode leader --port 188885. 高级功能与调优5.1 记忆进化策略自定义进化规则创建evolution_rules.yaml- name: api_key_protection pattern: (?i)(api|access)_?key\s*[:]\s*[\]?([a-z0-9_-]) action: redact params: replace_with: [REDACTED] - name: code_enhancement when: memory.metadata.type code action: embed_with_context params: prepend: 这是用户提供的示例代码可能有错误通过 API 应用规则curl -X POST -H X-API-Key: your-key \ -d evolution_rules.yaml \ http://localhost:8848/api/v1/evolution/rules5.2 性能监控仪表板启用 Prometheus 监控# .env 中新增 POWERMEM_METRICS_ENABLEDtrue POWERMEM_METRICS_PORT9090关键监控指标powermem_memory_ops_total记忆操作计数器powermem_embedding_duration_seconds向量化耗时powermem_retrieval_latency_ms检索延迟5.3 灾备与迁移备份记忆数据pmem db backup --output backup.sqlite3跨数据库迁移pmem db migrate \ --source sqlite:///old.db \ --target oceanbase://user:passhost:2881/memdb6. 故障排查手册6.1 常见错误解决方案错误1Error: Embedding dimension mismatch检查.env中EMBEDDING_DIMS是否与模型匹配运行pmem check-dimensions验证错误2[WinError 193] %1 is not a valid Win32 application确保在 Windows 客户端使用 PowerShell 命令重新生成 hooks.json 文件错误3记忆检索不准确检查嵌入模型是否支持中文推荐 bge-m3调整检索参数MEMORY_RETRIEVAL_TOPK7 MEMORY_SIMILARITY_THRESHOLD0.656.2 日志分析技巧查看详细日志journalctl -u powermem -f # systemd 服务 或 tail -f /var/log/powermem.log关键日志标记[MEMORY_COMPACT]记忆压缩过程[EVOLUTION]自动进化事件[RETRIEVAL]记忆检索详情6.3 调试模式启用临时开启调试POWERMEM_DEBUG1 powermem-server --log-level DEBUG获取会话诊断信息/diagnostic memory-powermem7. 生产环境最佳实践7.1 安全加固措施启用 API 认证POWERMEM_SERVER_AUTH_ENABLEDtrue POWERMEM_SERVER_API_KEYSyour-secret-key-1,your-secret-key-2配置 HTTPSpmem config tls \ --cert /path/to/cert.pem \ --key /path/to/key.pem敏感记忆加密MEMORY_ENCRYPTION_ENABLEDtrue MEMORY_ENCRYPTION_KEYyour-32-char-key7.2 高可用部署方案A负载均衡upstream powermem { server 10.0.0.1:8848; server 10.0.0.2:8848; } server { listen 443 ssl; location / { proxy_pass http://powermem; } }方案B数据库集群配置 OceanBase 集群设置DATABASE_PROVIDERoceanbase添加多个 OB 节点到连接字符串7.3 性能调优参数关键.env调优参数# 向量索引优化 SEEKDB_INDEX_TYPEHNSW SEEKDB_EF_CONSTRUCTION200 SEEKDB_M32 # 缓存配置 MEMORY_CACHE_ENABLEDtrue MEMORY_CACHE_TTL3600 MEMORY_CACHE_SIZE10000 # 批处理设置 EMBEDDING_BATCH_SIZE32 STORAGE_BATCH_COMMIT1008. 进阶开发指南8.1 插件开发创建自定义记忆处理器from powermem import MemoryProcessor class MyProcessor(MemoryProcessor): def pre_store(self, memory): # 存储前处理 if 密码 in memory.text: memory.text memory.text.replace(密码, [REDACTED]) return memory def post_retrieve(self, memories): # 检索后处理 return sorted(memories, keylambda m: m.score, reverseTrue)注册处理器from powermem.plugins import register_processor register_processor(security, MyProcessor())8.2 API 扩展添加自定义端点from fastapi import APIRouter from powermem.server import PowerMemServer router APIRouter() router.get(/custom-endpoint) async def custom(): return {message: Hello from extension!} server PowerMemServer() server.include_router(router, prefix/extensions)8.3 记忆可视化使用内置 Dashboard 扩展点// 在 /dashboard/static/custom.js 中添加 PowerMemDashboard.registerPanel(custom, { title: 我的面板, render: (container) { container.innerHTML h3自定义可视化/h3; // 添加自定义图表逻辑 } });9. 典型应用场景9.1 客户支持助手实现效果记住客户历史问题自动关联相似案例生成个性化响应配置要点MEMORY_NAMESPACEcustomer_support MEMORY_RETENTION_DAYS180 AUTO_COMPACT_INTERVAL36009.2 个人知识管理工作流通过/remember保存重要信息自动关联相关笔记生成知识图谱增强命令/search-memories 去年讨论过的API设计模式 /visualize-knowledge 网络安全9.3 团队协作增强共享记忆配置TEAM_SHARED_MEMORIEStrue TEAM_IDdev-team-42 ACCESS_CONTROL_MODErole_based角色定义roles: - name: developer permissions: - memory:read - memory:write - memory:delete_own - name: manager permissions: - memory:*10. 未来演进路线10.1 短期规划v1.3多模态记忆支持图像/音频记忆版本控制增量索引更新10.2 中期规划v2.0分布式记忆网络联邦学习支持记忆溯源功能10.3 社区贡献指引欢迎通过以下方式参与提交插件到 Marketplace完善文档翻译报告性能优化建议贡献前请阅读pmem contribution guidelines
PowerMem：AI Agent自进化记忆层系统设计与实践
1. 项目概述PowerMem 是什么PowerMem 是一个为 AI Agent 设计的自进化记忆层系统它解决了传统 AI 对话系统健忘的核心痛点。想象一下你每天和同一个助手聊天但它永远记不住你昨天说过什么 - 这就是 PowerMem 要改变的状况。这个系统最吸引我的地方在于它的四步进化循环捕获Capture→存储Store→检索Retrieve→进化Evolve。不同于简单的聊天记录存储PowerMem 会主动分析、压缩和关联记忆让 Agent 真正成长。从技术架构看它包含三个关键组件服务端基于 Python 的 HTTP API 服务处理记忆的存储和检索向量数据库内置的 seekdb 或可选的 OceanBase/SQLite 存储客户端插件支持 Claude Code 和 OpenClaw 等主流 Agent 平台2. 环境准备与安装2.1 硬件与软件要求在开始前确保你的环境满足以下条件Linux 服务端最低配置CPU4核推荐 8 核以上用于向量计算内存8GB推荐 16GB存储50GB SSD向量索引会占用大量空间Python 3.11强烈建议使用 pyenv 管理版本特别注意如果使用内置 seekdb首次启动会下载约 2GB 的嵌入模型Windows 仅支持作为客户端连接不能运行服务端2.2 安装方式对比提供两种安装方案根据你的使用场景选择方案A生产环境推荐# 使用更快的 uv 替代 pip curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc # 安装完整功能包 uv pip install powermem[cli,server,mcp,seekdb]方案B开发环境git clone https://github.com/oceanbase/powermem.git cd powermem uv pip install -e .[cli,server,mcp,seekdb,dev]关键提示mcp扩展包是跨 Agent 通信的必备组件如果计划连接多个 Agent 平台必须安装2.3 组件功能详解安装时不同的 extras 提供不同能力扩展包功能说明是否必需clipmem 命令行工具是serverHTTP API 服务是mcp多 Agent 通信协议支持可选seekdb内置向量数据库可选dev开发工具测试/调试仅开发3. 服务端配置详解3.1 初始化配置运行交互式配置向导pmem config init这会生成.env配置文件以下是关键参数解析数据库配置# 使用 SQLite单机测试推荐 DATABASE_PROVIDERsqlite SQLITE_PATH/path/to/powermem.db # 或使用 OceanBase生产环境 DATABASE_PROVIDERoceanbase OB_HOST127.0.0.1 OB_PORT2881 OB_USERroot OB_PASSWORDyour_password大模型配置# OpenAI 兼容 API LLM_PROVIDERopenai LLM_API_KEYsk-xxx LLM_MODELgpt-4 OPENAI_LLM_BASE_URLhttps://api.yourproxy.com/v1 # 或使用 Anthropic LLM_PROVIDERanthropic ANTHROPIC_LLM_BASE_URLhttps://your-proxy.com嵌入模型配置核心# 硅基流动模型中文推荐 EMBEDDING_PROVIDERsiliconflow EMBEDDING_API_KEYsk-xxx EMBEDDING_MODELBAAI/bge-m3 EMBEDDING_DIMS1024 # 维度必须与模型匹配3.2 常见配置误区问题1SQLite 路径写成目录错误示例SQLITE_PATH/data/powermem/正确示例SQLITE_PATH/data/powermem/powermem.db问题2忘记设置 EMBEDDING_DIMS使用 seekdb 时必须明确指定向量维度否则启动报错问题3混合使用不同提供商的组件避免 OpenAI LLM Anthropic Embedding 的组合可能因 API 速率限制导致性能下降3.3 启动与监控启动生产级服务powermem-server \ --host 0.0.0.0 \ --port 8848 \ --workers 8 \ --log-level WARNING关键参数调优建议--workers通常设为 CPU 核数的 1.5 倍使用内置 seekdb 时workers 必须设为 1添加--preload参数可以加速首次响应验证服务健康状态curl -s http://localhost:8848/api/v1/system/health | jq # 预期输出{status:ok,version:1.2.0}4. 客户端集成实战4.1 Claude Code 集成步骤步骤1安装插件/plugin marketplace add oceanbase/powermem /plugin install memory-powermempowermem /reload-plugins步骤2Windows 特别处理修改 hooks.json 文件路径%USERPROFILE%\.claude\plugins\cache\powermem\memory-powermem\0.1.0\hooks\hooks.json{ hooks: { UserPromptSubmit: [ { hooks: [ { type: command, command: powershell.exe -NoProfile -ExecutionPolicy Bypass -File \${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.ps1\, timeout: 120 } ] } ] } }步骤3配置连接编辑settings.json{ env: { POWERMEM_BASE_URL: http://your-server:8848, POWERMEM_API_KEY: your-key, POWERMEM_AUTO_RECALL: true, POWERMEM_AUTO_STORE: true } }4.2 OpenClaw 集成技巧记忆测试命令/remember 重要信息我的API密钥是123-456仅测试用 /recall API密钥性能优化配置# 在 powermem.env 中增加 MAX_MEMORY_ITEMS5000 # 控制单用户记忆上限 MEMORY_COMPRESSION_THRESHOLD0.85 # 相似度阈值4.3 跨平台同步方案通过 MCP 协议实现 Claude Code 和 OpenClaw 的记忆共享在两台设备上安装 mcp 扩展包配置相同的MCP_GROUP_ID环境变量设置主节点pmem mcp enable --mode leader --port 188885. 高级功能与调优5.1 记忆进化策略自定义进化规则创建evolution_rules.yaml- name: api_key_protection pattern: (?i)(api|access)_?key\s*[:]\s*[\]?([a-z0-9_-]) action: redact params: replace_with: [REDACTED] - name: code_enhancement when: memory.metadata.type code action: embed_with_context params: prepend: 这是用户提供的示例代码可能有错误通过 API 应用规则curl -X POST -H X-API-Key: your-key \ -d evolution_rules.yaml \ http://localhost:8848/api/v1/evolution/rules5.2 性能监控仪表板启用 Prometheus 监控# .env 中新增 POWERMEM_METRICS_ENABLEDtrue POWERMEM_METRICS_PORT9090关键监控指标powermem_memory_ops_total记忆操作计数器powermem_embedding_duration_seconds向量化耗时powermem_retrieval_latency_ms检索延迟5.3 灾备与迁移备份记忆数据pmem db backup --output backup.sqlite3跨数据库迁移pmem db migrate \ --source sqlite:///old.db \ --target oceanbase://user:passhost:2881/memdb6. 故障排查手册6.1 常见错误解决方案错误1Error: Embedding dimension mismatch检查.env中EMBEDDING_DIMS是否与模型匹配运行pmem check-dimensions验证错误2[WinError 193] %1 is not a valid Win32 application确保在 Windows 客户端使用 PowerShell 命令重新生成 hooks.json 文件错误3记忆检索不准确检查嵌入模型是否支持中文推荐 bge-m3调整检索参数MEMORY_RETRIEVAL_TOPK7 MEMORY_SIMILARITY_THRESHOLD0.656.2 日志分析技巧查看详细日志journalctl -u powermem -f # systemd 服务 或 tail -f /var/log/powermem.log关键日志标记[MEMORY_COMPACT]记忆压缩过程[EVOLUTION]自动进化事件[RETRIEVAL]记忆检索详情6.3 调试模式启用临时开启调试POWERMEM_DEBUG1 powermem-server --log-level DEBUG获取会话诊断信息/diagnostic memory-powermem7. 生产环境最佳实践7.1 安全加固措施启用 API 认证POWERMEM_SERVER_AUTH_ENABLEDtrue POWERMEM_SERVER_API_KEYSyour-secret-key-1,your-secret-key-2配置 HTTPSpmem config tls \ --cert /path/to/cert.pem \ --key /path/to/key.pem敏感记忆加密MEMORY_ENCRYPTION_ENABLEDtrue MEMORY_ENCRYPTION_KEYyour-32-char-key7.2 高可用部署方案A负载均衡upstream powermem { server 10.0.0.1:8848; server 10.0.0.2:8848; } server { listen 443 ssl; location / { proxy_pass http://powermem; } }方案B数据库集群配置 OceanBase 集群设置DATABASE_PROVIDERoceanbase添加多个 OB 节点到连接字符串7.3 性能调优参数关键.env调优参数# 向量索引优化 SEEKDB_INDEX_TYPEHNSW SEEKDB_EF_CONSTRUCTION200 SEEKDB_M32 # 缓存配置 MEMORY_CACHE_ENABLEDtrue MEMORY_CACHE_TTL3600 MEMORY_CACHE_SIZE10000 # 批处理设置 EMBEDDING_BATCH_SIZE32 STORAGE_BATCH_COMMIT1008. 进阶开发指南8.1 插件开发创建自定义记忆处理器from powermem import MemoryProcessor class MyProcessor(MemoryProcessor): def pre_store(self, memory): # 存储前处理 if 密码 in memory.text: memory.text memory.text.replace(密码, [REDACTED]) return memory def post_retrieve(self, memories): # 检索后处理 return sorted(memories, keylambda m: m.score, reverseTrue)注册处理器from powermem.plugins import register_processor register_processor(security, MyProcessor())8.2 API 扩展添加自定义端点from fastapi import APIRouter from powermem.server import PowerMemServer router APIRouter() router.get(/custom-endpoint) async def custom(): return {message: Hello from extension!} server PowerMemServer() server.include_router(router, prefix/extensions)8.3 记忆可视化使用内置 Dashboard 扩展点// 在 /dashboard/static/custom.js 中添加 PowerMemDashboard.registerPanel(custom, { title: 我的面板, render: (container) { container.innerHTML h3自定义可视化/h3; // 添加自定义图表逻辑 } });9. 典型应用场景9.1 客户支持助手实现效果记住客户历史问题自动关联相似案例生成个性化响应配置要点MEMORY_NAMESPACEcustomer_support MEMORY_RETENTION_DAYS180 AUTO_COMPACT_INTERVAL36009.2 个人知识管理工作流通过/remember保存重要信息自动关联相关笔记生成知识图谱增强命令/search-memories 去年讨论过的API设计模式 /visualize-knowledge 网络安全9.3 团队协作增强共享记忆配置TEAM_SHARED_MEMORIEStrue TEAM_IDdev-team-42 ACCESS_CONTROL_MODErole_based角色定义roles: - name: developer permissions: - memory:read - memory:write - memory:delete_own - name: manager permissions: - memory:*10. 未来演进路线10.1 短期规划v1.3多模态记忆支持图像/音频记忆版本控制增量索引更新10.2 中期规划v2.0分布式记忆网络联邦学习支持记忆溯源功能10.3 社区贡献指引欢迎通过以下方式参与提交插件到 Marketplace完善文档翻译报告性能优化建议贡献前请阅读pmem contribution guidelines
