核心概述
Smart Memory v2 是一套为 OpenClaw 设计的持久化认知记忆运行时系统，突破传统向量记忆 CLI 的局限，提供结构化的长期记忆管理能力。系统采用 Node.js 适配器 + FastAPI 引擎的混合架构，在本地环境实现完整的记忆生命周期管理。
核心能力详解
结构化记忆体系
系统定义四种记忆类型，模拟人类认知结构：
- Episodic（情景记忆）：对话会话、经历事件
- Semantic（语义记忆）：事实知识、概念关系
- Belief（信念记忆）：Agent 形成的判断与观点
- Goal（目标记忆）：活跃任务与追踪目标
智能检索与重排序
实体感知检索机制能够理解查询中的实体引用，结合相关性分数进行智能重排序，确保返回最相关的上下文片段。
热工作内存机制
维护活跃的"工作记忆"缓冲区，快速响应高频访问内容，减少重复检索开销。
背景认知处理
独立运行的后台进程持续执行：
- 反思（Reflection）：提炼模式与洞察
- 整合（Consolidation）：压缩冗余记忆
- 衰减（Decay）：降低陈旧记忆权重
- 冲突解决：调和矛盾信念
技术实现亮点
Token 边界提示词合成
严格受限的提示词组装策略，确保记忆注入不会超出模型上下文窗口，避免截断导致的语义断裂。
可靠性保障设计
- 健康检查门控：每次工具调用前强制校验
/health端点 - 离线队列机制：服务端不可达时自动写入
.memory_retry_queue.json，恢复后自动刷新 - 序列化提交保护：嵌入计算密集型操作串行执行，保护本地 CPU 资源
OpenClaw 原生集成（v2.5）
提供专用钩子函数包：
createSmartMemorySkill()- 技能实例化createOpenClawHooks()- 生命周期钩子（beforeModelResponse,onTurn,onSessionEnd）- 会话弧（Session Arc）自动捕获：每 20 轮对话生成摘要，持久化为情景记忆
工具接口
| 工具 | 功能 |
|------|------|
| `memory_search` | 查询长期记忆，支持类型过滤与相关性阈值 |
| `memory_commit` | 显式持久化重要信息，含自动标签与离线队列 |
| `memory_insights` | 获取背景认知产生的待处理洞察 |
被动上下文注入
通过 inject_active_context 在模型响应前注入标准化上下文块，包含：活跃项目、待解决问题、置顶事项、待处理洞察。配合基础提示词引导 Agent 自然 surfaced 相关洞察。
局限性与注意事项
硬件依赖
- 仅限 CPU 运行：强制使用 PyTorch CPU 版本，不支持 GPU 加速
- 本地嵌入计算存在吞吐量瓶颈，大型会话可能出现延迟
部署复杂度
需同时维护 Python 环境（FastAPI + PyTorch）与 Node.js 运行时，Docker/WSL 环境需特别注意安装顺序
记忆质量依赖
摘要质量直接影响检索效果，需配置可靠的 summarizeWithLLM 实现；自动标签启发式规则有限，关键记忆建议手动指定标签
适用场景
- 需要跨会话长期记忆的个性化 Agent
- 复杂多轮对话任务的上下文保持
- 需要信念追踪与目标管理的自主 Agent 系统
- 对数据隐私敏感、要求本地部署的场景
潜在风险
- 资源占用：后台认知进程持续消耗 CPU，低功耗设备需谨慎
- 记忆漂移：自动衰减与整合可能误删重要信息，关键记忆建议提高
importance分数 - 版本锁定：v2 已移除旧版 CLI 兼容层，升级需完整迁移