核心用法
Soul Memory 是一款面向AI智能体的长期记忆管理框架，采用纯Python标准库实现，无需任何外部API或云服务。系统通过8个核心模块（优先级解析器、向量搜索、动态分类器、版本控制、记忆衰减、自动触发、粤语分支、CLI接口）构建完整的记忆生命周期管理。
典型使用流程：
1. 初始化系统后，通过[C]/[I]/[N]标签标记记忆优先级（关键/重要/普通）
2. 利用自动触发模块，在AI响应前自动检索相关记忆并注入上下文
3. 对话结束后自动保存新记忆，系统执行语义去重与分级索引
4. Heartbeat机制每3小时自动清理冗余报告，优化存储质量
OpenClaw集成：作为插件运行时，通过before_prompt_build钩子自动提取当前查询、检索Top-K记忆并格式化为前置上下文，避免历史消息循环注入。
显著优点
- 完全本地化：零外部依赖，纯Python标准库，JSON文件存储，适合隐私敏感场景
- 智能上下文注入：OpenClaw插件自动在响应前注入相关记忆，无需手动管理
- 粤语深度支持：独特的语气词分级与语境映射，支持简繁转换及情绪识别
- 自动化运维：Heartbeat自动清理+Cron调度，记忆质量评分从7.9提升至8.5
- 语义去重机制：MD5哈希跟踪+语义相似度检测，避免重复存储
- CLI友好：纯JSON输出便于外部系统集成，支持FastAPI可视化面板
潜在缺点与局限性
- 非真正向量数据库：采用关键词索引+语义扩展，非基于嵌入向量的相似度搜索，大规模数据下检索质量可能下降
- 分类系统较简单：动态学习+预设规则，复杂场景需要人工调优
- OpenClaw绑定：插件功能深度依赖OpenClaw生态，独立使用需自行实现触发逻辑
- 存储格式限制：JSON本地存储，高并发写入场景存在IO瓶颈
- 维护状态存疑：GitHub仓库链接指向kingofqin2026，个人项目长期维护不确定性较高
适合人群
- OpenClaw用户：希望为AI助手添加长期记忆能力的进阶玩家
- 隐私优先用户：拒绝云端记忆服务，坚持数据本地化的开发者
- 粤语使用者：需要AI理解粤语语气词与情绪语境的特殊需求场景
- 低资源环境用户：无GPU、无外网，需在边缘设备运行记忆系统的场景
- 自动化运维爱好者：需要定时清理、自动归档的"Set and Forget"用户
常规风险
- 数据持久化风险：JSON文件损坏或误删会导致记忆丢失，建议配合
--backup参数定期备份 - 循环注入陷阱：虽v0.2.1-beta已修复，但自定义插件仍可能因逻辑错误导致记忆递归注入
- 语义漂移：自动分类学习可能随时间产生类别漂移，需定期人工校准
- 权限管理缺失：无多用户隔离机制，共享环境存在记忆串扰风险
- 升级兼容性：v3.x版本间存在索引策略变更，跨版本升级需完整卸载重装