核心用法
Soul Memory 是一款面向 AI Agent 的长期记忆管理框架，采用模块化设计（A-H 八大模块），支持从内存优先级解析、向量检索到自动触发注入的完整工作流。用户可通过 Python API 或纯 JSON 输出的 CLI 接口操作，亦可部署 FastAPI Web 仪表盘实时监控。其与 OpenClaw 的深度集成（before_prompt_build Hook）能在每次响应前自动检索并注入相关记忆上下文，实现「无感」记忆增强。
典型使用路径：初始化系统 → 通过 [C]/[I]/[N] 标签写入分级记忆 → 配置 OpenClaw 插件自动触发检索 → 利用 Heartbeat 定时任务自动清理过期记忆。
显著优点
1. 完全本地化：零外部 API 调用，纯 Python 标准库实现，数据存储于本地 JSON，隐私可控。
2. OpenClaw 原生集成：官方插件支持自动上下文注入，避免记忆循环递归，且具备版本回滚能力。
3. CJK 深度优化：中文分词、粤语语气词分级、简繁转换支持，对中文场景友好。
4. Heartbeat 自动运维：内置 Cron 任务与去重机制（MD5 哈希），记忆质量评分从 7.9 提升至 8.5。
5. CLI 与 Web 双模式：既满足开发者脚本化需求，也提供可视化仪表盘。
潜在局限
- 搜索非纯向量：依赖关键词索引 + 语义扩展，非基于嵌入向量的近似最近邻（ANN）检索，大规模数据下性能可能受限。
- 单用户架构：未明确支持多用户隔离或分布式部署，企业级并发场景需自行扩展。
- OpenClaw 生态依赖：核心自动化功能依赖 OpenClaw Gateway，若用户未部署该环境，插件价值大打折扣。
- 版本迭代较快：v3.3.1 发布于 2026-02-27（文档日期），API 可能存在短期不兼容风险。
适合人群
- 使用 OpenClaw 搭建本地 AI 助手的进阶用户
- 对数据隐私敏感、拒绝云端记忆服务的开发者
- 需要粤语/中文语义理解的特定区域用户
- 希望快速实验记忆增强 Agent 的研究者
常规风险
- 数据持久化风险：本地 JSON 存储无事务机制，异常断电可能导致记忆文件损坏，建议定期
--backup。 - 权限管理缺失：无内置身份鉴权，多用户共用机器时记忆数据可被任意读取。
- Plugin 版本耦合：OpenClaw Plugin v0.2.1-beta 与特定 Gateway 版本绑定，升级时需同步验证兼容性。
- Cron 任务副作用：自动清理脚本若配置不当可能误删有效记忆，建议先以
--backup模式试运行。