Openclaw Semantic Memory

核心用法

semantic-memory是OpenClaw框架的本地语义记忆插件，通过向量搜索技术实现智能信息存储与检索。安装后提供三个核心工具：

• memory_store: 保存结构化记忆，支持分类标签
• memory_search: 基于语义相似度的向量检索，自动召回相关上下文
• memory_forget: 按ID或语义查询删除记忆

配置模式

插件支持三种运行模式：
1. 内存模式（零配置）：数据易失，重启清空
2. 持久化模式（默认）：数据保存至~/.openclaw-memory/
3. Qdrant模式：连接外部向量数据库服务器

关键特性

• 自动记忆捕获（默认关闭）：智能识别对话中的偏好、决策、事实并存储
• 上下文感知召回：对话中自动注入相关历史记忆
• 本地运行：使用Xenova/all-MiniLM-L6-v2模型生成768维向量嵌入，无需云端服务

显著优点

1. 完全本地化：零API成本，无网络依赖（首次下载25MB模型后）
2. 隐私优先设计：PII保护默认启用，自动跳过含邮箱/电话的文本
3. 灵活部署：从个人开发到生产环境的Qdrant集群均可适配
4. 语义理解：基于Transformer的嵌入优于关键词匹配，支持概念级相似检索

潜在缺点与局限性

• 冷启动成本：首次运行需下载模型，可能需编译原生依赖（sharp、onnxruntime）
• 存储开销：向量数据相比原始文本膨胀约10-20倍
• 无跨设备同步：纯本地方案缺乏原生云端同步机制
• 模型能力边界：MiniLM对复杂语义关系和长文本理解有限
• Qdrant依赖：持久化方案引入额外基础设施复杂度

适合人群

• 注重隐私的AI应用开发者
• 需要长期上下文记忆的个人助理场景
• 离线/内网环境的OpenClaw用户
• 对API调用成本敏感的项目

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| PII泄露 | autoCapture误捕获敏感信息 | 保持`allowPIICapture: false`（默认） |

| 数据持久化风险 | 磁盘存储可能被其他程序读取 | 使用内存模式或加密存储路径 |

| 供应链风险 | Hugging Face模型下载、npm依赖 | 验证模型哈希，锁定依赖版本 |

| Qdrant传输安全 | 外部服务器模式存在中间人风险 | 启用TLS，使用可信私有网络 |

| 记忆污染 | 错误记忆被反复召回强化 | 定期使用memory_forget清理 |

技术架构

用户输入 → Transformer.js嵌入 → Qdrant向量检索 → 相似度排序 → 上下文注入

采用ES6工厂函数模式，便于测试和依赖注入。向量维度768，默认余弦相似度度量。

核心用法

semantic-memory 是 OpenClaw 生态中的本地语义记忆插件，专为需要跨会话保留对话上下文的 AI 代理设计。该插件基于 Transformers.js 和 Qdrant 向量数据库构建，通过 memory_store、memory_search、memory_forget 三个核心工具实现信息的存储、语义检索与删除。

工作模式：

• 内存模式（persistToDisk: false）：零配置启动，数据随进程重启清空
• 磁盘持久化（默认）：数据保存至 ~/.openclaw-memory/，支持长期记忆
• 外部 Qdrant：可对接自托管或云端的 Qdrant 服务器

关键特性：首次运行自动从 Hugging Face 下载约 25MB 的 Xenova/all-MiniLM-L6-v2 嵌入模型，后续完全离线运行。

显著优点

| 维度 | 表现 |

|------|------|

| **隐私安全** | 完全本地架构，零外部 API 调用；PII 检测机制默认过滤邮箱/电话；自动捕获功能默认关闭 |

| **易用性** | 即装即用，无需 API 密钥配置；OpenClaw 插件生态原生集成 |

| **灵活性** | 三级存储模式（内存/磁盘/外部向量库）；支持自定义存储路径和语义触发规则 |

| **合规性** | 通过 GDPR/CCPA 合规检测，数据最小化原则实现 |

潜在局限

1. 初始下载依赖：首次使用需联网下载 25MB 模型，网络受限环境需手动部署
2. 计算资源占用：本地嵌入推理需消耗 CPU/GPU 资源，大规模记忆集可能影响响应延迟
3. 存储隔离：默认单用户目录存储，多用户共享环境需显式配置 storagePath
4. 模型单一性：当前仅支持固定嵌入模型，无法切换至更高性能或特定领域模型

适合人群

• 隐私敏感用户：拒绝云端记忆服务、要求数据完全本地化处理
• 企业合规场景：需满足数据不出域、审计追溯要求的内部 AI 系统
• 长期协作代理：需要跨任务、跨会话维持用户偏好与上下文的智能体
• 离线/内网环境：无法访问 OpenAI/Cohere 等云端嵌入 API 的封闭网络

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| PII 意外捕获 | 低 | 默认过滤机制有效，但 `allowPIICapture: true` 时可能泄露敏感信息 |

| 路径遍历攻击 | 低 | 建议增强 `storagePath` 规范化校验（当前依赖用户配置） |

| 模型完整性 | 低 | 缺乏下载后哈希校验，存在供应链篡改理论可能 |

| 数据未加密 | 中 | 磁盘存储为明文 JSON，敏感场景建议自行加密 |

生产建议：保持默认配置（autoCapture: false），定期备份 ~/.openclaw-memory/ 目录，敏感行业启用磁盘加密或选择内存模式。